Reinasboo/SPARTAN
GitHub: Reinasboo/SPARTAN
一款融合 Web2 与 Web3 安全审计的自主 AI 智能体，通过五阶段方法论实现从威胁建模到漏洞验证的完整渗透测试流程。
Stars: 0 | Forks: 0
# SPARTAN v2.0 — 自主安全审计与漏洞利用智能体
```
_______ ___ ____ ____ ___ _ _
/ __/ _ \/ _ |/ __ \/_ / / _ | / \/ |
\__ \/ ___/ __ / /_/ //_ < / __ |/ , |
/___/_/ /_/ |_\____/____//_/ |_/_/|_|
```
SPARTAN 是一款自主 AI 安全研究智能体，专为授权渗透测试、Bug Bounty 悬赏狩猎和智能合约审计而设计。它编排了一套结构化的 5 阶段方法论，维护持久会话内存，并生成可直接提交的专业报告。
## SPARTAN 的功能
| 能力 | 详情 |
|---|---|
| **攻击面测绘** | 枚举所有端点、入口点、角色、信任边界 |
| **威胁建模** | 识别威胁行为者、关键假设和高风险组件 |
| **漏洞分析** | 完整的 Web2 + Web3 分类法 — 25+ 种漏洞类型 + OWASP Top 10 |
| **侦查工具生成** | 生成可直接运行的 Nmap, Subfinder, WhatWeb 和 Schemathesis 命令 |
| **漏洞利用验证** | 安全、本地化的 PoC 生成 — Playwright 浏览器脚本、curl 模板、Python 脚本 |
| **数据流分析** | 针对注入和 XSS 漏洞检测的 Source-to-Sink 污点分析 |
| **协议检查清单** | 针对 12+ 种协议类型的 DeFi 专用漏洞检查清单 |
| **报告生成** | 符合提交标准的 Markdown 报告，包含 CVSS v3.1 评分 |
| **修复审查** | 验证已应用的修复，检查是否存在回归 |
| **会话持久化** | 完整的审计工作区保存至磁盘，随时可恢复 |
| **多提供商 LLM** | 支持 OpenAI, Anthropic 或 OpenRouter |
| **YAML 审计配置** | 声明式 `.yaml` 配置文件，用于可重复的脚本化审计 |
## 审计领域
- Web 应用程序 (REST, GraphQL, WebSockets, SPAs)
- APIs 与后端 (认证流程、业务逻辑、速率限制)
- 智能合约 (Solidity, Vyper, EVM 字节码推理)
- DeFi 协议 (AMMs, 借贷, 金库, 跨链桥, 质押)
- 账户抽象 (ERC-4337 bundler/paymaster/wallet)
- 治理与 DAOs (投票, 时间锁, 提案流程)
- L2 与跨链 (排序器风险, 跨链桥, 终局性)
- 密码学系统 (签名, ZK 电路, 密钥管理)
- 认证系统 (OAuth2, JWT, SAML, MFA 绕过, TOTP/2FA)
## 5 阶段方法论
```
Phase 1 — Recon → Attack Surface Map + Threat Model + Recon Tool Commands
Phase 2 — Analysis → OWASP Top 10 + Protocol Checklists + Dataflow Analysis
Phase 3 — Validation → Playwright/curl PoC generation + CVSS v3.1 scoring
Phase 4 — Report → Submission-ready Markdown reports
Phase 5 — Remediation → Fix verification + regression check
```
## 快速开始
### 1. 安装依赖
```
pip install -r requirements.txt
```
### 2. 设置 API 密钥
```
# 复制示例配置
copy .env.example .env
# 编辑 .env 并设置你的 API key：
# OPENAI_API_KEY=sk-... (用于 OpenAI)
# ANTHROPIC_API_KEY=sk-ant-... (用于 Anthropic)
# OPENROUTER_API_KEY=sk-or-... (用于 OpenRouter)
```
或者直接设置环境变量：
```
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."
$env:SPARTAN_LLM_PROVIDER = "openai"
$env:SPARTAN_LLM_MODEL = "gpt-4o"
# 或者使用 Gemini
$env:GEMINI_API_KEY = "AIza..."
$env:SPARTAN_LLM_PROVIDER = "gemini"
$env:SPARTAN_GEMINI_MODEL = "gemini-2.0-flash"
```
### 3. 运行 SPARTAN
```
# 交互模式（推荐）
python main.py
# 直接以 target 开始
python main.py --target "UniswapV3 fork vault contract"
# 以 source 文件开始
python main.py --target "MyVault" --file contracts/Vault.sol
# 加载 YAML audit config（参见 example-audit-config.yaml）
python main.py --config audit.yaml
# 使用 Anthropic Claude
python main.py --provider anthropic
# 使用 Google Gemini
python main.py --provider gemini
# 恢复上次会话
python main.py --resume
```
## 审计配置文件
对于可重复、脚本化的审计，可以在 YAML 文件中定义完整范围，并使用 `--config` 传递：
```
python main.py --config example-audit-config.yaml
```
配置文件控制以下内容：
| 部分 | 关键选项 |
|---|---|
| `scope` | `url`, `repo`, `openapi_path`, `protocol_type`, `contract_addresses`, `chain_id` |
| `authentication` | `login_type` (`none` \| `form` \| `api_key` \| `bearer_token` \| `basic` \| `oauth` \| `web3` \| `totp`), 通过环境变量设置凭证, 多步骤 `login_flow` |
| `rules` | `include_owasp_top10`, `include_api_security_top10`, `include_web3_vulns`, `include_protocol_vulns`, `no_exploit_no_report`, `max_severity_to_report`, `focus`, `avoid`, `custom_checklist` |
| `pipeline` | `max_concurrent_agents`, `timeout_per_phase_seconds`, `retry_on_failure`, `auto_advance_phases`, `stream_output`, `save_intermediate`, `retry_preset` |
| `auditor_notes` | 注入到每个阶段提示中的自由文本上下文 |
| `known_issues` | 需优先关注的已知问题区域 |
请参阅 [example-audit-config.yaml](example-audit-config.yaml) 获取涵盖 Web 应用和 DeFi 目标的完整注释模板。
## 交互式命令
| 命令 | 操作 |
|---|---|
| `target ` | 设置或更改审计目标 |
| `phase ` | 跳转至 Recon / Analysis / Validation / Report / Remediation 阶段 |
| `continue` | 进入下一阶段 |
| `status` | 显示会话摘要（发现、阶段、目标） |
| `report` | 生成完整的 Markdown 审计报告 |
| `findings` | 列出本次会话中的所有发现 |
| `finding ` | 显示 FINDING-001, FINDING-002 等的详细信息 |
| `sessions` | 列出所有已保存的会话 |
| `load ` | 通过 ID 加载之前的会话 |
| `save` | 强制保存当前会话 |
| `clear` | 清除对话历史（保留发现） |
| `model` | 显示当前活跃的 LLM 模型 |
| `help` | 显示所有命令 |
| `exit` | 保存并退出 |
## 使用示例
### 审计 Solidity 智能合约
```
> python main.py --target "StakingVault" --file contracts/StakingVault.sol
[Recon]> continue
[Analysis]> continue
[Validation]> continue
[Report]> report
```
### Bug Bounty Web 应用审计
```
> python main.py
[SPARTAN]> target https://api.example.com
[Recon]> The API uses JWT auth with RS256. Admin panel at /admin.
REST endpoints: /api/v1/users, /api/v1/orders, /api/v1/upload
[Analysis]> continue
[Validation]> continue
[Report]> report
```
### 使用 YAML 配置的脚本化审计
```
> python main.py --config my-audit.yaml
[Recon]> continue
[Analysis]> continue
[Validation]> continue
[Report]> report
```
### 恢复之前的会话
```
> python main.py --sessions
ID Target Phase Findings Last Active
──────────────────────────────────────────────────────────────────────────────────
a1b2c3d4 StakingVault Analysis 3 2026-03-03 09:15
> python main.py --load a1b2c3d4
```
## Shannon 集成 — 新特性
SPARTAN v2.0 融合了 Shannon 的多智能体分析和实时漏洞利用能力：
### 侦查工具命令 (`agent/tools/recon_tools.py`)
SPARTAN 在第 1 阶段生成操作员可直接运行的 Shell 命令：
| 工具 | 用途 |
|---|---|
| **Nmap** | 端口/服务发现 — 默认、深度、UDP、漏洞脚本和 Web 模式 |
| **Subfinder** | 被动子域名枚举，可选 DNS 解析 |
| **WhatWeb** | 技术指纹识别（框架、CMS、服务器标头） |
| **Schemathesis** | OpenAPI Schema 驱动的 API 模糊测试 — 感知 auth-token |
命令以注释块（工具、标志、预期输出）的形式打印，供操作员复制运行。SPARTAN 绝不会自动执行这些命令。
### Web 漏洞利用模板 (`agent/tools/web_exploits.py`)
具有强制安全等级的 Payload 库和 PoC 生成器：
| PoC 类型 | 安全等级 | 描述 |
|---|---|---|
| `build_playwright_script()` | LOCAL | 用于 XSS, IDOR, CSRF, 认证绕过的无头浏览器 PoC |
| `build_curl_poc()` | LOCAL/SAFE | 用于 SQLi, SSRF, 文件遍历等的 curl 复现步骤 |
| Payload 库 | — | SQLi (报错/盲注/时间), XSS, SSTI, SSRF, CMDi, 路径遍历 |
每个 `PoC` 对象都带有 `PoCSafety` 标签 (`SAFE` / `LOCAL` / `SIMULATED`) 和格式化的 `.format()` 方法，以便包含在报告中。
### 数据流分析 (`agent/tools/dataflow.py`)
针对源代码片段的静态污点分析：
- 检测 **20+ 种 Source 模式** (请求参数, 标头, Cookies, DB 读取, 环境变量, 文件读取)
- 检测 **20+ 种 Sink 模式** (SQL 查询, `eval`, `exec`, `render`, `mark_safe`, `innerHTML`, Shell 命令)
- 返回每个发现的严重程度、Source 类型、Sink 类型和匹配的代码行
- `build_dataflow_prompt()` 将分析封装为结构化的 LLM 提示，用于第 2 阶段
### OWASP 知识库 (`agent/knowledge/owasp.py`)
- 完整的 **OWASP Top 10 (2021)** — A01 至 A10，每类包含 Payload 示例
- 完整的 **OWASP API Security Top 10 (2023)** — API01 至 API10
- `search_owasp(query)` — 跨 ID、名称和类别的关键词搜索
- `build_owasp_prompt(include_api=True)` — 将 OWASP 上下文注入第 2 阶段分析提示
### 协议漏洞检查清单 (`agent/knowledge/protocol_vulns.py`)
针对 12 种协议类型的 DeFi 专用检查清单库：
`lending` · `dexes` · `bridge` · `oracle` · `governance` · `algo-stables` · `liquid-staking` · `yield-aggregator` · `staking-pool` · `cdp` · `nft-marketplace` · `account-abstraction`
- `detect_protocol_type(description)` — 从自由文本中自动检测协议类型
- `get_protocol_checklist(protocol_type)` — 返回指定类型的完整检查清单
- `get_multi_protocol_checklist(types)` — 为多协议目标组合检查清单
### “无 PoC 不报告”策略
通过审计配置中的 `rules.no_exploit_no_report: true` 控制。启用后，最终报告仅包含附有确认 `PoC` 对象的发现。未确认的发现会被降低严重程度并标记为需要进一步验证。
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SPARTAN_LLM_PROVIDER` | `openai` | LLM 提供商: `openai` \| `anthropic` \| `openrouter` \| `gemini` |
| `SPARTAN_LLM_MODEL` | `gpt-4o` | OpenAI 模型名称 |
| `SPARTAN_ANTHROPIC_MODEL` | `claude-opus-4-5` | Anthropic 模型名称 |
| `SPARTAN_GEMINI_MODEL` | `gemini-2.0-flash` | Gemini 模型名称 (`gemini-2.0-flash` \| `gemini-2.5-pro-preview-03-25`) |
| `OPENAI_API_KEY` | — | OpenAI API 密钥 |
| `ANTHROPIC_API_KEY` | — | Anthropic API 密钥 |
| `OPENROUTER_API_KEY` | — | OpenRouter API 密钥 |
| `GEMINI_API_KEY` | — | Google Gemini API 密钥 (可在 [aistudio.google.com](https://aistudio.google.com) 获取) |
| `SPARTAN_MAX_TOKENS` | `8192` | 每次响应的最大 Token 数 |
| `SPARTAN_TEMPERATURE` | `0.2` | LLM Temperature |
| `SPARTAN_STREAM` | `true` | 实时流式输出 |
| `SPARTAN_SAVE_SESSIONS` | `true` | 自动保存会话状态 |
## 项目结构
```
Spartan/
├── main.py # CLI entry point (--config/-c flag)
├── requirements.txt
├── .env.example
├── example-audit-config.yaml # Annotated YAML config template
├── sessions/ # Auto-saved session files
├── reports/ # Generated audit reports
├── tests/ # Test suite — 244 tests, all passing
│ ├── test_session.py # Session + Finding data models (26 tests)
│ ├── test_cvss.py # CVSS v3.1 scoring engine (29 tests)
│ ├── test_knowledge.py # protocol_vulns + OWASP knowledge bases (35 tests)
│ ├── test_tools.py # Recon tools + web exploits + dataflow (58 tests)
│ ├── test_phases.py # Phase prompt builders (33 tests)
│ └── test_spartan.py # SpartanAgent orchestration (35 tests)
├── config/
│ ├── settings.py # All configuration & constants
│ ├── prompts.py # System prompts for each phase
│ └── audit_config.py # YAML audit config parser & dataclasses
└── agent/
├── spartan.py # Core SpartanAgent class
├── session.py # Session & finding data models
├── llm_client.py # Multi-provider LLM abstraction
├── formatter.py # Terminal output formatting
├── phases/
│ ├── recon.py # Phase 1 — Reconnaissance + recon tool injection
│ ├── analysis.py # Phase 2 — OWASP + protocol checklist + dataflow
│ ├── validation.py # Phase 3 — PoC generation + CVSS scoring
│ ├── report.py # Phase 4 — Report generation
│ └── remediation.py # Phase 5 — Remediation review
├── tools/
│ ├── recon_tools.py # Nmap / Subfinder / WhatWeb / Schemathesis builders
│ ├── web_exploits.py # Playwright PoCs, curl templates, payload banks
│ └── dataflow.py # Source-to-sink taint analysis engine
└── knowledge/
├── web2_vulns.py # Web2/API vulnerability taxonomy
├── web3_vulns.py # Web3/DeFi vulnerability taxonomy
├── protocol_vulns.py # DeFi protocol-specific checklists (12 types)
├── owasp.py # OWASP Top 10 (2021) + API Security Top 10 (2023)
└── cvss.py # CVSS v3.1 scoring engine
```
## 运行测试
```
# 运行完整 test suite
python -m pytest tests/ -v
# 运行特定 module
python -m pytest tests/test_tools.py -v
# 仅显示简短摘要
python -m pytest tests/ --tb=short
```
预期结果：3 秒内 **244 项测试通过**（所有测试均为离线 — 无 LLM 调用）。
## 道德与法律声明
SPARTAN 在严格的道德护栏下运行，这些护栏**无法被覆盖**：
- **必须授权** — 仅测试您被明确授权测试的系统
- **禁止生产环境利用** — 所有 PoC 必须是安全、本地、Fork 或模拟的
- **禁止真实数据窃取** — PoC 用于证明访问权限，不提取真实用户数据
- **禁止恶意软件生成** — PoC 展示漏洞类别，而非武器化 Payload
- **仅限授权用途** — Bug Bounty 项目、CTF、授权红队演练、安全研究
*SPARTAN v2.0 — 为精英安全研究打造。仅限授权场景。*
标签：API安全, AppImage, Bug Bounty, CISA项目, CTI, CVSS评分, DeFi安全, EVM字节码分析, GitHub, JSON输出, LLM安全应用, Maven, Nmap, OWASP Top 10, Petitpotam, PE 加载器, Playwright, PoC生成, Red Teaming, Solidity安全, TShark, Web3安全, Web应用防火墙, Web报告查看器, 人工智能安全, 代码生成, 区块链安全, 可自定义解析器, 合规性, 威胁建模, 安全Agent, 安全报告生成, 实时处理, 密码管理, 恶意样本开发, 攻击模拟, 攻击面映射, 智能合约审计, 渗透测试工具, 漏洞验证, 特征检测, 自动化安全审计, 虚拟驱动器, 逆向工具, 驱动签名利用