sergenbiltekin/poisonhound

# PoisonHound [](https://github.com/sergenbiltekin/poisonhound/actions/workflows/ci.yaml) [](LICENSE) [](pyproject.toml) PoisonHound 会监视本地网络，寻找常见的中间人攻击设置背后的流量模式。一旦发现此类攻击，它会通过电子邮件通知您，告警中包含足够详细的细节，以便您立即采取行动。  *截取自真实的测试会话：针对正在运行的 PoisonHound 实例发起了 `arpspoof`、手工伪造的 DHCPOFFER、`mitm6` 以及 `Responder` 攻击 —— 这并非模拟输出的结果。* 它可以检测： - **ARP 欺骗** - 声称是您网关的 MAC 地址发生更改。 - **伪造 DHCP 服务器** - 不在您的白名单中的 DHCP 服务器开始响应请求。 - **IPv6 路由器/DHCPv6 劫持 (mitm6 风格)** - 未经授权的路由器通告或 DHCPv6 服务器试图将自身推送为网络的 IPv6 配置或 DNS 服务器。 - **LLMNR / NBT-NS / mDNS 中毒** (Responder, Inveigh, ...) - 通过主动查询它知道不存在的 hostname 并对任何响应发出告警，因为合法的解析永远无法解析它们。 ## 为什么这些告警真正有用 每个告警都包含： - **检测到了什么以及如何检测到的** - 触发的特定启发式规则。 - **来自哪里** - 源 MAC/IP 和尽力而为的供应商查询信息。 - **该如何处理** - 针对该攻击类型的一套固定的具体补救步骤。 - **证据** - 支持该告警的完整 packet dump 会写入日志，并通过告警的 dedup key 进行引用。 针对同一底层问题的重复告警会在可配置的时间窗口内进行去重，而不是淹没您的收件箱。 ## 安装说明 需要 Python 3.10+，并且由于 packet capture 需要 raw sockets： - **Linux**：以 root 用户身份运行（或授予解释器 `CAP_NET_RAW`/`CAP_NET_ADMIN` 权限），并确保已安装 `libpcap`。 - **Windows**：安装 [Npcap](https://npcap.com/#download)（在设置过程中勾选“WinPcap API-compatible mode”），并从具有管理员权限的命令提示符运行。 ``` git clone https://github.com/sergenbiltekin/poisonhound.git cd poisonhound pip install -e . ``` ## 配置 复制示例 config 并针对您的网络进行编辑： ``` cp config.example.yaml config.yaml ``` 关键字段： | 字段 | 用途 | |---|---| | `interface` | 要监听的网络接口（例如 `eth0`、`Ethernet`）。 | | `detectors.arp_spoof.gateway_ip` / `known_gateway_mac` | 您的网关 IP 和（可选的）其真实 MAC 地址；将 MAC 留空可在首次运行时自动学习。 | | `detectors.rogue_dhcp.authorized_servers` | 您合法的 DHCP 服务器的 IP/MAC。 | | `detectors.ipv6_rogue_ra.authorized_routers` / `authorized_dhcpv6_servers` | 您合法的 IPv6 路由器/DHCPv6 服务器的 Link-local address。 | | `detectors.name_resolution_canary` | 针对主动的 LLMNR/mDNS/NBT-NS canary 查询的调优。 | | `smtp` | 用于发送告警电子邮件的邮件服务器和收件人。 | SMTP 凭据不必存放在 `config.yaml` 中 - 将 `.env.example` 复制到 `.env` 并改为设置 `PH_SMTP__PASSWORD`。 ## 用法 ``` poisonhound --config config.yaml ``` 或者，不安装 console script： ``` python -m poisonhound --config config.yaml ``` 在不启动 sniffer 的情况下验证 config 文件： ``` poisonhound --config config.yaml --check-config ``` 使用 Ctrl+C 停止（SIGINT/SIGTERM 在 Linux 和 Windows 上均会被优雅处理）。 ## 告警示例 ``` ALERT [HIGH] ARP spoofing suspected: gateway MAC changed to de:ad:be:ef:00:01 source=de:ad:be:ef:00:01/192.168.1.1, vendor=Locally administered (randomized/spoofed) The baseline MAC address for gateway 192.168.1.1 is aa:bb:cc:00:00:01, but an ARP reply just claimed the gateway is now at de:ad:be:ef:00:01. This is the classic ARP cache poisoning pattern used to redirect traffic through an attacker's machine for a MITM attack. ``` 支持此告警的完整 packet dump 以及建议的补救步骤会写入日志并包含在告警电子邮件中。有关涵盖所有四个检测器的真实检测运行外观，请参见上面的截图。 ## 开发 ``` pip install -e ".[dev]" pytest ruff check src tests ``` 测试将合成数据包直接注入每个检测器 - 它们都不接触网络或需要提升的权限，因此全套测试可以在 Linux 和 Windows 的 CI 上运行。 ## 架构 - `src/poisonhound/core/` - 插件接口（`BaseDetector`、`BaseNotifier`）、`Alert` 模型、config 加载、packet dispatcher 以及去重/速率限制器。 - `src/poisonhound/detectors/` - 每种攻击类型一个模块。 - `src/poisonhound/notifiers/` - 告警发送渠道（目前支持 SMTP）。 - `src/poisonhound/net/` - 共享的 packet-building/evidence 辅助工具。 单个 sniffer 在所有检测器之间共享：它们的 BPF 过滤器被合并，并且每个捕获的 packet 都被分发给每个已启用的检测器。一个检测器中的 bug 会被记录下来，并且不会影响其他检测器或停止捕获。 ## 路线图 目前刻意不将其纳入范围，但插件接口的构建旨在无需返工即可支持它们： - 一个本地的 web dashboard，用于浏览告警历史记录和编辑设置。 - 打包的 Windows 服务 / `.exe` 和 Linux systemd 发行版。 - 可选的 Docker 部署。 - Webhook、Telegram 和 Discord 通知器。 ## 贡献 欢迎提交 issue 和 pull request - 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：Python, 中间人攻击检测, 局域网安全, 无后门, 网络流量分析, 逆向工具