R00T-Kim/SCOUT
GitHub: R00T-Kim/SCOUT
SCOUT 是一款确定性固件安全分析引擎，通过 42 阶段流水线将固件二进制文件转化为哈希锚定的漏洞证据链，输出 SARIF、CycloneDX SBOM 和经验证的利用链。
Stars: 6 | Forks: 1
# SCOUT
### 固件到漏洞利用证据引擎
**投入固件二进制文件。获取 SARIF 扫描结果、CycloneDX SBOM+VEX，以及基于哈希锚定的证据链。**
[](https://python.org)
[](LICENSE)
[]()
[-orange?style=for-the-badge)]()
[]()
[]()
[]()
[English (this file)](README.md) | [한국어](README.ko.md)
## 为什么选择 SCOUT？
## 工作原理
```
firmware.bin ──> 42-stage pipeline ──> SARIF findings ──> Web viewer
(auto Ghidra) CycloneDX SBOM+VEX TUI dashboard
(auto CVE match) Evidence chain GitHub/VS Code
(optional LLM) SLSA attestation MCP for AI agents
```
```
# 完整分析
./scout analyze firmware.bin
# 仅静态 (无 LLM, $0)
./scout analyze firmware.bin --no-llm
# 预提取的 rootfs
./scout analyze firmware.img --rootfs /path/to/rootfs
# Web viewer
./scout serve aiedge-runs/
--port 8080
# TUI dashboard
./scout ti # interactive (latest run)
./scout tw # watch mode (auto-refresh)
# 用于 AI agents 的 MCP server
./scout mcp --project-id aiedge-runs/
```
## 功能对比
| Feature | SCOUT | FirmAgent | EMBA | FACT | FirmAE |
|:--------|:-----:|:---------:|:----:|:----:|:------:|
| Scale (firmware tested) | 1,124 | 14 | -- | -- | 1,124 |
| SBOM (CycloneDX 1.6+VEX) | Yes | No | Yes | No | No |
| SARIF 2.1.0 Export | Yes | No | No | No | No |
| Hash-Anchored Evidence Chain | Yes | No | No | No | No |
| SLSA L2 Provenance | Yes | No | No | No | No |
| Known CVE Signature Matching | Yes (2,239 CVEs) | No | No | No | No |
| Confidence Caps (honest scoring) | Yes | No | No | No | No |
| Ghidra Integration (auto-detect) | Yes | IDA Pro | Yes | No | No |
| AFL++ Fuzzing Pipeline | Yes | Yes | No | No | No |
| Cross-Binary IPC Chains | Yes (5 types) | No | No | No | No |
| Taint Propagation (LLM) | Yes | Yes (DeepSeek) | No | No | No |
| Adversarial FP Reduction | Yes | No | No | No | No |
| MCP Server (AI agent) | Yes | No | No | No | No |
| Web Report Viewer | Yes | No | Yes | Yes | No |
| Zero pip Dependencies | Yes | No | No | No | No |
## 核心特性
| | Feature | Description |
|---|---------|-------------|
| :package: | **SBOM & CVE** | CycloneDX 1.6 (40+ signatures) + NVD CVE scan + 2,239 local CVE DB + 13 known CVE signatures |
| :mag: | **Binary Analysis** | ELF hardening (NX/PIE/RELRO/Canary) + `.dynstr` detection + FORTIFY_SOURCE + Ghidra decompilation |
| :dart: | **Attack Surface** | Source-to-sink tracing, web server auto-detection, cross-binary IPC chains (5 types) |
| :brain: | **Taint Analysis** | HTTP-aware inter-procedural taint with call chain visualization; web server priority |
| :shield: | **Security Assessment** | X.509 cert scan, boot service audit, filesystem permission checks, credential mapping |
| :test_tube: | **Fuzzing** *(optional)* | AFL++ with CMPLOG, persistent mode, NVRAM faker, harness generation, crash triage |
| :bug: | **Emulation** | 3-tier (Firmae / QEMU user-mode / rootfs inspection) + GDB remote debug |
| :robot: | **MCP Server** | 12 tools via Model Context Protocol for Claude Code/Desktop |
| :bar_chart: | **Web Viewer** | Glassmorphism dashboard with KPI bar, IPC map, risk heatmap |
| :link: | **Evidence Chain** | SHA-256 anchored artifacts, confidence caps, 5-tier exploit promotion |
| :scroll: | **SARIF & SLSA** | SARIF 2.1.0 findings + SLSA Level 2 in-toto attestation |
| :chart_with_upwards_trend: | **Benchmarking** | FirmAE 1,124 dataset support, CVE rematch, TP/FP analysis scripts |
## 流水线 (42 个阶段)
```
Firmware --> Unpack --> Profile --> Inventory --> Ghidra --> Semantic Classification
--> SBOM --> CVE Scan --> Reachability --> Endpoints --> Surfaces
--> Enhanced Source --> C-Source ID --> Taint Propagation
--> FP Verification --> Adversarial Triage
--> Graph --> Attack Surface --> Findings
--> LLM Triage --> LLM Synthesis --> Emulation --> [Fuzzing]
--> PoC Refinement --> Chain Construction --> Exploit Chain --> PoC --> Verification
```
Ghidra 默认被自动检测并启用。`[括号内]` 的阶段需要可选的外部工具 (AFL++/Docker)。
v2.0 新增阶段 (8)
| Stage | Module | Purpose | LLM? | Cost |
|-------|--------|---------|------|------|
| `enhanced_source` | `enhanced_source.py` | Web server auto-detection + INPUT_APIS scan (21 APIs) | No | $0 |
| `semantic_classification` | `semantic_classifier.py` | 3-pass function classifier (static, haiku, sonnet) | Yes | Low |
| `taint_propagation` | `taint_propagation.py` | HTTP-aware inter-procedural taint with call chain | Yes | Medium |
| `fp_verification` | `fp_verification.py` | 3-pattern FP removal (sanitizer/non-propagating/sysfile) | No | $0 |
| `adversarial_triage` | `adversarial_triage.py` | Advocate/Critic LLM debate for FPR reduction | Yes | Medium |
| `poc_refinement` | `poc_refinement.py` | Iterative PoC generation from fuzzing seeds (5 attempts) | Yes | Medium |
| `chain_construction` | `chain_constructor.py` | Same-binary + cross-binary IPC exploit chains | No | $0 |
| `csource_identification` | `csource_identification.py` | HTTP input source identification via static sentinel + QEMU | No | $0 |
## 架构
```
+--------------------------------------------------------------------+
| SCOUT (Evidence Engine) |
| |
| Firmware --> Unpack --> Profile --> Inventory --> SBOM --> CVE |
| | | | | |
| Ghidra Binary Audit 40+ sigs NVD+ |
| auto-detect NX/PIE/etc local DB|
| |
| --> Taint --> FP Filter --> Attack Surface --> Findings |
| (HTTP-aware) (3-pattern) (IPC chains) (SARIF 2.1.0) |
| |
| --> Emulation --> [Fuzzing] --> Exploit Chain --> PoC --> Verify |
| |
| 42 stages . SHA-256 manifests . confidence cap 0.60 (static) |
| Outputs: SARIF + CycloneDX VEX + SLSA L2 + Markdown reports |
+--------------------------------------------------------------------+
| Handoff (firmware_handoff.json) |
+--------------------------------------------------------------------+
| Terminator (Orchestrator) |
| LLM Tribunal --> Dynamic Validation --> Verified Chain |
+--------------------------------------------------------------------+
```
| Layer | Role | Deterministic? |
|:------|:-----|:--------------:|
| **SCOUT** | Evidence production (42 stages) | Yes |
| **Handoff** | JSON contract between engine and orchestrator | Yes |
| **Terminator** | LLM tribunal, dynamic validation, exploit dev | No (auditable) |
## 漏洞利用提升策略
| Level | Requirements | Placement |
|:------|:-------------|:----------|
| `dismissed` | Critic rebuttal strong or confidence < 0.5 | Appendix only |
| `candidate` | Confidence 0.5-0.8, evidence exists but chain incomplete | Report (flagged) |
| `high_confidence_static` | Confidence >= 0.8, strong static evidence, no dynamic | Report (highlighted) |
| `confirmed` | Confidence >= 0.8 AND >= 1 dynamic verification artifact | Report (top) |
| `verified_chain` | Confirmed AND PoC reproduced 3x in sandbox | Exploit report |
CLI 参考
| Command | Description |
|---------|-------------|
| `./scout analyze ` | 完整的 42 阶段分析流水线 |
| `./scout analyze-8mb ` | 截断的 8MB 规范化跟踪 |
| `./scout stages --stages X,Y` | 重新运行特定阶段 |
| `./scout serve ` | 启动 Web 报告查看器 |
| `./scout mcp [--project-id ]` | 启动 MCP stdio 服务器 |
| `./scout tui ` | 终端 UI 仪表板 |
| `./scout ti` | TUI 交互模式 (最新运行) |
| `./scout tw` | TUI 监视模式 (自动刷新) |
| `./scout to` | TUI 单次执行 (最新运行) |
| `./scout t` | TUI 默认模式 (最新运行) |
| `./scout corpus-validate` | 验证语料库清单 |
| `./scout quality-metrics` | 计算质量指标 |
| `./scout quality-gate` | 检查质量阈值 |
| `./scout release-quality-gate` | 统一的发布质量关卡 |
**Exit codes:** `0` success, `10` partial, `20` fatal, `30` policy violation
基准测试
```
# FirmAE dataset 基准测试 (1,124 个固件镜像, 8 家厂商)
./scripts/benchmark_firmae.sh --parallel 8 --time-budget 1800 --cleanup
# 选项
--dataset-dir DIR # Firmware directory (default: aiedge-inputs/firmae-benchmark)
--results-dir DIR # Output directory
--parallel N # Concurrent jobs (default: 4)
--time-budget S # Seconds per firmware (default: 600)
--stages STAGES # Specific stages (default: full pipeline)
--max-images N # Limit images (0 = all)
--8mb # Use 8MB truncated track
--full # Include dynamic stages
--cleanup # Archive JSONs, delete run dirs (saves disk)
--dry-run # List files without running
# 基准测试后分析
PYTHONPATH=src python3 scripts/cve_rematch.py \
--results-dir benchmark-results/firmae-YYYYMMDD_HHMM \
--nvd-dir data/nvd-cache \
--csv-out cve_matches.csv
PYTHONPATH=src python3 scripts/analyze_findings.py \
--results-dir benchmark-results/firmae-YYYYMMDD_HHMM \
--output analysis_report.json
# Firmae dataset 设置
./scripts/unpack_firmae_dataset.sh [ZIP_FILE]
```
环境变量
### 核心配置
| Variable | Default | Description |
|----------|---------|-------------|
| `AIEDGE_LLM_DRIVER` | `codex` | LLM 提供者：`codex` / `claude` / `ollama` |
| `ANTHROPIC_API_KEY` | -- | Claude 驱动的 API 密钥 |
| `AIEDGE_OLLAMA_URL` | `http://localhost:11434` | Ollama 服务器 URL |
| `AIEDGE_LLM_BUDGET_USD` | -- | LLM 成本预算限制 |
| `AIEDGE_PRIV_RUNNER` | -- | 用于动态阶段的特权命令前缀 |
| `AIEDGE_FEEDBACK_DIR` | `aiedge-feedback` | Terminator 反馈目录 |
### Ghidra
| Variable | Default | Description |
|----------|---------|-------------|
| `AIEDGE_GHIDRA_HOME` | auto-detect | Ghidra 安装路径；探测 `/opt/ghidra_*`, `/usr/local/ghidra*` |
| `AIEDGE_GHIDRA_MAX_BINARIES` | `20` | 最大分析二进制文件数量 |
| `AIEDGE_GHIDRA_TIMEOUT_S` | `300` | 单个二进制文件的分析超时时间 |
### SBOM & CVE
| Variable | Default | Description |
|----------|---------|-------------|
| `AIEDGE_NVD_API_KEY` | -- | NVD API 密钥 (可选，提高速率限制) |
| `AIEDGE_NVD_CACHE_DIR` | -- | 跨运行的 NVD 响应缓存 |
| `AIEDGE_SBOM_MAX_COMPONENTS` | `500` | 最大 SBOM 组件数 |
| `AIEDGE_CVE_SCAN_MAX_COMPONENTS` | `50` | 进行 CVE 扫描的最大组件数 |
| `AIEDGE_CVE_SCAN_TIMEOUT_S` | `30` | 单次 NVD API 请求超时时间 |
### Fuzzing 与仿真
| Variable | Default | Description |
|----------|---------|-------------|
| `AIEDGE_AFLPP_IMAGE` | `aflplusplus/aflplusplus` | AFL++ Docker 镜像 |
| `AIEDGE_FUZZ_BUDGET_S` | `3600` | Fuzzing 时间预算 (秒) |
| `AIEDGE_FUZZ_MAX_TARGETS` | `5` | 最大 Fuzzing 目标二进制文件数 |
| `AIEDGE_EMULATION_IMAGE` | `scout-emulation:latest` | 仿真 Docker 镜像 |
| `AIEDGE_FIRMAE_ROOT` | `/opt/FirmAE` | FirmAE 安装路径 |
| `AIEDGE_QEMU_GDB_PORT` | `1234` | QEMU GDB 远程端口 |
### 质量关卡
| Variable | Default | Description |
|----------|---------|-------------|
| `AIEDGE_QG_PRECISION_MIN` | `0.9` | 最低精确率阈值 |
| `AIEDGE_QG_RECALL_MIN` | `0.6` | 最低召回率阈值 |
| `AIEDGE_QG_FPR_MAX` | `0.1` | 最高误报率 |
运行目录结构
```
aiedge-runs//
├── manifest.json
├── firmware_handoff.json
├── provenance.intoto.jsonl # SLSA L2 attestation
├── input/firmware.bin
├── stages/
│ ├── extraction/ # Unpacked filesystem
│ ├── inventory/
│ │ └── binary_analysis.json # Per-binary hardening + symbols
│ ├── enhanced_source/
│ │ └── sources.json # HTTP input sources + web server detection
│ ├── sbom/
│ │ ├── sbom.json # CycloneDX 1.6
│ │ └── vex.json # VEX exploitability
│ ├── cve_scan/
│ │ └── cve_matches.json # NVD + known signature matches
│ ├── taint_propagation/
│ │ └── taint_results.json # Taint paths + call chains
│ ├── ghidra_analysis/ # Decompiled functions (optional)
│ ├── chain_construction/
│ │ └── chains.json # Same-binary + cross-binary IPC chains
│ ├── findings/
│ │ ├── findings.json # All findings
│ │ ├── pattern_scan.json # Static pattern matches
│ │ ├── sarif.json # SARIF 2.1.0 export
│ │ └── stage.json # SHA-256 manifest
│ └── ... # 42 stage directories total
└── report/
├── viewer.html # Web dashboard
├── report.json
├── analyst_digest.json
└── executive_report.md
```
验证脚本
```
# 证据链完整性
python3 scripts/verify_analyst_digest.py --run-dir aiedge-runs/
python3 scripts/verify_verified_chain.py --run-dir aiedge-runs/
# Report schema 合规性
python3 scripts/verify_aiedge_final_report.py --run-dir aiedge-runs/
python3 scripts/verify_aiedge_analyst_report.py --run-dir aiedge-runs/
# Security invariants
python3 scripts/verify_run_dir_evidence_only.py --run-dir aiedge-runs/
python3 scripts/verify_network_isolation.py --run-dir aiedge-runs/
# Quality gates
./scout release-quality-gate aiedge-runs/
```
## 文档
| Document | Purpose |
|:---------|:--------|
| [Blueprint](docs/blueprint.md) | 流水线架构与设计原理 |
| [Status](docs/status.md) | 当前实现状态 |
| [Artifact Schema](docs/aiedge_firmware_artifacts_v1.md) | Profiling + 清单契约 |
| [Adapter Contract](docs/aiedge_adapter_contract.md) | Terminator-SCOUT 交接协议 |
| [Report Contract](docs/aiedge_report_contract.md) | 报告结构与治理 |
| [Analyst Digest](docs/analyst_digest_contract.md) | 摘要模式与判定 |
| [Verified Chain](docs/verified_chain_contract.md) | 证据要求 |
| [Duplicate Gate](docs/aiedge_duplicate_gate_contract.md) | 跨运行去重规则 |
| [Known CVE Ground Truth](docs/known_cve_ground_truth.md) | CVE 验证数据集 |
| [Upgrade Plan v2](docs/upgrade_plan_v2.md) | v2.0 升级计划 |
| [LLM Roadmap](docs/roadmap_llm_agent_integration.md) | LLM 集成策略 |
## 安全与伦理
SCOUT 旨在用于签约安全审计、漏洞研究（负责任的披露）以及实验室环境下的 CTF/培训。动态验证在网络隔离的沙容器中运行。不包含任何武器化的 Payload。
## 许可证
MIT
标签：AI安全, Chat Copilot, CISA项目, CVE匹配, CycloneDX, DevSecOps, DNS 反向解析, Ghidra, Google搜索, LLM, MCP, Python, SARIF, SBOM, SLSA, TUI, Unmanaged PE, URL发现, VEX, Web查看器, 上游代理, 云安全监控, 云资产清单, 固件分析, 固件安全, 安全检测, 嵌入式安全, 开源安全工具, 文档安全, 无后门, 物联网安全, 硬件无关, 网络安全, 证据链, 请求拦截, 身份验证强制, 逆向工具, 逆向工程, 逆向工程平台, 配置审计, 隐私保护, 零依赖, 静态分析