sachindots/HuntAI

HuntAI 自动化了渗透测试的**侦察阶段**。一个 LLM *编排*整个测试过程 —— 它决定运行哪些工具，读取结果， 并决定下一步运行什么 —— 同时由人工审批每一次主动扫描。发现 的结果会与 **MITRE ATT&CK** 技术和 **CVE** 进行关联，被渲染为攻击 图谱，并写入结构化报告中。 一切都运行在**免费模型**（NVIDIA NIM、Ollama、Gemini）上，并且 **在代码层面锁定范围**，因此它只会触及你被授权测试的目标。 ## ✨ 特性 | | | |---|---| | 🧠 **LLM 驱动循环** | Agentic 编排：`决策 → 运行 → 观察 → 重复`，而非固定脚本 | | 🔐 **范围锁定** | 每个目标都经过代码强制检查；默认拒绝公共 IP | | 🙋 **人工介入** | 主动扫描需要明确批准；被动侦察优先 | | 🗺️ **内置情报** | MITRE ATT&CK 映射 · CVE 关联 · 攻击图谱生成 | | 💸 **仅限免费模型** | NVIDIA NIM + Ollama + Gemini — 无需付费 API 密钥 | | ⚡ **Token 严格控制** | 事件驱动引擎：LLM 永远不会阻塞缓慢的工具 | | 🖥️ **CLI + Web + TUI** | 一个 FastAPI 核心，一个 Svelte Web UI，以及一个 Textual 终端应用 | | 🧪 **两种运行模式** | **Auto**（HuntAI 驱动）和 **Copilot**（在旁提供建议） | | 🐳 **随处运行** | Docker 沙箱 *或* 在 Kali/Parrot 机器上原生执行；支持 Windows + Linux | ## 🏗️ 架构 ``` flowchart TD U[User · CLI / Web / TUI] --> ORc subgraph Orchestration ORc[Orchestrator] --> AG[Agentic Recon Agent
LLM-driven loop] ORc --> AN[Analysis] ORc --> VA[Validation
anti-false-positive] ORc --> RE[Reporter] ORc -.copilot.-> CP[Copilot · advisory] end AG -->|scope check| SG{{Scope Guard
code-enforced}} AG -->|approve active| HL{{Human approval}} AG --> DP[Async Dispatcher
non-blocking · batched] DP --> RN[Tool Runner] RN -->|Docker| SB[(Sandbox container)] RN -->|native| NT[(Kali/Parrot host)] SB & NT --> TL[nmap · naabu · httpx ·
nuclei · subfinder] TL -->|typed parse| AN AN --> INT[Intelligence
MITRE · CVE · attack graph] INT --> RE --> OUT[Report + attack graph] KB[(Knowledge base
CAG cheatsheet + findings memory)] -.grounds.-> AG & CP LLM[NVIDIA NIM · Ollama · Gemini] -.reasoning.-> AG & AN & CP style SG fill:#b91c1c,color:#fff style HL fill:#c2410c,color:#fff style LLM fill:#76b900,color:#fff ``` 组件级细节和数据流请参见 **[ARCHITECTURE.md](ARCHITECTURE.md)**。 ## 🔁 LLM 如何编排 核心目标：让 LLM *主导整个测试过程*。这是一个迭代循环，而不是固定计划。 ``` sequenceDiagram participant L as LLM Orchestrator participant G as Scope Guard participant H as Human participant D as Dispatcher participant T as Tools L->>G: target in scope? G-->>L: ✓ authorized loop until done / budget cap L->>L: decide next tools (from results so far) L->>H: approve active scans? H-->>L: ✓ / ✗ L->>D: run approved tools (concurrent) D->>T: execute (sandbox or native) T-->>D: raw output D-->>L: compacted summary (never raw dumps) L->>L: observe → decide again, or done end L->>L: analyse · MITRE · CVE · graph · report ``` 每个 LLM 决策都会被**验证** —— 只接受来自 registry 的工具名称， 选项会被列入白名单，任何 LLM 错误都会回退到 确定性的基于规则的计划。模型可以塑造侦察过程；但它永远不能 发明命令或逃离范围。 ## 🚀 快速开始 ``` git clone https://github.com/sachindots/HuntAI.git && cd HuntAI python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev,web,llm]" pytest # 106 tests pass huntai check 172.20.0.5 # IN SCOPE huntai check 8.8.8.8 # OUT OF SCOPE (blocked in code) ``` 从应用中配置免费模型 + 你自己的目标 —— 无需编辑文件： ``` huntai config set nvidia_api_key nvapi-xxxx # or run fully local on Ollama huntai scope add 203.0.113.7 --yes # authorize YOUR target (attestation) huntai serve # web UI at http://127.0.0.1:8000 ``` 完整演练（Docker 实验环境、Kali 原生执行、离线模式）请参见 **[RUN.md](RUN.md)**。 ## 🖥️ 两种模式 | 模式 | 驱动者 | HuntAI 的角色 | |------|-----------|---------------| | **Auto** | HuntAI | 规划 → 扫描（你批准） → 分析 → 生成包含 MITRE + CVE + 攻击图谱的报告 | | **Copilot** | 你 | 监控你粘贴的内容，基于知识库提供下一步建议 —— **不执行任何操作** | ## 🧪 实际运行 在 Kali 上使用原生工具，对在线服务进行真实的 `nmap` 扫描： ``` $ python scripts/native_run.py 127.0.0.1 TOOLS: naabu success open ports [9001] nmap success 9001/tcp http SimpleHTTPServer 0.6 ← real -sV fingerprint FINDINGS (1): [INFO] open 9001/tcp http mitre=T1595.001 ``` ``` graph TD t["172.20.0.10"] --> p80["80/http"] --> f1["MEDIUM: Apache 2.4.7
CVE-2014-0226"] t --> p22["22/ssh"] --> f2["MEDIUM: OpenSSH 6.6
CVE-2015-5600"] t --> f3["HIGH: DVWA default login
T1078"] style f1 fill:#c2410c,color:#fff style f2 fill:#c2410c,color:#fff style f3 fill:#b91c1c,color:#fff ``` ## 🛡️ 安全模型 HuntAI 专为**授权**测试构建。安全防护在代码中强制执行，而非依赖 prompt： - **范围防护** —— 在运行任何工具之前，每个目标都会被验证；默认拒绝公共 IP， cloud-metadata / CGNAT 范围*始终*被拒绝，即使 有人试图允许它们。 - **授权证明** —— 添加你自己的目标需要明确的确认， 并记录到审计日志中。 - **人工介入** —— 主动（发送数据包）工具需要批准；被动优先。 - **不可信的 LLM 输出** —— 模型只能从 registry 选择工具；从不执行 任意命令。 - **审计追踪** —— 范围决策、批准和工具运行都会被记录。 ## 🧰 技术栈 | 层级 | 选择 | |-------|--------| | 语言 | Python 3.11–3.14 · Pydantic v2 | | LLM | `openai` SDK → NVIDIA NIM · Ollama · Gemini（均兼容 OpenAI） | | 工具 | nmap · ProjectDiscovery (subfinder / naabu / httpx / nuclei) | | 知识库 | CAG（长上下文速查表）+ 混合 BM25/dense findings memory | | Web | FastAPI + WebSocket · Svelte 前端 | | CLI | Textual TUI + Rich | | 沙箱 | Docker Compose · 或在 Kali/Parrot 上原生执行 | | 评估 | 真值测试套件（覆盖率 / 精确率 / F1） | ## 📁 项目结构 ``` src/huntai/ ├── agents/ orchestrator · agentic recon · analysis · validation · reporter · copilot ├── analysis/ MITRE mapping · CVE correlation · attack graph ├── engine/ async dispatcher · runners (sandbox / native / fake) · compaction ├── tools/ typed tool wrappers + parsers ├── kb/ CAG store + findings memory (kept separate) ├── llm/ openai-SDK client + provider routing ├── core/ engine factory · settings store ├── web/ FastAPI app + WebSocket ├── tui/ Textual terminal UI ├── evalkit/ benchmark harness └── obs/ span tracer docker/ sandbox image + scope-locked lab targets web/frontend/ Svelte web UI ``` ## 🔬 为什么是 v2 最初的硕士项目使用单次 `gpt-4o-mini` 调用和 `ada-002` embedding，通过字符串解析 shell 命令，没有真正的 agent 循环。v2 进行了重建： | 原版 | HuntAI v2 | |----------|-----------| | 单次 LLM 调用 | **Agentic 多 agent** 编排 | | `!command` 字符串解析 | **类型化工具层**（原生 JSON/XML 解析） | | 被误标为 "CAG" 的 RAG | **真正的 CAG** *和* findings memory，作为独立的模块 | | 付费 OpenAI | **免费模型**（NIM / Ollama / Gemini） | | 仅限侦察 | **+ MITRE 映射，CVE 关联，攻击图谱** | | 无沙箱 / 无评估 | **Docker 沙箱 + 基准测试套件** | ## 📄 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI风险缓解, Cloudflare, GitHub, MITRE ATT&CK, Python, SBOM分析, Svelte, XSS, 大模型智能体, 实时处理, 密码管理, 插件系统, 无后门, 漏洞情报, 自动化侦察, 请求拦截, 逆向工具