NullRabbitLabs/minerva-hdn

# minerva-hdn 基于 TCP 时序样本的蜜罐检测。 当你扫描网络时，某些主机是蜜罐——设计用来伪装成真实服务但实际上会记录并上报你活动的系统。minerva-hdn 通过分析其 TCP 响应时间的统计指纹来帮助识别它们。 真实服务的时序变化源于 CPU 调度、网络抖动和应用处理。蜜罐模拟器（Cowrie、Dionaea 等）往往会产生暴露其合成来源的时序模式：不自然的统一响应、缓慢的初始握手后紧跟快速回复，或者暗示脚本化行为的双峰分布。 minerva-hdn 接收针对单个 host:port 的往返时间测量列表（单位为 ms），并返回判定结果、概率评分以及驱动该决策的具体指标（"tells"）。 ``` {"verdict": "likely_honeypot", "probability": 0.8, "tells": ["High timing variance (CV=1.29)", "Bimodal timing distribution"], "target": "10.0.0.1:443"} ``` 判定结果：`likely_real` (p < 0.3)，`inconclusive` (0.3–0.7)，`likely_honeypot` (p > 0.7)。 ### 检测信号 | 信号 | 含义 | |--------|---------------| | 高变异系数 (CV > 0.4) | 时序方差相对于均值不成比例——与真实 OS 网络栈行为不一致 | | 首次响应缓慢 | 首个数据包显著慢于后续数据包——暗示模拟代码中的延迟初始化 | | 双峰分布 | 存在较大间隙的两个 distinct 时序聚类——暗示两条不同的代码路径在响应，典型的脚本模拟器特征 | 每个信号的评分会累加并上限为 1.0。运行双峰检查至少需要五个样本。 ## 安装 ``` pip install -e ".[dev]" # dev (tests included) pip install -e ".[server]" # HTTP API pip install -e ".[mcp]" # MCP server pip install -e ".[server,mcp]" # everything ``` ## 用法 ### CLI ``` # Pipe JSON array echo '[12.3, 45.1, 11.9, 200.4, 13.2]' | minerva-hdn analyze # Explicit flags minerva-hdn analyze --samples 12.3 45.1 11.9 200.4 13.2 minerva-hdn analyze --samples 12.3 45.1 11.9 --target 10.0.0.1:443 ``` 输出始终为 JSON。退出码：`0` = 成功，`1` = 错误。如果少于 5 个样本会向 stderr 发出警告（双峰检查禁用）。 ### HTTP API ``` minerva-serve --host 0.0.0.0 --port 8080 ``` ``` POST /analyze {"samples": [...], "host": "10.0.0.1", "port": 443} → {"verdict": "...", "probability": 0.82, "tells": [...]} POST /analyze/batch {"targets": [{"host": "...", "port": 443, "samples": [...]}, ...]} → {"assessments": [{"target_host": "...", "target_port": 443, "verdict": "...", ...}]} GET /health → {"status": "ok"} ``` ### MCP server ``` minerva-mcp # stdio — spawned by MCP client minerva-mcp --transport sse --port 8080 # HTTP/SSE — Docker service ``` 暴露一个工具：`analyze_honeypot(samples_ms, target_host, target_port)`。 ## 手动测试 ### 1. 独立运行 minerva-hdn ``` # CLI minerva-hdn analyze --samples 12.3 45.1 11.9 200.4 13.2 # HTTP server minerva-serve --host 0.0.0.0 --port 8080 & # Single target curl -s -X POST localhost:8080/analyze \ -H 'Content-Type: application/json' \ -d '{"samples": [12.3, 45.1, 200.4, 13.2, 11.9], "host": "10.0.0.1", "port": 443}' | jq . # Batch (what the orchestrator calls) curl -s -X POST localhost:8080/analyze/batch \ -H 'Content-Type: application/json' \ -d '{"targets": [{"host":"10.0.0.1","port":443,"samples":[12.3,45.1,200.4]},{"host":"10.0.0.2","port":22,"samples":[1.1,1.2,1.1]}]}' | jq . # Health check curl -s localhost:8080/health kill %1 ``` ### 2. 单元测试（无需基础设施） ``` pytest -v ``` ## 设计 minerva-hdn 是**无状态**的——像 nmap 一样，它接收输入并返回结果。没有数据库，没有消息队列。持久化完全由调用者负责。 这使得它易于作为库嵌入、通过 HTTP 调用，或通过 MCP 由 AI 代理驱动——而无需引入基础设施依赖。 ## 开发 ``` pytest --cov=src # tests with coverage ``` ## 背景 Minerva-HDN 是 [NullRabbit](https://nullrabbit.ai) 平台的开源蜜罐检测组件——面向验证者基础设施和去中心化网络的自主防御。 Minerva 消费由 [Limpet](https://github.com/NullRabbitLabs/limpet-trs)（NullRabbit 的 eBPF/XDP 网络扫描器）产生的时序样本。它们共同构成了扫描层：Limpet 以纳秒级 RTT 精度发现开放端口，Minerva 判断这些服务是真实的还是合成的。 分析结果会输入到 NullRabbit 专有的威胁分析和行为基线系统。关于自主防御行动背后的治理框架，请参阅：

标签：BOF, Dionaea, Python, Python脚本, Shellcode执行, TCP协议分析, 云存储安全, 分布检测, 反蜜罐, 威胁情报, 安全规则引擎, 密码管理, 开发者工具, 插件系统, 文档结构分析, 无后门, 时间指纹识别, 服务指纹, 欺骗防御, 统计分析, 网络延迟, 网络扫描, 网络行为分析, 蜜罐检测, 逆向工具