cxnturi0n/nomad

# Nomad — 多智能体源代码安全审计 一个与提供商无关的多智能体渗透测试流水线，用于源代码审查。每个智能体专门负责评估的不同阶段——从侦察到漏洞利用验证——由一个确定性的 Python 编排器进行协调。 支持 **Claude**、**OpenAI** 或本地 **Ollama** 模型。 ## 前置条件 - **Python 3.10+** - **至少一个 AI 提供商：** | Provider | Setup | |---|---| | Claude (默认) | `npm install -g @anthropic-ai/claude-code && claude auth login` | | OpenAI Codex CLI | `npm install -g @openai/codex && export OPENAI_API_KEY=sk-...` | | OpenAI API | `pip install openai && export OPENAI_API_KEY=sk-...` | | Ollama (本地) | `curl -fsSL https://ollama.com/install.sh \| sh && ollama pull qwen2.5-coder:32b` | - **可选工具**（安装后可提升效果）： | Tool | 作用 | 安装命令 | |---|---|---| | Semgrep | 基于 AST 的模式匹配（secrets、SQLi、XSS、OWASP） | `pipx install semgrep` | | TruffleHog | 基于熵值的密钥检测 | `curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \| sudo sh -s -- -b /usr/local/bin` | | npm | Node.js 依赖审计 | `sudo apt install npm` | | pip-audit | Python 依赖审计 | `pipx install pip-audit` | | osv-scanner | 通用依赖扫描器（Go、Java、Rust 等） | `go install github.com/google/osv-scanner/cmd/osv-scanner@latest` | ## 快速开始 ``` # 使用 Claude 进行全量扫描 python3 nomad.py --repo /path/to/target-app # OpenAI python3 nomad.py --repo /path/to/target-app --provider openai --model o4-mini # Ollama（免费，离线） python3 nomad.py --repo /path/to/target-app --provider ollama --model qwen2.5-coder:32b # 快速扫描，详细信息 python3 nomad.py --repo /path/to/target-app --scope quick -v # 全量扫描 + 针对运行中应用的主动漏洞验证 python3 nomad.py --repo /path/to/target-app \ --validate --base-url http://localhost:3000 \ --creds "admin:password123" --safe-only # 跳过缓慢的 agents python3 nomad.py --repo /path/to/target-app --skip deps triage # 仅信息收集 + 静态分析 python3 nomad.py --repo /path/to/target-app --skip secrets deps triage fingerprint validation ``` ## 智能体流水线 ``` A0 Orchestrator (deterministic Python — not an LLM) │ ├─ A1 Recon ................. ✅ Maps codebase architecture, entry points, data flows ├─ A2 Static Analysis ....... ✅ Hunts vulnerabilities across 30+ CWE classes ├─ A3 Secrets Scanner ....... ✅ Hardcoded credentials, API keys, tokens (+ Semgrep, TruffleHog) ├─ A4 Dependency Audit ...... ✅ Vulnerable packages, supply chain risks (+ npm audit, pip-audit, osv-scanner) ├─ A5 Triage & Dedup ........ ✅ Merges findings, identifies attack chains, assigns CVSS 3.1 ├─ A6 Fingerprint ........... ✅ Probes running app: WAF detection, bypass hints, defense profiling ├─ A7 Validation ............ ✅ Active exploit testing with adaptive WAF bypass └─ A8 Reporting ............. ⬜ Planned ``` ### 智能体如何连接 ``` A1 Recon → A2 Static Analysis ─┐ → A3 Secrets Scanner ─┤→ A6 Triage & Dedup → A4 Dependency Audit ─┘ │ ├─→ AFP Fingerprint (probes live app) └─→ A7 Validation (exploits with fingerprint intel) ``` A1 将数据输入到每个下游智能体。A2/A3/A4 独立运行并生成发现结果。A6 合并、去重、识别攻击链并分配 CVSS 评分。AFP 对运行中应用程序的防御机制（WAF、速率限制、安全头）进行指纹识别。A7 使用指纹数据选择最佳 payload 和绕过技术。 ## CLI 参考 | 标志 | 说明 | 默认值 | |---|---|---| | `--repo` | 目标仓库路径（**必需**） | — | | `--provider` | `claude`、`openai`、`ollama` | `claude` | | `--model` | 模型覆盖 | 根据提供商自动选择 | | `--api-key` | API key 覆盖 | 环境变量 | | `--ollama-host` | Ollama 服务器 URL | `localhost:11434` | | `--scope` | `full`、`quick`、`secrets_only`、`deps_only` | `full` | | `--severity-threshold` | `critical`、`high`、`medium`、`low`、`info` | `low` | | `--skip` | 要跳过的智能体：`static`、`secrets`、`deps`、`triage`、`fingerprint`、`validation` | 无 | | `--validate` | 启用主动漏洞利用测试（AFP + A7） | 关闭 | | `--safe-only` | 仅非破坏性 PoC | `true` | | `--base-url` | 运行中应用的 URL（与 `--validate` 一起使用时必需） | — | | `--tokens` | 用于验证的认证令牌 | — | | `--creds` | 用于验证的凭据（`user:pass`） | — | | `--output-dir` | 报告输出目录 | `./output` | | `--format` | `md`、`json`、`pdf` | `md,json` | | `--tester` | 报告中的测试人员姓名 | — | | `--engagement-id` | 报告中的 Engagement ID | — | | `-v, --verbose` | 显示智能体推理过程 | 关闭 | ## 提供商对比 | 能力 | Claude Code | OpenAI Codex | Ollama | |---|---|---|---| | Agentic（迭代式文件浏览） | ✓ | ✓ | ✗ (单次请求) | | Shell 命令执行 | ✓ | ✓ | ✗ | | 文件读/写 | ✓ | ✓ | ✗ (预加载) | | 离线 / 免费 | ✗ | ✗ | ✓ | | 最适合 | 全量扫描、大型仓库 | 全量扫描 | 快速扫描、小型仓库 | Agentic 提供商（Claude、OpenAI）会迭代式地探索代码库——读取文件，决定下一步读取什么，运行命令。Ollama 在单次请求模式下运行，Nomad 会预读取源文件并将其注入到 prompt 上下文中。 ## 输出结构 ``` output/ ├── nomad.log # Full execution log ├── scaling_plan.json # How the orchestrator partitioned work ├── recon/ │ └── a1_recon_output.json # Codebase architecture map ├── analysis/ │ ├── a2_static_full_repo_output.json # Per-partition findings │ └── findings_static_merged.json # Merged static analysis findings ├── secrets/ │ └── a3_secrets_output.json # Secrets scan findings ├── deps/ │ └── a4_deps_output.json # Dependency audit findings ├── triage/ │ └── a6_triage_output.json # Deduplicated, CVSS-scored, prioritized findings ├── fingerprint/ │ └── a_fp_fingerprint_output.json # Target defense profile (WAF, headers, endpoints) └── validation/ └── a7_validation_output.json # Exploit confirmation with PoC evidence ``` ## 架构 ``` nomad.py ← A0 Orchestrator + CLI entry point ├── agents/ │ ├── base.py ← BaseAgent (provider-agnostic contract) │ ├── recon.py ← A1 Recon │ ├── static_analysis.py ← A2 Static Analysis │ ├── secrets.py ← A3 Secrets (+ Semgrep/TruffleHog integration) │ ├── dependency_audit.py ← A4 Dependency Audit (+ npm audit/pip-audit/osv-scanner) │ ├── triage.py ← A6 Triage & Deduplication │ ├── fingerprint.py ← AFP Target Fingerprinting │ ├── validation.py ← A7 Exploit Validation │ └── prompts/ │ ├── recon.md ← A1 system prompt │ ├── static_analysis.md ← A2 system prompt │ ├── secrets.md ← A3 system prompt │ ├── dependency_audit.md ← A4 system prompt │ ├── triage.md ← A6 system prompt │ ├── fingerprint.md ← AFP system prompt │ └── validation.md ← A7 system prompt ├── models/ │ └── schemas.py ← Shared dataclasses (EngagementConfig, AgentRun, etc.) └── utils/ └── runners/ ├── base.py ← BaseRunner interface + RunResult + JSON extraction ├── claude.py ← Claude Code CLI runner ├── openai.py ← OpenAI Codex CLI / API runner └── ollama.py ← Ollama HTTP API runner ``` ## 关键设计决策 **编排器是代码，而非 LLM。** `nomad.py` 使用 `if` 语句（而非 AI）来进行路由和决策。这确保了流水线的可预测性和可调试性。 **智能体通过 JSON 文件通信。** 没有共享内存，没有消息传递。每个智能体都会写入结构化的 JSON 输出。编排器读取这些输出，并将相关部分注入到下一个智能体的 prompt 中。 **智能体从不知道运行它们的是哪个 AI。** 它们定义一个 system prompt 和 task prompt，调用 `self.runner.run(...)`，并获取一个 `RunResult`。切换提供商只需一个 CLI 标志。 **混合工具 + LLM 方案。** A3 和 A4 首先运行 CLI 安全工具（Semgrep、TruffleHog、npm audit），然后将原始结果提供给 LLM 进行验证、去重和丰富。工具可以快速捕获已知模式；LLM 则能捕捉工具遗漏的内容，并减少误报。 **基于指纹的漏洞利用。** AFP 会在 A7 运行前探测目标的防御机制。A7 会收到 WAF 供应商、绕过提示和输入向量分析——这样它就能在第一次尝试时就选择正确的 payload 技术，而不是浪费轮次去重新发现哪些内容被阻止。 **扩展基于分区。** 对于大型仓库，编排器根据 A1 的 LOC（代码行数）估算结果，按模块和/或漏洞类别拆分工作：小于 5K LOC = 单次通过；小于 50K = 按模块拆分；大于 50K = 模块 × 漏洞类别的矩阵。 ## 添加新提供商 1. 创建 `utils/runners/your_provider.py`，实现 `BaseRunner` 2. 在 `utils/runners/__init__.py` 中注册它 → 添加到 `PROVIDERS` 字典 3. 完成 — 所有智能体将自动支持它 ## 添加新智能体 1. 创建 `agents/prompts/your_agent.md`（system prompt） 2. 创建 `agents/your_agent.py`，继承 `BaseAgent` 3. 将其接入 `nomad.py` 的流水线 4. 将其跳过键（skip key）添加到 `parse_args` 中的 `valid_skips` 集合

标签：AI, AI安全, Chat Copilot, Claude, CVE检测, DevSecOps, LLM评估, Ollama, OpenAI, PyRIT, Python, SAST, Secret检测, Semgrep, SQL注入检测, TruffleHog, WordPress安全扫描, XSS检测, 上游代理, 云安全监控, 依赖审计, 内存规避, 多智能体系统, 学术论文, 无后门, 本地化部署, 源代码审计, 盲注攻击, 离线安全测试, 网络安全, 自动化代码审查, 逆向工具, 隐私保护, 静态分析