industrial-scanner
ICS/OT cybersecurity scanner — Modbus, S7Comm & DNP3. Passive PCAP analysis + safe read-only Modbus scans. JSON/HTML reports + executive dashboards.
- 17
- Python
- MIT
- 6 wk ago
🔍 零依赖·本地优先的局域网资产普查与暴露面自查 CLI | Privacy-first LAN asset census & exposure self-audit (Python stdlib only)
Repo gitstq/LocalCensus, read from GitHub 1 min ago. gitstq has not joined Take My Repo.
gitstq/LocalCensus is a public repo on GitHub by gitstq. 🔍 零依赖·本地优先的局域网资产普查与暴露面自查 CLI | Privacy-first LAN asset census & exposure self-audit (Python stdlib only). It declares the MIT license on GitHub. It is written mainly in Python, has 0 stars and last changed on 2026-11-07. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
零依赖 · 本地优先的局域网资产普查与暴露面自查工具
你无法保护你看不见的东西。先弄清楚自己的网段里到底有什么。
LocalCensus 是一个用 Python 标准库写成的命令行工具,用来回答三个非常具体的问题:
近期开源社区里「本地网络、无需云账户」的设备管理项目(如 Home Assistant 生态中的局域网设备集成)很受欢迎。它们解决的是「怎么控制设备」,但在此之前还有一个更容易被忽略的问题:很多人根本不知道自己网段里跑着什么——一台忘了关调试端口的 NAS、一台默认无密码的 Redis、一个暴露在 HTTP 上的路由器管理页。
LocalCensus 只借鉴了「本地优先、隐私优先」这一产品理念,代码 100% 独立自研,不做设备控制、不实现任何厂商协议,而是把精力放在资产盘点 + 暴露面自查 + 快照差异上。
| 😣 痛点 | ✅ LocalCensus 的做法 |
|---|---|
nmap 功能强大但对新手太重,且默认行为容易越界 |
只做温和的 TCP connect 探测,默认只允许私有地址 |
| 运维脚本散落各处,结果没法沉淀和对比 | 一次扫描生成结构化 JSON 快照,可存档、可 diff |
| 知道端口开着,却不知道「这算不算问题」 | 内置 21 条自查规则,直接给出风险等级 + 整改建议 |
| 云资产盘点工具要把数据上传到第三方 | 全程本地运行,零遥测、零外传 |
| 装个工具要拖一堆依赖 | 零第三方依赖,pip install 完即用 |
nmap、无 scapy、无 requests。severity、说明和具体整改命令方向,而不是只报一个端口号。diff 子命令直接告诉你「新出现的设备」和「新暴露的端口」。ThreadPoolExecutor,默认 32 并发、300ms 单端口超时,可按需调整;对网段温和。Server 头、页面 <title>、服务 banner 与端口提示,推断设备类别(Router/Gateway、NAS、IP Camera、Printer、Datastore…)。--format table|json|csv|md,--output 自动按扩展名推断格式。NO_COLOR 与 LOCALCENSUS_COLOR=0。localcensus demo 用内置合成数据跑通全流程,不打开任何 socket,适合 CI、教学与文档演示。| 项目 | 要求 |
|---|---|
| 🐍 Python | 3.8 及以上(已在 3.11 验证) |
| 🔧 Git | 仅从源码安装时需要 |
| 📦 第三方依赖 | 无 |
| 🖥️ 操作系统 | Windows / macOS / Linux 均可 |
| 🌐 网络 | 只需能访问你自己的局域网 |
git clone https://github.com/gitstq/LocalCensus.git cd LocalCensus pip install -e .
或者不安装、直接从源码运行(便于二次开发):
export PYTHONPATH="$PWD:$PYTHONPATH" # Windows PowerShell: $env:PYTHONPATH = "$PWD" python -m localcensus demo
# 1️⃣ 扫描自己的网段,生成报告 + 可存档的 JSON 快照 localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --format md --output report.md --snapshot snapshots/today.json # 2️⃣ 第二天再扫一次,对比资产漂移 localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --snapshot snapshots/tomorrow.json localcensus diff snapshots/today.json snapshots/tomorrow.json \ --format md --output drift.md # 3️⃣ 没网 / 不想真的扫描?跑离线演示 localcensus demo
localcensus version localcensus rules
⚠️ 合法使用提示:LocalCensus 只应用于你拥有或已获授权的网络。默认会拒绝非私有地址;
--allow-public仅供自有公网资产自查使用,滥用风险自负。
| 子命令 | 作用 |
|---|---|
scan |
扫描目标并生成资产清单 + 风险报告 |
report |
重新渲染一个已保存的 JSON 快照 |
diff |
对比两份快照,输出漂移报告 |
demo |
离线演示(合成数据,不开 socket) |
rules |
列出全部内置指纹与风险规则 |
version |
输出版本与运行时信息 |
scan 常用参数| 参数 | 默认值 | 说明 |
|---|---|---|
--target |
必填 | 单 IP、IPv4 CIDR,或逗号分隔列表,如 192.168.1.10,192.168.1.20 |
--top-ports N |
32 |
扫描内置常见端口表的前 N 个(共 74 个) |
--ports |
— | 自定义端口,支持范围:22,80,8000-8010 |
--timeout MS |
300 |
单端口连接超时(毫秒) |
--concurrency N |
32 |
最大并发探测数(硬上限 256) |
--max-hosts N |
256 |
CIDR 展开后的主机数上限(硬上限 1024) |
--no-http |
关闭 | 跳过 HTTP 指纹抓取,只做 TCP 连通性判断 |
--keep-unresponsive |
关闭 | 保留无开放端口的主机 |
--dry-run |
关闭 | 只打印扫描计划,不建立任何连接 |
--allow-public |
关闭 | 解除「仅私有地址」保护(请谨慎) |
--format |
table |
table / json / csv / md |
--output, -o |
— | 报告写入文件;未指定 --format 时按扩展名自动推断 |
--snapshot |
— | 额外写出完整 JSON 快照,供 diff 使用 |
--verbose |
关闭 | 向 stderr 打印进度 |
① 只想快速看一眼某台机器开了什么
localcensus scan --target 192.168.1.20 --ports 22,80,443,445,5000,8080
② 先确认计划、再真正执行(安全习惯)
localcensus scan --target 192.168.1.0/28 --top-ports 16 --dry-run localcensus scan --target 192.168.1.0/28 --top-ports 16 --snapshot day1.json
③ 把结果接进自己的脚本 / CI
localcensus scan --target 10.0.0.0/29 --format json --snapshot out.json --output out.json
python -c "import json; d=json.load(open('out.json')); print(d['summary']['risk_score'])"④ 生成给同事看的 Markdown 报告
localcensus report out.json --format md --output report.md
⑤ 导出 CSV 做表格分析
localcensus report out.json --format csv --output assets.csv
NO_COLOR复制 .env.example 为 .env 即可覆盖默认值(也可用同名环境变量):
LOCALCENSUS_TIMEOUT=500 # 单端口超时 500ms LOCALCENSUS_CONCURRENCY=16 # 降低并发,对老旧设备更友好 LOCALCENSUS_MAX_HOSTS=64 # 收紧主机上限 LOCALCENSUS_COLOR=0 # 禁用彩色输出(NO_COLOR=1 同样生效)
工具不读取任何凭据类配置,.env 里只有数值与开关。
🔍 LocalCensus 局域网资产普查 v1.0.0
📊 概览
主机 4 · 开放服务 9 · 风险项 8 · 风险评分 64/100(等级 F)
● CRITICAL 1 ● HIGH 2 ● MEDIUM 3 ● LOW 0 ● INFO 2
🖥️ 资产清单
192.168.1.1 Router/Gateway 80 OpenWrt LuCI, 22 SSH
192.168.1.20 NAS 5000 Synology DSM, 445 SMB
192.168.1.33 Datastore 22 SSH, 3306 MySQL, 8080 Grafana, 6379 Redis
192.168.1.50 IP Camera 80 Hikvision
⚠️ 暴露面风险
CRITICAL 192.168.1.33 :6379 LC-002 Redis 直接监听局域网
HIGH 192.168.1.20 :445 LC-008 SMB/NetBIOS 文件共享暴露
📷 运行截图 / 演示动图占位:可把
localcensus demo的终端输出截图放在docs/screenshot.png,并在 README 中引用。本项目为保证仓库轻量,暂以文字示例代替。
| ❓ 问题 | 💡 处理 |
|---|---|
提示 refusing to scan non-private address |
目标不是私有地址。确认目标无误后,仅对自己拥有的网络加 --allow-public |
| 结果里没有某台设备 | 增大 --top-ports / 用 --ports 指定端口、提高 --timeout、或加 --keep-unresponsive |
| 扫描太慢 | 降低 --top-ports,或减小 --timeout;并发已是上限时先缩小 CIDR |
| 彩色输出变成乱码 | 设置 NO_COLOR=1 或 LOCALCENSUS_COLOR=0 |
Windows 上没有 ip neigh |
工具会自动回退到 arp -a,MAC 识别为尽力而为,不影响主流程 |
localcensus/
├── cli.py # argparse 子命令编排、参数校验、错误码
├── config.py # 环境变量 / .env 读取(纯数值配置,无密钥)
├── net.py # 目标解析、安全围栏、有界并发 TCP 探测、ARP 邻居表
├── fingerprint.py # 规则化服务指纹 + 设备类别推断
├── risk.py # 暴露面自查规则、去重、排序
├── models.py # dataclass 数据契约、风险评分与等级
├── report.py # 终端 / JSON / CSV / Markdown 四种渲染
├── diff.py # 快照差异计算与 Markdown 渲染
└── demo.py # 离线合成数据(测试与演示共用)
数据流严格单向:net → fingerprint → risk → report/diff,每个模块都可单独 import 与单测。
| 选择 | 原因 |
|---|---|
| 纯标准库 | 避免依赖安装失败、避免供应链风险;pip install -e . 后到处能跑 |
socket.create_connection 而非原始报文 |
只判断「端口是否接受连接」,不构造数据包,行为可预测、对网络温和 |
| 规则表而非机器学习 | 结果可解释、可审计、可离线复现,用户能直接用 localcensus rules 查看依据 |
| dataclass + JSON 快照 | 结构化、易 diff、易被其他工具消费 |
ThreadPoolExecutor |
网络 I/O 密集型,线程足够;subprocess 与 socket 都是阻塞型标准库调用 |
--allow-public 且会二次警告;GET /,用于读取 Server 头与 <title>;--rules myrules.json),让用户补充自家设备;--fail-on CRITICAL 便于 CI 卡口);新增设备指纹规则、补充风险规则与整改建议、改进跨平台 ARP 解析、翻译校对,都非常欢迎。
按发布规范,LocalCensus 属于「脚本 / 工具库 / CLI」类项目:无需生成 Windows / macOS / Linux 三平台可执行文件,也不上传 GitHub Release 附件;安装、引入、集成、使用的完整步骤写在本 README 中即可。因此本仓库不在首页放置 Release 下载入口。
bash scripts/build.sh # Linux / macOS:wheel + sdist + SHA256SUMSWindows(PowerShell):
.\scripts\build.ps1
产物位于 dist/:
localcensus-1.0.0-py3-none-any.whl
localcensus-1.0.0.tar.gz
SHA256SUMS
pip install dist/localcensus-1.0.0-py3-none-any.whl localcensus version
bash scripts/test.sh # 66 个标准库 unittest,无需 pytest bash scripts/dev.sh demo # 免安装运行离线演示 bash scripts/dev.sh rules PYTHONPATH=. python -m localcensus scan --target 127.0.0.1 --ports 22,80 --dry-run
main 分支代码完整,可直接 git clone 后运行pyproject.toml / setup.py / .gitignore / .env.example 齐备localcensus --help、version、rules、demo 均可正常执行main 建分支,命名如 feat/mdns-discovery、fix/arp-windows。feat: ... / fix: ... / docs: ... / refactor: ... / test: ...。bash scripts/test.sh 全部通过。CHANGELOG.md。Server 头、title 或 banner 样例(请先脱敏)。详见 CONTRIBUTING.md。
本项目采用 MIT License,详见 LICENSE。
⚖️ 免责声明:LocalCensus 仅用于你自有或已获书面授权的网络资产自查。作者不对误用、未授权扫描或依据报告所做配置变更造成的任何后果负责。工具不会帮你绕过认证、不会攻击任何设备。
零依賴 · 本地優先的區域網路資產普查與曝露面自我檢核工具
你看不見的東西,就無從保護。先弄清楚自己的網段裡到底有什麼。
LocalCensus 是一支以 Python 標準函式庫寫成的命令列工具,專門回答三個很具體的問題:
近期開源社群中「本地網路、無須雲端帳號」的設備管理專案(例如 Home Assistant 生態系中的區網設備整合)相當受歡迎。它們處理的是「如何控制設備」,但在此之前還有一個更容易被忽略的問題:多數人根本不知道自己網段裡跑著什麼——一台忘了關除錯埠的 NAS、一台預設無密碼的 Redis、一個跑在明文 HTTP 上的路由器管理頁。
LocalCensus 只借鏡「本地優先、隱私優先」這項產品理念,程式碼 100% 獨立自研,不做設備控制、不實作任何廠商協定,而是專注在資產盤點 + 曝露面檢核 + 快照差異。
| 😣 痛點 | ✅ LocalCensus 的做法 |
|---|---|
nmap 功能強大,但對新手太重,預設行為也容易越界 |
只做溫和的 TCP connect 探測,預設只允許私有位址 |
| 維運腳本四散,結果無法沉澱與比較 | 一次掃描產生結構化 JSON 快照,可保存、可 diff |
| 知道埠開著,卻不知道「這算不算問題」 | 內建 21 條檢核規則,直接給出風險等級 + 改善建議 |
| 雲端資產盤點工具得把資料上傳第三方 | 全程本機執行,零遙測、零外傳 |
| 裝個工具要拖一堆依賴 | 零第三方依賴,pip install 完即可用 |
nmap、scapy、requests。severity、說明與具體改善方向,而不是只丟一個埠號。diff 直接告訴你「新出現的設備」與「新曝露的連接埠」。ThreadPoolExecutor 實作,預設 32 並行、單埠 300ms 逾時,可依需求調整,對網段溫和。Server 標頭、頁面 <title>、服務 banner 與連接埠提示,推斷設備類別(Router/Gateway、NAS、IP Camera、Printer、Datastore…)。--format table|json|csv|md,--output 會依副檔名自動推斷格式。NO_COLOR 與 LOCALCENSUS_COLOR=0。localcensus demo 以內建合成資料跑完全流程,不開啟任何 socket,適合 CI、教學與文件展示。| 項目 | 需求 |
|---|---|
| 🐍 Python | 3.8 以上(已於 3.11 驗證) |
| 🔧 Git | 僅從原始碼安裝時需要 |
| 📦 第三方依賴 | 無 |
| 🖥️ 作業系統 | Windows / macOS / Linux 皆可 |
| 🌐 網路 | 只需能存取你自己的區域網路 |
git clone https://github.com/gitstq/LocalCensus.git cd LocalCensus pip install -e .
也可以不安裝、直接從原始碼執行(方便二次開發):
export PYTHONPATH="$PWD:$PYTHONPATH" # Windows PowerShell: $env:PYTHONPATH = "$PWD" python -m localcensus demo
# 1️⃣ 掃描自己的網段,產生報告 + 可保存的 JSON 快照 localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --format md --output report.md --snapshot snapshots/today.json # 2️⃣ 隔天再掃一次,比對資產漂移 localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --snapshot snapshots/tomorrow.json localcensus diff snapshots/today.json snapshots/tomorrow.json \ --format md --output drift.md # 3️⃣ 沒網路 / 不想真的掃?跑離線展示 localcensus demo
localcensus version localcensus rules
⚠️ 合法使用提醒:LocalCensus 僅應用于你擁有或已取得授權的網路。預設會拒絕非私有位址;
--allow-public僅供自有公開資產自我檢核,濫用風險自負。
| 子命令 | 用途 |
|---|---|
scan |
掃描目標並產生資產清單 + 風險報告 |
report |
重新渲染一份已保存的 JSON 快照 |
diff |
比對兩份快照,輸出漂移報告 |
demo |
離線展示(合成資料,不開 socket) |
rules |
列出全部內建指紋與風險規則 |
version |
輸出版本與執行環境資訊 |
scan 常用參數| 參數 | 預設值 | 說明 |
|---|---|---|
--target |
必填 | 單一 IP、IPv4 CIDR,或逗號分隔清單,如 192.168.1.10,192.168.1.20 |
--top-ports N |
32 |
掃描內建常見埠表前 N 個(共 74 個) |
--ports |
— | 自訂連接埠,支援範圍:22,80,8000-8010 |
--timeout MS |
300 |
單埠連線逾時(毫秒) |
--concurrency N |
32 |
最大並行探測數(硬上限 256) |
--max-hosts N |
256 |
CIDR 展開後的主機數上限(硬上限 1024) |
--no-http |
關閉 | 略過 HTTP 指紋抓取,只判斷 TCP 連通性 |
--keep-unresponsive |
關閉 | 保留無開放埠的主機 |
--dry-run |
關閉 | 只印出掃描計畫,不建立任何連線 |
--allow-public |
關閉 | 解除「僅私有位址」保護(請謹慎) |
--format |
table |
table / json / csv / md |
--output, -o |
— | 報告寫入檔案;未指定 --format 時依副檔名自動推斷 |
--snapshot |
— | 額外寫出完整 JSON 快照,供 diff 使用 |
--verbose |
關閉 | 將進度輸出到 stderr |
① 只想快速看某台機器開了什麼
localcensus scan --target 192.168.1.20 --ports 22,80,443,445,5000,8080
② 先確認計畫、再真正執行(安全習慣)
localcensus scan --target 192.168.1.0/28 --top-ports 16 --dry-run localcensus scan --target 192.168.1.0/28 --top-ports 16 --snapshot day1.json
③ 接進自己的腳本 / CI
localcensus scan --target 10.0.0.0/29 --format json --output out.json
python -c "import json; d=json.load(open('out.json')); print(d['summary']['risk_score'])"④ 產生給同事看的 Markdown 報告
localcensus report out.json --format md --output report.md
NO_COLOR把 .env.example 複製為 .env 即可覆蓋預設值(同名環境變數亦可):
LOCALCENSUS_TIMEOUT=500 # 單埠逾時 500ms LOCALCENSUS_CONCURRENCY=16 # 降低並行,對老舊設備更友善 LOCALCENSUS_MAX_HOSTS=64 # 收緊主機上限 LOCALCENSUS_COLOR=0 # 停用彩色輸出(NO_COLOR=1 同樣生效)
工具不讀取任何憑證類設定,.env 裡只有數值與開關。
🔍 LocalCensus 區域網路資產普查 v1.0.0
📊 概覽
主機 4 · 開放服務 9 · 風險項 8 · 風險評分 64/100(等級 F)
🖥️ 資產清單
192.168.1.1 Router/Gateway 80 OpenWrt LuCI, 22 SSH
192.168.1.20 NAS 5000 Synology DSM, 445 SMB
192.168.1.33 Datastore 22 SSH, 3306 MySQL, 6379 Redis, 8080 Grafana
⚠️ 曝露面風險
CRITICAL 192.168.1.33 :6379 LC-002 Redis 直接監聽區域網路
HIGH 192.168.1.20 :445 LC-008 SMB/NetBIOS 檔案分享曝露
📷 執行截圖 / 展示動圖預留位:可將
localcensus demo的終端輸出存為docs/screenshot.png,再以引用。為保持倉庫輕量,目前以文字範例代替。
| ❓ 問題 | 💡 處理方式 |
|---|---|
出現 refusing to scan non-private address |
目標不是私有位址。確認無誤後,僅對自有網路加 --allow-public |
| 結果少了某台設備 | 提高 --top-ports、用 --ports 指定埠、加大 --timeout,或加 --keep-unresponsive |
| 掃描太慢 | 降低 --top-ports 或縮小 --timeout;並行已達上限時先縮小 CIDR |
| 彩色輸出變亂碼 | 設定 NO_COLOR=1 或 LOCALCENSUS_COLOR=0 |
Windows 沒有 ip neigh |
工具會自動退回 arp -a;MAC 辨識為盡力而為,不影響主流程 |
localcensus/
├── cli.py # argparse 子命令編排、參數驗證、錯誤碼
├── config.py # 環境變數 / .env 讀取(純數值設定,無金鑰)
├── net.py # 目標解析、安全圍欄、有界並行 TCP 探測、ARP 鄰居表
├── fingerprint.py # 規則化服務指紋 + 設備類別推斷
├── risk.py # 曝露面檢核規則、去重、排序
├── models.py # dataclass 資料契約、風險評分與等級
├── report.py # 終端 / JSON / CSV / Markdown 四種渲染
├── diff.py # 快照差異計算與 Markdown 渲染
└── demo.py # 離線合成資料(測試與展示共用)
資料流嚴格單向:net → fingerprint → risk → report/diff,每個模組都能單獨 import 與單測。
| 選擇 | 原因 |
|---|---|
| 純標準函式庫 | 避免依賴安裝失敗與供應鏈風險;pip install -e . 後到處能跑 |
socket.create_connection 而非原始封包 |
只判斷「連接埠是否接受連線」,不構造封包,行為可預期、對網路溫和 |
| 規則表而非機器學習 | 結果可解釋、可稽核、可離線重現,使用者可直接用 localcensus rules 查看依據 |
| dataclass + JSON 快照 | 結構化、易 diff、易被其他工具取用 |
ThreadPoolExecutor |
網路 I/O 密集,執行緒已足夠;subprocess 與 socket 皆為阻塞式標準函式庫呼叫 |
--allow-public 且會二次警告;GET /,用於讀取 Server 標頭與 <title>;--rules myrules.json),讓使用者補充自家設備;--fail-on CRITICAL 便於 CI 卡關);新增設備指紋規則、補齊風險規則與改善建議、改進跨平台 ARP 解析、翻譯校對,都非常歡迎。
依發布規範,LocalCensus 屬於「腳本 / 工具庫 / CLI」類專案:無須產生 Windows / macOS / Linux 三平台執行檔,也不上傳 GitHub Release 附件;安裝、引入、整合、使用的完整步驟寫在本 README 即可。因此本倉庫不在首頁放置 Release 下載入口。
bash scripts/build.sh # Linux / macOS:wheel + sdist + SHA256SUMSWindows(PowerShell):
.\scripts\build.ps1
產出位於 dist/:
localcensus-1.0.0-py3-none-any.whl
localcensus-1.0.0.tar.gz
SHA256SUMS
pip install dist/localcensus-1.0.0-py3-none-any.whl localcensus version
bash scripts/test.sh # 66 個標準函式庫 unittest,不需 pytest bash scripts/dev.sh demo # 免安裝執行離線展示 bash scripts/dev.sh rules PYTHONPATH=. python -m localcensus scan --target 127.0.0.1 --ports 22,80 --dry-run
main 分支程式碼完整,可直接 git clone 後執行pyproject.toml / setup.py / .gitignore / .env.example 齊備localcensus --help、version、rules、demo 皆可正常執行main 建立分支,命名如 feat/mdns-discovery、fix/arp-windows。feat: ... / fix: ... / docs: ... / refactor: ... / test: ...。bash scripts/test.sh。CHANGELOG.md。Server 標頭、title 或 banner 範例(請先去識別化)。詳見 CONTRIBUTING.md。
本專案採用 MIT License,詳見 LICENSE。
⚖️ 免責聲明:LocalCensus 僅用於你自有或已取得書面授權的網路資產自我檢核。作者不對誤用、未授權掃描或依據報告所做任何設定變更之後果負責。工具不會協助繞過認證,也不會攻擊任何設備。
Zero-dependency, local-first LAN asset census and exposure self-audit
You cannot protect what you cannot see. Start by finding out what is actually on your network.
LocalCensus is a command-line tool built entirely on the Python standard library. It answers three very concrete questions:
"Local-first, no cloud account required" device projects (for example LAN integrations in the Home Assistant ecosystem) have been getting a lot of attention lately. They solve how to control a device. But an earlier question is even easier to overlook: most people have no idea what is actually running on their own subnet — a NAS with a debug port left open, a Redis instance with no password, a router admin page served over plain HTTP.
LocalCensus borrows only the local-first, privacy-first product idea. The code is 100% independently written: it does not control devices, implements no vendor protocol, and focuses instead on asset inventory + exposure self-audit + snapshot drift.
| 😣 Problem | ✅ LocalCensus approach |
|---|---|
nmap is powerful but heavy for beginners, and easy to point somewhere you shouldn't |
Gentle TCP connect probes only, private addresses only by default |
| Ad-hoc scripts produce results you cannot store or compare | One scan produces a structured JSON snapshot you can archive and diff |
| You know a port is open but not whether that is a problem | 21 built-in checks with a severity and a concrete remediation |
| Cloud inventory tools require uploading your data to a third party | Runs entirely locally — zero telemetry, zero exfiltration |
| Installing a small utility pulls in a dependency tree | Zero third-party dependencies |
nmap, no scapy, no requests.severity, an explanation and a specific remediation direction, not just a port number.diff tells you exactly which devices and which ports are new.ThreadPoolExecutor, 32 workers and a 300 ms per-port timeout by default; gentle on the network.Server header, the page <title>, service banners and port hints to infer a device category (Router/Gateway, NAS, IP Camera, Printer, Datastore…).--format table|json|csv|md; --output infers the format from the file extension.NO_COLOR and LOCALCENSUS_COLOR=0.localcensus demo runs the entire pipeline on synthetic data without opening a single socket; ideal for CI, teaching and docs.| Item | Requirement |
|---|---|
| 🐍 Python | 3.8+ (verified on 3.11) |
| 🔧 Git | Only needed when installing from source |
| 📦 Third-party packages | None |
| 🖥️ OS | Windows / macOS / Linux |
| 🌐 Network | Only needs reachability to your own LAN |
git clone https://github.com/gitstq/LocalCensus.git cd LocalCensus pip install -e .
Or run straight from source without installing:
export PYTHONPATH="$PWD:$PYTHONPATH" # Windows PowerShell: $env:PYTHONPATH = "$PWD" python -m localcensus demo
# 1️⃣ Scan your subnet, write a report plus an archivable JSON snapshot localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --format md --output report.md --snapshot snapshots/today.json # 2️⃣ Scan again tomorrow and compare the drift localcensus scan --target 192.168.1.0/24 --top-ports 32 \ --snapshot snapshots/tomorrow.json localcensus diff snapshots/today.json snapshots/tomorrow.json \ --format md --output drift.md # 3️⃣ Offline / no real scan needed? Run the demo localcensus demo
localcensus version localcensus rules
⚠️ Legal use: LocalCensus is for networks you own or are explicitly authorised to assess. Non-private targets are refused by default;
--allow-publicexists solely for auditing your own public assets. Use it responsibly.
| Command | Purpose |
|---|---|
scan |
Probe targets and produce an inventory + risk report |
report |
Re-render a saved JSON snapshot |
diff |
Compare two snapshots and emit a drift report |
demo |
Offline demo (synthetic data, no sockets) |
rules |
List every built-in fingerprint and risk rule |
version |
Print version and runtime information |
scan options| Option | Default | Description |
|---|---|---|
--target |
required | Single IP, IPv4 CIDR, or comma-separated list, e.g. 192.168.1.10,192.168.1.20 |
--top-ports N |
32 |
Scan the first N entries of the built-in common-port table (74 total) |
--ports |
— | Custom ports, ranges supported: 22,80,8000-8010 |
--timeout MS |
300 |
Per-port connect timeout in milliseconds |
--concurrency N |
32 |
Maximum concurrent probes (hard cap 256) |
--max-hosts N |
256 |
Host cap after CIDR expansion (hard cap 1024) |
--no-http |
off | Skip HTTP fingerprinting, TCP connectivity only |
--keep-unresponsive |
off | Keep hosts with no open ports |
--dry-run |
off | Print the plan without opening any connection |
--allow-public |
off | Lift the private-address-only protection (use with care) |
--format |
table |
table / json / csv / md |
--output, -o |
— | Write the report to a file; format is inferred from the extension when omitted |
--snapshot |
— | Additionally write the full JSON snapshot for diff |
--verbose |
off | Print progress to stderr |
① Quick look at one machine
localcensus scan --target 192.168.1.20 --ports 22,80,443,445,5000,8080
② Plan first, execute second (a good habit)
localcensus scan --target 192.168.1.0/28 --top-ports 16 --dry-run localcensus scan --target 192.168.1.0/28 --top-ports 16 --snapshot day1.json
③ Feed the result into a script / CI
localcensus scan --target 10.0.0.0/29 --format json --output out.json
python -c "import json; d=json.load(open('out.json')); print(d['summary']['risk_score'])"④ Produce a Markdown report for colleagues
localcensus report out.json --format md --output report.md
NO_COLORCopy .env.example to .env to override defaults (plain environment variables work too):
LOCALCENSUS_TIMEOUT=500 # 500 ms per-port timeout LOCALCENSUS_CONCURRENCY=16 # gentler on older hardware LOCALCENSUS_MAX_HOSTS=64 # tighter host cap LOCALCENSUS_COLOR=0 # disable color (NO_COLOR=1 works too)
The tool never reads credential-type settings — .env contains numbers and switches only.
🔍 LocalCensus LAN asset census v1.0.0
📊 Overview
hosts 4 · open services 9 · findings 8 · risk score 64/100 (grade F)
● CRITICAL 1 ● HIGH 2 ● MEDIUM 3 ● LOW 0 ● INFO 2
🖥️ Inventory
192.168.1.1 Router/Gateway 80 OpenWrt LuCI, 22 SSH
192.168.1.20 NAS 5000 Synology DSM, 445 SMB
192.168.1.33 Datastore 22 SSH, 3306 MySQL, 8080 Grafana, 6379 Redis
192.168.1.50 IP Camera 80 Hikvision
⚠️ Exposure findings
CRITICAL 192.168.1.33 :6379 LC-002 Redis exposed on the LAN
HIGH 192.168.1.20 :445 LC-008 SMB/NetBIOS file sharing exposed
📷 Screenshot / demo GIF placeholder: save the terminal output of
localcensus demoasdocs/screenshot.pngand reference it with. To keep the repository lean, a text example is used for now.
| ❓ Symptom | 💡 Fix |
|---|---|
refusing to scan non-private address |
The target is not private. Double-check it, then add --allow-public only for a network you own |
| A device is missing from the results | Raise --top-ports, specify --ports, increase --timeout, or add --keep-unresponsive |
| Scanning is slow | Lower --top-ports or --timeout; narrow the CIDR if concurrency is already maxed |
| Color output shows escape codes | Set NO_COLOR=1 or LOCALCENSUS_COLOR=0 |
Windows has no ip neigh |
The tool falls back to arp -a; MAC detection is best-effort and does not affect the main flow |
localcensus/
├── cli.py # argparse subcommands, validation, exit codes
├── config.py # environment / .env loading (numeric settings only, no secrets)
├── net.py # target parsing, safety guardrails, bounded concurrent TCP probes, ARP table
├── fingerprint.py # rule-based service fingerprints and device categorisation
├── risk.py # exposure rules, de-duplication, ordering
├── models.py # dataclass contracts, risk score and grade
├── report.py # terminal / JSON / CSV / Markdown renderers
├── diff.py # snapshot diff and Markdown rendering
└── demo.py # offline synthetic data (shared by tests and demo)
Data flows strictly one way: net → fingerprint → risk → report/diff. Every module can be imported and unit-tested independently.
| Choice | Rationale |
|---|---|
| Standard library only | No dependency-install failures, no supply-chain surface; works right after pip install -e . |
socket.create_connection instead of raw packets |
Only answers "does this port accept a connection" — predictable behaviour, gentle on the network |
| Rule tables, not machine learning | Results are explainable, auditable and reproducible offline; localcensus rules shows the evidence |
| dataclass + JSON snapshots | Structured, easy to diff, easy for other tools to consume |
ThreadPoolExecutor |
Network I/O bound; threads are sufficient and socket/subprocess are blocking standard-library calls |
--allow-public plus a second warning;GET / to an already-open port, to read the Server header and <title>;--rules myrules.json) for home-lab specific devices;--fail-on CRITICAL) for CI gating;New device fingerprints, additional risk rules with better remediation text, cross-platform ARP improvements, and translation reviews are all very welcome.
Under the release policy, LocalCensus is a script / library / CLI project: it does not need Windows/macOS/Linux standalone executables and does not upload GitHub Release assets. Complete install, import, integration and usage instructions belong in this README — which is why there is no Release download badge at the top of the page.
bash scripts/build.sh # Linux / macOS: wheel + sdist + SHA256SUMSOn Windows (PowerShell):
.\scripts\build.ps1
Artifacts in dist/:
localcensus-1.0.0-py3-none-any.whl
localcensus-1.0.0.tar.gz
SHA256SUMS
pip install dist/localcensus-1.0.0-py3-none-any.whl localcensus version
bash scripts/test.sh # 66 standard-library unittests, pytest not required bash scripts/dev.sh demo # run the offline demo without installing bash scripts/dev.sh rules PYTHONPATH=. python -m localcensus scan --target 127.0.0.1 --ports 22,80 --dry-run
main branch is complete and runs directly after git clonepyproject.toml / setup.py / .gitignore / .env.example includedlocalcensus --help, version, rules and demo all workmain, e.g. feat/mdns-discovery, fix/arp-windows.feat: ... / fix: ... / docs: ... / refactor: ... / test: ....bash scripts/test.sh must pass.CHANGELOG.md.Server header, title or banner sample (redact it first).See CONTRIBUTING.md.
Released under the MIT License — see LICENSE.
⚖️ Disclaimer: LocalCensus is intended solely for auditing networks you own or are explicitly authorised in writing to assess. The author is not responsible for misuse, unauthorised scanning, or any configuration changes made on the basis of a report. The tool does not bypass authentication and does not attack any device.
gitstq/LocalCensus is a public repo on GitHub by gitstq. 🔍 零依赖·本地优先的局域网资产普查与暴露面自查 CLI | Privacy-first LAN asset census & exposure self-audit (Python stdlib only).
It declares the MIT license on GitHub.
Its maker tagged it for macOS, Windows and Linux, or as Docker or cross-platform. That is declared by the maker; Take My Repo has not tested it.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-07. GitHub counts 0 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
ICS/OT cybersecurity scanner — Modbus, S7Comm & DNP3. Passive PCAP analysis + safe read-only Modbus scans. JSON/HTML reports + executive dashboards.
Reverse engineer anything with agents, from app behavior down to native binaries.
A collection of quick starters for ansible, kubernetes, docker, linux, windows, and more. Great for HomeLabs!

A list of Free Software network services and web applications which can be hosted on your own servers
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.

Bring your homelab to life. A self-hosted IPAM and service mapper that visualizes complex hardware, compute, and network relationships in real-time.
ADB 驱动的 Android 虚拟定位 CLI:常驻推送、坐标系统一换算、GPX 轨迹回放。零 npm 依赖,无需 root。
BlueEagle AI Gateway | 蓝鹰AI网关 - Cheapest AI API Gateway | 0.09x cost | 1:1 recharge | GPT-4o Claude Gemini DeepSeek | OpenAI compatible | 最便宜AI中转站
Cheapest AI API Gateway | GPT-4o/Claude/Gemini at 0.09x cost | 1:1 CNY:USD recharge | 100% official pool | OpenAI compatible | ahg.codes
🔬 HexScope — 零依赖·离线优先的二进制文件取证探查工具箱 | Zero-dependency binary forensics workbench: hex dump, magic detection, entropy, strings, histogram, binary diff & file carving
🔭 零依赖 · 离线优先的 A2A(Agent2Agent)协议一致性审计与互操作性探针引擎:36 条规则、4 种报告格式、CI 门禁就绪
🛡️ AgentCubicle — 零依赖·离线优先的 AI Agent 隔离工作区、动作前置授权与防篡改审计引擎 | Zero-dependency isolated workspaces, pre-action authorization & tamper-evident audit for AI agents
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/gitstq/LocalCensusTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.