chavooosss/SpecterAI
GitHub: chavooosss/SpecterAI
一款由 LangGraph 驱动的漏洞赏金自主 agent，能够自动完成从目标同步、范围验证到侦测分析和报告生成的完整流程。
Stars: 0 | Forks: 0
# SpecterAI
**由 LangGraph 驱动的自主漏洞赏金 Agent**
[](https://www.python.org/)
[](tests/)
[](LICENSE)
[](https://github.com/langchain-ai/langgraph)
[](platforms/)
*范围安全的侦测 · LLM 驱动的分析 · 有据可查的报告*
## 什么是 SpecterAI？
大规模的漏洞赏金挖掘需要人类难以维持的三件事：**纪律**、**记忆**和**速度**。
SpecterAI 是一个自主 agent，负责处理重复性的侦测到验证 pipeline —— 从 HackerOne 或 Intigriti 同步项目范围，将其作为严格的防火墙执行，串联行业标准攻击工具，并通过 LLM 驱动的 ReAct 循环呈现可操作的发现。**最终提交决策的控制权始终掌握在您手中。**
```
sync scope → validate target → run tools → reason over output → report findings
```
## 功能
| 功能 | 描述 |
|---|---|
| **平台同步** | 从 HackerOne 和 Intigriti 拉取活跃项目及范围 |
| **范围防火墙** | 在任何 subprocess 运行前严格拒绝超出范围的目标 |
| **动态武器库** | 通过 JSON 添加 CLI 工具 —— 无需编写新的 Python 代码 |
| **LangGraph 大脑** | ReAct 循环：规划 → 调用工具 → 分析 → 循环 → 报告 |
| **多提供商 LLM** | 支持 OpenAI (GPT-4o) 或 Anthropic (Claude) —— 可灵活配置 |
| **审计追踪** | 记录每次工具调用的状态、产出物和持续时间 |
| **双重报告** | 生成专业的 Markdown 和机器可读的 JSON 导出文件 |
| **Web 仪表盘** | 通过 SSE 提供 ReAct 实时流的 React 控制面板 |
| **117 项测试** | 涵盖范围、数据库、工具和 agent 的单元与集成测试 |
## 架构
```
┌──────────────────────────────────────────────────────────────────┐
│ main.py — CLI / api/ — FastAPI + SSE / gui/ — React │
└──────────────────────────┬───────────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────┐ ┌─────────────┐ ┌──────────────┐
│platforms/│ │ agent/ │ │ reporting/ │
│ H1 + I13 │ │ LangGraph │ │ MD · JSON │
└────┬─────┘ └──────┬──────┘ └──────────────┘
│ │
▼ ▼
┌──────────┐ ┌─────────────┐
│ scope/ │◄───│ tools/ │
│ firewall │ │ registry │
└────┬─────┘ └──────┬──────┘
│ │
└────────┬─────────┘
▼
┌────────────┐
│ db/ │ SQLite: programs · scope · scans · findings
└────────────┘
```
### 范围防火墙
在任何工具执行之前，每个目标都会经过 `ScopeValidator` 验证：
1. 匹配任意 **超出范围** 规则 → **拒绝**（无条件）
2. 不匹配任何 **范围内** 规则 → **拒绝**
3. 匹配 **范围内** 规则 → **允许**
支持通配符 (`*.target.com`)、域名、URL、IP、CIDR 块和正则表达式规则。解析自 HackerOne、Intigriti 以及手动配置的 JSON schema。
### LangGraph Agent
```
HumanMessage("Begin engagement on api.target.com")
│
▼
┌─────────┐ tool calls? ┌───────────────┐
│Reasoner │ ──────────────► │ Tool Executor │
│ (LLM) │ ◄────────────── │ (scope-gated) │
└─────────┘ ToolMessages └───────────────┘
│
│ no tool calls / finished
▼
END — findings in state
```
推理器接收 `ToolMessage` 形式的工具输出，并进行迭代，直到发现漏洞或确定不再有剩余的范围内攻击面。
### 工具注册表
共存两种注册方式：
| 类型 | 添加方式 | 示例 |
|---|---|---|
| **内置类** | 带有自定义输出解析器的 Python 模块 | `NucleiTool` (JSON-line 解析) |
| **配置驱动** | 编辑 `tools/tools_config.json` | 添加 `ffuf`、`amass` 或任何二进制程序 |
所有工具都继承自 `BaseTool.run()`，该方法会在每次 subprocess 调用前后强制执行范围验证并写入 `ScanLog` 生命周期记录。
## 快速开始
### 前置条件
- Python 3.11+
- 至少一个 API key：[OpenAI](https://platform.openai.com/) 或 [Anthropic](https://console.anthropic.com/)
- 根据需要在 `PATH` 中配置 CLI 工具：`subfinder`、`nmap`、`nuclei`、`httpx`、`naabu`
```
# 安装基于 Go 的安全工具（Kali / Ubuntu）
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
sudo apt-get install nmap
```
### 安装 SpecterAI
```
git clone https://github.com/chavooosss/SpecterAI.git
cd SpecterAI
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
```
编辑 `.env` 并至少添加您的 LLM API key：
```
# 选择一个 provider
DEFAULT_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
# 可选：HackerOne 平台同步
HACKERONE_API_IDENTIFIER=your_username
HACKERONE_API_TOKEN=your_token_secret
```
## 使用说明
### 典型工作流
```
# 1. 从 HackerOne 同步 programs 和 scope
python main.py --sync-platform hackerone
# 2. 查看已导入的内容
python main.py --list-programs
# 3. 在 in-scope target 上运行 autonomous agent
python main.py --run 1 --target api.example.com
# 4. 导出 findings
python main.py --report 1 --output reports/program_1.md
python main.py --report 1 --output reports/program_1.json
```
### 所有 CLI 选项
```
python main.py --help
--sync-platform {hackerone,intigriti} Pull programs + scope from platform
--list-programs List stored programs
--include-inactive Include inactive programs
--run PROGRAM_ID Start autonomous agent
--target TARGET In-scope target for --run
--include-config-tools Also load tools from tools_config.json
--report PROGRAM_ID Generate vulnerability report
--scan-log-id N Filter report to a specific scan
--output FILE Output path (.md or .json)
--format {markdown,json} Explicit format override
```
### Web 仪表盘
```
python run_gui.py
# 或：./run_gui.sh
```
| URL | 服务 |
|---|---|
| `http://127.0.0.1:5173` | React 控制面板 |
| `http://127.0.0.1:8000/api/health` | FastAPI 后端 |
| `http://127.0.0.1:8000/api/events` | SSE 事件流 |
**仪表盘面板：**
- **实时终端** —— 实时观察 ReAct 循环逐个工具执行的过程
- **目标管理器** —— 同步平台、选择项目、启动 agent
- **设置** —— 从浏览器管理 `.env` 凭证（敏感信息已掩码）
仅使用 API 或仅使用 GUI：
```
python run_gui.py --api-only
python run_gui.py --gui-only
```
## 添加自定义工具
编辑 `tools/tools_config.json` —— 无需 Python 代码：
```
{
"name": "feroxbuster",
"binary": "feroxbuster",
"description": "Fast content discovery scanner",
"enabled": true,
"strict_host_args": true,
"timeout_seconds": 600,
"args_template": ["-u", "https://{target}", "--silent", "--no-state"]
}
```
`{target}` 将在 runtime 被替换。该工具会自动进行范围验证、记录日志，并通过工具桥接供 LLM 调用。
## 配置参考
请参阅 [`.env.example`](.env.example) 获取完整的注释模板。
| 变量 | 适用场景 | 默认值 | 描述 |
|---|---|---|---|
| `OPENAI_API_KEY` | `--run` (OpenAI) | — | OpenAI API key |
| `ANTHROPIC_API_KEY` | `--run` (Anthropic) | — | Anthropic API key |
| `DEFAULT_LLM_PROVIDER` | `--run` | `openai` | `openai` 或 `anthropic` |
| `DEFAULT_LLM_MODEL` | `--run` | `gpt-4o` | 模型标识符 |
| `HACKERONE_API_IDENTIFIER` | `--sync-platform hackerone` | — | HackerOne 用户名 |
| `HACKERONE_API_TOKEN` | `--sync-platform hackerone` | — | HackerOne token 密钥 |
| `INTIGRITI_API_TOKEN` | `--sync-platform intigriti` | — | Intigriti bearer token |
| `MAX_REACT_ITERATIONS` | `--run` | `25` | ReAct 循环迭代上限 |
| `DEFAULT_TOOL_TIMEOUT_SECONDS` | `--run` | `300` | Subprocess 超时时间 |
| `LOG_LEVEL` | 始终需要 | `INFO` | `DEBUG` / `INFO` / `WARNING` |
| `DATABASE_PATH` | 可选 | `data/specter.db` | SQLite 文件路径 |
## 项目结构
```
SpecterAI/
├── main.py CLI entry point & orchestration
├── config.py Pydantic-settings loader (type-safe)
├── run_gui.py / run_gui.sh Launch FastAPI + React together
│
├── agent/
│ ├── graph.py LangGraph StateGraph assembly
│ ├── reasoner.py LLM node (OpenAI / Anthropic)
│ ├── state.py AgentState TypedDict + reducers
│ ├── tool_bridge.py LangChain ↔ SpecterAI tool adapter
│ └── prompts.py System prompt for the bug bounty agent
│
├── scope/
│ ├── parser.py HackerOne · Intigriti · manual JSON parsers
│ └── validator.py Bypass-proof scope enforcement engine
│
├── platforms/
│ ├── hackerone.py HackerOne API client (paginated)
│ └── intigriti.py Intigriti API client
│
├── tools/
│ ├── base_tool.py Secure execution contract (scope + ScanLog)
│ ├── subfinder.py Subdomain enumeration
│ ├── nmap.py Port/service discovery
│ ├── nuclei.py Template vulnerability scanner
│ ├── custom_http.py Targeted HTTP probe tool
│ ├── registry.py ToolRegistry + ToolFactory
│ └── tools_config.json JSON-configured tool definitions
│
├── reporting/
│ ├── markdown_reporter.py Human-readable Markdown reports
│ ├── json_reporter.py Machine-readable JSON exports
│ └── analyzer.py Severity aggregation + deduplication
│
├── db/
│ ├── models.py SQLAlchemy ORM (Program · Scope · Scan · Finding)
│ └── repository.py Typed CRUD layer
│
├── api/
│ ├── main.py FastAPI app + SSE event bus
│ └── agent_runner.py Background agent execution
│
├── gui/ React + TypeScript dashboard (Vite)
├── utils/
│ ├── subprocess_runner.py shell=False, whitelist, arg sanitization
│ └── logger.py Structured JSON + colorized console
│
└── tests/
├── conftest.py Shared fixtures (isolated per-test DB)
├── unit/ Scope, DB, tool unit tests
└── integration/ Platform parsers + agent graph tests
```
## 运行测试
```
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest
```
```
======================== 117 passed in 0.69s ========================
```
测试使用每个测试独立的 SQLite 数据库，并模拟 LLM 调用 —— 无需真实的 API key。
## 安全设计说明
- **始终使用 `shell=False`** —— 目标参数无法进行 shell injection
- **二进制白名单** —— 只能执行预先批准的二进制文件
- **参数过滤** —— 阻止所有 argv token 中的 shell 元字符
- **可配置超时** —— 支持单工具和全局硬性上限
- **范围防火墙无条件执行** —— 超出范围的匹配始终优先，即使存在带通配符的范围内规则
- **参数化 SQL** —— 所有查询均通过 SQLAlchemy ORM 执行，无字符串插值
## 路线图
- [ ] 向量记忆层 —— 基于 embedding 的跨会话漏洞发现召回 (`memory/vector_store.py`)
- [ ] 为平台 API 客户端集成限流器
- [ ] 更多平台适配器（Bugcrowd、YesWeHack）
- [ ] 并行多目标任务编排
- [ ] 生成 AI 驱动的 PoC 报告草稿，以便直接提交至平台
## 许可证
MIT —— 详情请参阅 [LICENSE](LICENSE)。
## 免责声明
SpecterAI 是一款安全研究与自动化框架，专为授权的漏洞赏金挖掘和认可的渗透测试而设计。作者不对任何滥用行为负责。请始终遵守项目规则、适用法律和负责任的披露准则。**绝不在未经明确书面授权的情况下测试目标。**标签：DLL 劫持, LangGraph, Python, 人工智能代理, 大语言模型, 实时处理, 密码管理, 无后门, 自动化渗透测试, 逆向工具