tjnull/leetha

**Leetha 通过分析广播流量和协议交换来识别您网络上的设备** —— 结合被动观察与主动服务探测，以构建全面的设备清单、检测异常并映射您的攻击面。无需代理，无需凭证，无需设备配合。 ## 为什么选择 Leetha - **被动优先设计** —— 无需发送任何数据包即可识别设备；主动探测是可选的 - **多证据融合** —— 跨 15 个以上协议源的加权确定性评分，当独立源相互佐证时进行一致性增强 - **30 个协议 Banner 匹配器** —— 从观察到的流量中被动读取服务 Banner（SSH, MySQL, SMB, RDP, MQTT, RTSP 等） - **315 个主动探测插件** —— 特定协议的请求/响应解析，而不仅仅是 Banner 抓取 - **1150 万条指纹签名** —— 同步自 12 个上游数据库，包括 IEEE OUI, Huginn-Muninn, p0f, JA3/JA4 - **实时 Web 仪表板** —— 通过 WebSocket 进行主机清单、检测分类、网络拓扑和攻击面分析 - **行为检测** —— DNS 供应商亲和力漂移、身份变更警报、MAC 欺骗检测、DHCP 异常分析 - **OT / ICS / SCADA 支持** —— 被动识别 Modbus, BACnet, EtherNet/IP, CoAP, MQTT 以及工业设备指纹 ## 工作原理 ``` Network Traffic | v Capture Engine -----> Parser Chain (20 protocol parsers) (per-interface | scapy threads) CapturedPacket | Registry-Based Processors (Network, Services, Names, Infrastructure, IoT/SCADA, Banners, Behavioral) | Evidence | Verdict Engine (weighted certainty fusion + agreement boosting) | +------------+------------+ v v v Host Store Finding Rules Active Probes (SQLite) (8 rule types) (315 plugins) | Web Dashboard / Console / API ``` 1. **Capture (捕获)** —— 每个接口的线程通过 BPF 过滤器，按照有序的协议链解析流量 2. **Process (处理)** —— 注册的处理器从捕获的数据包中提取证据 3. **Fuse (融合)** —— 裁决引擎使用加权确定性和一致性增强来组合每个主机的所有证据 4. **Store (存储)** —— 主机身份、证据链和发现结果持久化到 SQLite，具有可配置的保留期 5. **Detect (检测)** —— 发现规则评估每个主机的异常、欺骗和身份漂移 6. **Probe (探测)** —— 可选的主动探测发送特定协议的请求以进行服务确认 ## 快速开始 需要 **Python 3.11+** 和 **root/sudo** 权限以进行数据包捕获。 ``` # 安装 pip install leetha # 同步 fingerprint 数据库（推荐，约 880 MB） leetha sync # 启动 web dashboard sudo leetha --web # 在特定 interface 上的交互式 console sudo leetha -i eth0 # 多 interface 捕获 sudo leetha -i eth0 -i wlan0 ``` 打开 `http://localhost:8080` 实时查看发现的设备。 ## 网络协议栈分析 | 层 | 协议 | Leetha 分析 | |-------|----------|-----------------| | 2 | Ethernet | ARP 绑定，MAC 厂商解析，随机化检测 | | 2 | LLDP, CDP, STP | 交换机/AP/路由器识别，网络拓扑 | | 3 | ICMPv6 | 路由器通告，邻居发现，IPv6 主机检测 | | 4 | TCP SYN | p0f 风格的 OS 指纹识别（TTL, window, MSS, options） | | 4 | TCP Banners | 来自 30 个协议的被动服务识别（SSH, MySQL, SMB, RDP, ...） | | 7 | DHCPv4 / DHCPv6 | 通过 Option 55/60, vendor class, ORO, DUID 进行设备指纹识别 | | 7 | DNS / mDNS | 主机名解析，供应商亲和力画像，独占服务检测 | | 7 | SSDP / WS-Discovery | UPnP 设备类型，制造商，型号识别 | | 7 | TLS ClientHello | JA3 和 JA4 指纹识别，SNI 提取 | | 7 | HTTP | User-Agent 解析，平台和浏览器检测 | | 7 | SNMP | 系统描述，基于 OID 的设备分类 | | 7 | MQTT, CoAP, Modbus, BACnet, EtherNet/IP | IoT 和 OT 设备识别 | | 7 | SIP, RTSP | VoIP 电话和 IP 摄像头检测 | | 7 | LLMNR / NetBIOS | Windows 主机名和工作组解析 | ## 检测能力 ### 设备类别 | 类别 | 示例 | |----------|----------| | **网络基础设施** | 路由器，交换机，接入点，防火墙，负载均衡器，Mesh 路由器 | | **计算设备** | 服务器，工作站，笔记本电脑，台式机，Hypervisor，虚拟机，容器，云实例 | | **移动设备** | 手机，平板电脑（Apple, Android, Windows，具有 MAC 随机化处理） | | **OT / ICS / SCADA** | PLC（Siemens S7, Allen-Bradley, Beckhoff），RTU，HMI，楼宇自动化控制器，电动汽车充电站 | | **IoT / 智能家居** | 摄像头，门铃，恒温器，智能锁，智能插座，智能照明，扫地机器人，传感器 | | **娱乐设备** | 智能电视（Samsung, LG, Roku），游戏机，流媒体设备，媒体播放器，智能音箱 | | **存储设备** | NAS 设备（Synology, QNAP, TrueNAS, Unraid, OpenMediaVault） | | **打印机** | 网络打印机，扫描仪（IPP, JetDirect, LPD） | | **VoIP** | IP 电话，PBX 系统，SIP 端点 | | **安全设备** | Docker APIs（未加密），Kubernetes APIs，SOCKS 代理，VPN 集中器 | ### 被动 Banner 识别 Leetha 从观察到的 TCP 流量中被动捕获服务 Banner，而无需发送任何数据包： | 协议 | 端口 | 识别内容 | |----------|-------|--------------------| | SSH | 22 | 软件，版本，OS 线索（OpenSSH, Dropbear） | | MySQL / MariaDB | 3306 | 服务器版本，认证插件，MariaDB 检测 | | PostgreSQL | 5432 | 来自 ParameterStatus 的服务器版本 | | MSSQL | 1433 | TDS prelogin 响应 | | MongoDB | 27017 | Wire 协议版本，服务器版本 | | Redis | 6379 | RESP 协议，来自 INFO 的版本 | | SMB | 445, 139 | SMB1/SMB2 方言，服务器 GUID | | RDP | 3389 | X.224 协商，NLA/TLS 能力 | | SMTP | 25, 465, 587 | MTA 软件（Postfix, Exim, Exchange） | | IMAP / POP3 | 143, 110 | 服务器软件（Dovecot, Cyrus） | | FTP | 21 | 服务器软件和版本 | | MQTT | 1883 | CONNACK 响应，Broker 识别 | | RTSP | 554 | IP 摄像头检测（Hikvision, Dahua, Axis） | | SIP | 5060 | VoIP 电话供应商识别 | | LDAP | 389, 636 | 目录服务器检测 | | Elasticsearch | 9200 | 集群名称，版本 | | Docker API | 2375 | API 版本，OS（如果未加密则为安全发现） | | SOCKS | 1080 | 代理检测（SOCKS4/5），开放代理发现 | | BGP | 179 | 路由器识别，AS 号提取 | | VNC, Telnet, IRC | 各种 | 协议版本，登录 Banner | ### 发现规则 | 规则 | 严重程度 | 描述 | |------|----------|-------------| | `new_host` | INFO | 网络上发现新设备 | | `identity_shift` | CRITICAL / HIGH | 设备指纹类别已更改（类别、供应商或平台） | | `addr_conflict` | WARNING | 多个 MAC 声称拥有相同的 IP 地址 | | `low_certainty` | INFO | 设备识别低于置信度阈值 | | `stale_source` | INFO | 证据源最近未被看到 | | `randomized_addr` | INFO | 检测到 MAC 地址随机化 | | `dhcp_anomaly` | HIGH | 流氓 DHCP 服务器，饥饿攻击，或中继代理注入 | | `behavioral_drift` | WARNING | DNS 供应商亲和力从一个生态系统转移到另一个 | ### 指纹来源 | 来源 | 记录数 | 提供的数据 | |--------|---------|---------------| | Huginn-Muninn MAC Vendors | 10.1M | MAC 到供应商/设备的映射 | | Huginn DHCP Vendors | 425K | DHCP 供应商类别标识符 | | Huginn DHCP Signatures | 368K | DHCP 选项指纹 | | Huginn-Muninn Devices | 116K | 设备配置文件（型号，类别，OS） | | IEEE OUI | 86K+ | MAC 制造商查询 | | Huginn DHCPv6 Enterprise | 58K | DHCPv6 企业标识符 | | IANA Enterprise Numbers | 50K+ | SNMP/协议企业 OID | | Huginn DHCPv6 | 40K | DHCPv6 指纹 | | JA3 TLS Fingerprints | Database | TLS 客户端识别与匹配 | | JA4+ TLS Fingerprints | Database | 现代 TLS 客户端识别与匹配 | | p0f TCP Signatures | Database | TCP/IP 协议栈 OS 指纹识别 | | Custom Vendor Patterns | 4,645 | Banner 和特定协议识别 | ## 架构 ``` src/leetha/ capture/ engine.py Packet capture (per-interface scapy threads, BPF filters) protocols/ 20 protocol parsers (ARP, DHCP, DNS, TLS, L2, banners, ...) banner/ Passive TCP banner capture (30 service matchers, connection tracking) dedup.py TTL-based LRU deduplication cache processors/ Registry-based packet processors network.py ARP, DHCP, DHCPv6, ICMPv6 discovery services.py TCP SYN, TLS, HTTP User-Agent fingerprinting names.py DNS, mDNS, SSDP, NetBIOS hostname/service resolution infrastructure.py LLDP, CDP, STP, SNMP network device identification iot_scada.py Modbus, BACnet, CoAP, MQTT, EtherNet/IP banner.py Passive service banner evidence emission behavioral.py DNS vendor affinity tracking evidence/ Evidence models and verdict computation engine fingerprint/ Device identification, OS intelligence, MAC analysis patterns/ JSON pattern loader, compiled regex matching, category index rules/ Finding rules (identity shift, behavioral drift, DHCP anomaly, ...) probe/ 315 active service identification plugins store/ SQLite persistence with retention policies analysis/ Attack surface analysis, spoofing detection, DHCP anomaly detection sync/ Fingerprint database sync with streaming JSON parsers topology.py Network topology graph (gateway, core switch, AP, VM detection) pipeline.py MAC-sharded packet dispatch with bounded queues ui/ web/ FastAPI dashboard with WebSocket real-time updates live.py Live packet stream viewer console.py Interactive REPL console cli.py Entry point and argument parsing ``` ## 性能与资源管理 | 组件 | 机制 | 限制 | |-----------|-----------|-------| | Worker 队列 | 有界 asyncio 队列，溢出时丢弃并计数 | 每个分片 10K 数据包 | | 数据包去重 | 基于 TTL 的 LRU 缓存（300s TTL, 50K 条目） | 稳定内存，无状态丢失 | | 模式匹配 | 预编译正则表达式，按类别索引查找 | 每次匹配 O(k)，而非 O(n) | | 证据链 | 每个来源上限 20 条，每个设备总计 200 条 | 每台主机有界 | | 数据库 | 可配置保留期（观测 7d，警报 30d） | 定期修剪 | | 同步下载 | 流式 JSON 解析器（支持 ijson） | O(item) 内存，而非 O(file) | | 批量写入 | 分组 SQLite 事务（50 ops, 100ms 窗口） | 分摊 I/O | ## 测试 ``` # 运行完整 test suite PYTHONPATH=src python -m pytest spec/ -v # 运行特定 test group PYTHONPATH=src python -m pytest spec/capture/ -v PYTHONPATH=src python -m pytest spec/processors/ -v PYTHONPATH=src python -m pytest spec/evidence/ -v ``` ## 文档 请参阅 [docs/wiki/](docs/wiki/Home.md) 获取详细指南： - [入门指南](docs/wiki/Getting-Started.md) - [工作原理](docs/wiki/How-It-Works.md) - [被动网络发现](docs/wiki/Passive-Network-Discovery.md) - [主动探测](docs/wiki/Active-Probing.md) - [指纹来源](docs/wiki/Fingerprint-Sources.md) - [CLI 参考](docs/wiki/CLI-Reference.md) - [Web 仪表板](docs/wiki/Web-Dashboard.md) - [攻击面分析](docs/wiki/Attack-Surface-Analysis.md) - [欺骗检测](docs/wiki/Spoofing-Detection.md) ## 免责声明 Leetha 是一款被动网络分析工具，仅供在您拥有或拥有明确书面授权监控的网络上进行**授权使用**。 - **无担保。** 本工具按“原样”提供，用于教育、研究和防御安全目的。作者不对误用、误报、漏报或基于其输出采取的任何行动承担任何责任。 - **需遵守法律。** 未经授权的网络监控可能违反地方、州或联邦法律。在某些司法管辖区，混杂模式下的被动数据包捕获可能受窃听法规的约束。在部署之前，请务必确保符合适用的法规、组织政策和交战规则。 - **不能替代专业评估。** Leetha 是网络可视化的辅助工具。它不能取代漏洞扫描器、渗透测试或合格的安全评估。 ## 致谢 ### 上游数据源 Leetha 的指纹识别准确性取决于这些项目慷慨维护的数据： - **[Huginn-Muninn](https://github.com/fingerbank/Huginn-Muninn)** 由 **[Ringmaster](https://github.com/Ringmaster)** 提供 -- MAC 供应商数据库，DHCP 指纹，设备层级和 DHCPv6 模式。Leetha 设备识别的支柱。 - **[IEEE OUI Registry](https://standards-oui.ieee.org/)** -- 官方 MAC 地址制造商分配。 - **[p0f](https://lcamtuf.coredump.cx/p0f3/)** -- 由 Michal Zalewski 提供的 TCP/IP 协议栈指纹签名。被动 OS 检测的基础。 - **[JA3](https://github.com/salesforce/ja3)** -- 由 Salesforce 提供的 TLS 客户端指纹识别方法。 - **[JA4+](https://github.com/FoxIO-LLC/ja4)** -- 由 FoxIO, LLC 提供的下一代 TLS 指纹识别。JA4 方法论和规范版权归 (c) 2023, Fox, LLC 所有。 - **[IANA](https://www.iana.org/assignments/enterprise-numbers/)** -- 用于 SNMP 和协议 OID 的企业编号分配。 ### 灵感来源 - **[p0f](https://lcamtuf.coredump.cx/p0f3/)** 由 Michal Zalewski 开发 -- 开创了被动 TCP/IP 指纹识别。Leetha 的 TCP SYN 分析借鉴了 p0f 的方法论。 ## 许可证 [GNU General Public License v3.0](LICENSE)