glorybnat/aegis-pentest
GitHub: glorybnat/aegis-pentest
一款基于 AI 编排的自主 Web 渗透测试 agent，通过 PTES 方法论和 80+ 工具自动完成从侦察到报告的完整测试流程。
Stars: 6 | Forks: 0
# aegis · v0.12.0
**自适应交互与通用检查扫描器**
一个自主的、由 AI 编排的 Web 渗透测试 agent。Aegis 负责处理侦察、指纹识别、漏洞发现、验证和报告，从而让人类渗透测试者专注于真正需要人工判断的工作。
## 它是什么
Aegis 针对目标 Web 运行结构化的、方法论驱动的测试任务。它会分析主机环境，对目标技术栈进行指纹识别，从 PTES + OWASP WSTG v4.2 剧本中选择相关的工具和测试，并发执行它们，最后生成带有修复指导且经过验证的漏洞报告。
它不是 Burp Suite 的替代品。它是为人类渗透测试者提供信息的自主侦察和漏洞发现层，可消除约 70% 的日常繁杂工作。
**内置在运行时的严格约束：**
- 每次测试任务在进行任何网络出口流量之前，都需要一个已签署的 `scope.yaml`。
- 在 socket 打开之前，每个外部请求都会与范围内和范围外的规则进行匹配。
- 范围违规会中止当前任务，并将其写入审计日志。
- 破坏性工具（`sqlmap`、`wpscan`、`commix`、`kerbrute`、`crackmapexec` 等）未经操作员批准拒绝运行，除非 `scope.yaml` 明确启用它们。
- 没有任何可以绕过范围的 `--force` 标志。
## 安装说明
### 选项 A — Docker（推荐，所有工具已预装）
```
# 拉取预构建镜像（约 4 GB）或在本地构建（约 15-30 分钟）
aegis docker pull # from GitHub Container Registry
# 或者
aegis docker build # build locally from Dockerfile
# 运行一个 engagement
export ANTHROPIC_API_KEY=sk-ant-...
aegis docker run engagements/2026-acme
# 带有 PATH 上所有工具的交互式 shell
aegis docker shell
# 检查镜像状态和工具清单
aegis docker status
```
Docker 镜像基于 **Kali rolling**，并包含了目录中的每一个工具。
### 选项 B — PyPI
```
pip install aegis-pentest
# 或
pipx install aegis-pentest
```
### 选项 C — Arch (AUR)
```
yay -S aegis-pentest
# 或
paru -S aegis-pentest
```
可选依赖覆盖了完整的工具面；只需安装你需要的即可。
### 选项 D — 原生安装脚本（一行命令）
```
# 自动检测 Arch、Kali、Ubuntu/Debian、Fedora、macOS
curl -fsSL https://raw.githubusercontent.com/glorybnat/aegis-pentest/main/scripts/install.sh | bash
# 或者从 repo 开始
bash scripts/install.sh
# 改为构建 Docker 镜像
bash scripts/install.sh --docker
```
### 选项 E — 从源码安装
```
git clone https://github.com/glorybnat/aegis-pentest.git
cd aegis-pentest
pip install -e .
cd tui && npm install && npm run build
```
安装 AEGIS 后，检测主机上已有的工具并补齐其余工具：
```
aegis init # detect what's installed
aegis env tools --missing # show what's missing + install commands
aegis env install --missing # install everything (no-sudo tools)
aegis env install --missing --dry-run # preview first
```
**要求：**
- Python 3.12+
- 环境中包含 `ANTHROPIC_API_KEY`
- Docker（选项 A）或渗透测试工具链（选项 B–E）
## 快速开始
```
# Docker 快速开始（零主机配置）
export ANTHROPIC_API_KEY=sk-ant-...
aegis docker build # or: aegis docker pull
aegis docker run engagements/2026-acme
# 原生快速开始
# 首次运行：分析主机环境，列出缺失的工具
aegis init
# 同步知识库（NVD、GHSA、nuclei-templates、CISA KEV、FIRST EPSS）
aegis kb sync
# 创建新的 engagement
aegis engagement new --client "Acme Corp" --domain "acme.com"
# 填写授权详情
vim engagements/2026-05-acme/scope.yaml
# 可选：从现有的 API spec 或 proxy trace 中提取 endpoints
aegis ingest openapi engagements/2026-05-acme/spec.yaml --engagement engagements/2026-05-acme
aegis ingest postman engagements/2026-05-acme/collection.json --engagement engagements/2026-05-acme
aegis ingest har engagements/2026-05-acme/burp.har --engagement engagements/2026-05-acme
# 运行
aegis run engagements/2026-05-acme
# 在崩溃或按下 Ctrl+C 后从最后完成的阶段恢复
aegis run engagements/2026-05-acme # picks up state.json automatically
# 生成报告 — md/html/json/sarif/h1/bugcrowd，或 "all"
aegis report engagements/2026-05-acme --format html
aegis report engagements/2026-05-acme --format sarif # GitHub/GitLab code scanning
aegis report engagements/2026-05-acme --format h1 # HackerOne JSON, one per finding
aegis report engagements/2026-05-acme --format bugcrowd # Bugcrowd VRT bundle
```
## scope.yaml
如果没有此文件，Aegis 拒绝运行。绝无例外。
```
engagement_id: "BL-2026-007"
client: "Acme Corp"
operator: "Majd Bnat "
authorization:
document_ref: "SOW-2026-007.pdf"
signed_date: "2026-05-12"
expiry: "2026-06-12"
in_scope:
domains:
- "*.acme.com"
- "api-staging.acme.io"
ips:
- "203.0.113.0/24"
out_of_scope:
- "admin.acme.com"
- "*.internal.acme.com"
rules_of_engagement:
rate_limit_rps: 10
business_hours_only: false
destructive_tests: false
no_credential_stuffing: true
no_dos_tests: true
confirm_before: # per-engagement gate for destructive tools
- sqlmap
- hydra
- commix
```
## 架构
```
aegis CLI
|
Engagement Manager
(scope validation, lifecycle, audit log)
|
+-----------------+-----------------+
| | |
Environment Target Methodology
Profiler Profiler Engine
(host info) (fingerprint) (PTES phases)
| | |
+--------+--------+--------+--------+
|
LLM Orchestrator
(Haiku / Sonnet / Opus)
|
+----------+---------+----------+----------+
| | | | |
Tool Knowledge Findings PTT PoC
Registry Base DB Graph Generator
(173 tools) (NVD/GHSA (SQLite) (aiosqlite) (14 types)
+KEV/EPSS)
| |
Tool Executor Hallucination Guard
(async, sandboxed, (output verification)
destructive-gated)
|
Reporter
(md/html/json/sarif/h1/bugcrowd)
```
编排器在每个阶段运行一个有界循环：
```
plan(phase_context) -> execute(action) -> observe(result) -> update(state)
^ |
+---------------------------------------------------------------+
until phase complete OR budget exceeded
```
三个独立的预算限制着每个阶段：token 预算、自然时间（wall-clock time）和操作次数。无论哪个先触发，都会结束该阶段并进入定稿模式。
状态会在每次阶段推进后，通过原子操作 `tmp + os.replace` 持久化到 `/state.json`。对同一目录重新运行 `aegis run` 将从上次保存的阶段恢复。
## 推理引擎
v0.12 将 AEGIS 从“工具调度器”重新定位为“聪明的漏洞狩猎伙伴”。agent 会阅读观察结果，提出结构化的理论，调度探针进行测试，并在推进之前写下自我批评。OOHA 循环是其核心支柱：
| 步骤 | 含义 |
|---|---|
| **OBSERVE** | 阅读新的观察结果、开放假设区块和建议下一步区块。有什么是真正新出现的？ |
| **ORIENT** | 我现在处于攻击链（kill chain）的哪个位置？在可达范围内，影响最大的原语（primitive）是什么？ |
| **HYPOTHESISE** | 在调度工具之前，使用 `propose_hypothesis` 附带一段理由说明。如果匹配到已有的开放假设，则使用新证据调用 `update_hypothesis`。 |
| **ACT** | 以**批次**方式调度 `run_tool` / `aegis_verify` — 独立的调用会并行运行。 |
| **CRITIQUE** | 每个阶段一次，调用 `self_critique` — 我正在做出但尚未测试的假设是什么？哪些开放假设是死胡同？ |
四个推理动词会进入 `PLAN_TOOLS` 并绕过按阶段划分的枚举过滤器（agent 在每个阶段都会进行推理，而不仅仅是 `VULN_ANALYSIS` 阶段）：
| 动词 | 用途 |
|---|---|
| `propose_hypothesis(target, vuln_class, rationale)` | 在调度工具之前提出一个结构化理论。基于 `(target, vuln_class)` 去重，因此重复调用会返回现有行。 |
| `update_hypothesis(id, status, evidence_for, evidence_against)` | 追加证据；状态转换为 `CONFIRMED` 时会自动写入一个 `Finding`（严重性由 `vuln_class` 推断得出），以便立即触发攻击链检测。 |
| `mark_dead_end(id, reason)` | 永久废弃一个理论 — 防止建议器再次将其提出。其理由会作为 `evidence_against` 记录在该行中。 |
| `self_critique(reflection)` | 自由格式推理，作为 `reasoning_trace` 审计事件持久化保存。被认可的“草稿本” — 除了日志外对数据库没有其他副作用。 |
假设的生命周期为 `PROPOSED → TESTING → CONFIRMED | REFUTED | DEAD_END`。开放假设会在每个回合被注入回观察摘要中，以便 agent 在多回合间能看到自己的工作理论。
**并行调度。** 单个回合中的非控制类工具调用现在通过 `asyncio.gather` 并发运行，由每个运行器的 semaphore 限制（默认值为 `executor.max_parallel_tools`，回退到 4）。控制动词 — `advance_phase`、`change_phase`、`abort` — 保持串行，以便编排器可以进行短路处理。单个崩溃的调度永远不会扼杀批次中的其他任务。
**结构化失败信号。** `_recent_calls` 原本是 `dict[(tool, target), int]`，携带“失败 N 次”的信息。现在变成了 `dict[(tool, target), FailureSignal]`，包含 8 种类型的分类器（`TIMEOUT`、`RATE_LIMITED`、`PERMISSION_DENIED`、`AUTH_REQUIRED`、`OUT_OF_SCOPE`、`BINARY_MISSING`、`ZERO_RESULTS`、`EXCEPTION`）以及针对每种类型的带有攻击者视角的转换提示：
- `rate_limited` → 在进程中使用 `aegis_verify`；它不受速率限制
- `auth_required` → 通过 `aegis ingest har --replay` 摄取带有 cookie 的捕获到的 Burp/ZAP HAR 文件
- `binary_missing` → 执行 `aegis env install --missing`，或使用 `aegis_tool_list_help ` 寻找替代品
观察摘要中的 `STUCK SIGNALS` 区块会渲染类型 + 计数 + 转换提示，优先显示最近的记录，最多显示 5 条。
## 攻击链检测
漏洞发现包含结构化标签。攻击链检测器基于标签集进行匹配，而不是标题子字符串。自带 25 个开箱即用的攻击链 — 7 个传统 Web 攻击链，10 个现代 Web/API 攻击链，5 个 Active Directory 攻击链，以及 3 个 v0.12 高 ROI 盲点（Host Header、Web 缓存欺骗、参数污染）：
| 攻击链 | 严重性 | 谓词（标签组） |
|---|---|---|
| 通过 CORS + JWT 实现的账户接管 | critical | `cors_wildcard` + jwt-family |
| 存储型 XSS + CSRF = 会话劫持 | critical | `xss_stored` + `csrf` |
| SQL injection + 弱加密 | critical | `sqli` + `weak_crypto` |
| SSRF + 内部服务暴露 | high | `ssrf` + cloud/internal |
| SSRF + 云元数据 v1 | critical | `ssrf` + `cloud_metadata_v1` |
| Mass assignment + admin endpoint | critical | `mass_assignment` + `admin_endpoint` |
| 开放的存储桶 + 可达的 Lambda | high | `bucket_open` + `lambda_invoke` |
| Request smuggling → 认证头绕过 | critical | `request_smuggling` + `auth_header` |
| 缓存中毒 → 认证绕过 | critical | `cache_poisoning` + `auth_cookie` |
| Prototype pollution → RCE sink | critical | `prototype_pollution` + `dangerous_sink` |
| JWT alg-confusion → 权限提升 | critical | `jwt_alg_confusion` + `privileged_endpoint` |
| 暴露的 `.git` → 源代码泄露 | high | `git_exposure` |
| 开放注册 + IDOR | high | `open_registration` + `idor` |
| 竞态条件 → 认证绕过 | high | `race_condition` + auth |
| Kerberoasting → 服务账户沦陷 | high | `ad_kerberoast` + `ad_spn` + weak/service |
| AS-REP roasting | high | `ad_no_preauth` + weak/user |
| DCSync → 整个域沦陷 | critical | `ad_dcsync` + any AD creds |
| AdminSDHolder ACL 后门 | critical | `ad_adminsdholder` + any AD creds |
| 非约束委派 → 票据伪造 | critical | `ad_unconstrained` + any AD creds |
| Host Header Injection → 缓存中毒 | critical | `host_header_injection` + `cache_poisoning`/`redirect_open` |
| Web 缓存欺骗 → 认证 Token 泄漏 | high | `web_cache_deception` + `auth_cookie`/`auth_header` |
| HTTP 参数污染 → 认证绕过 | high | `http_parameter_pollution` + `auth_bypass`/`idor`/`mass_assignment` |
对于在标签功能推出之前进行的测试任务，子字符串回退机制仍会针对漏洞标题触发传统的 7 条规则。
## 引导式狩猎
攻击链属于事后检测 — 它们会在漏洞发现已存入数据库时触发。Playbook 是与之对应的主动手段：位于 `src/aegis/analysis/vuln_playbooks.py` 中的 28 个条目指明了“当你怀疑 X 时，运行这些探针；当你确认 X 时，接下来狩猎 Y”。
| 字段 | 含义 |
|---|---|
| `vuln_class` | `chains.py` 中的 `TAG_*` 常量之一 |
| `severity_floor` | `critical` / `high` / `medium` / `low` / `info` |
| `preconditions` | 状态谓词（`has_params`、`has_login`、`has_jwt` 等） |
| `probes` | 具体的 `(tool_name, args_template, rationale)` 元组 |
| `confirm_chain` | 该 playbook 最终馈送的 `ChainRule.name`（如果有） |
| `follow_ups` | 当此漏洞触发时，接下来要狩猎的其他漏洞类别 |
初始集合（每个攻击链标签对应一个 playbook）：
`sqli`、`nosqli`、`cmdi`、`ssti`、`xxe`、`xss_stored`、`xss_reflected`、`ssrf`、`lfi`、`cloud_metadata_v1`、`bucket_open`、`request_smuggling`、`cache_poisoning`、`prototype_pollution`、`jwt_alg_confusion`、`jwt_weak_secret`、`csrf`、`idor`、`race_condition`、`mass_assignment`、`git_exposure`、`cors_wildcard`、`ad_kerberoast`、`ad_no_preauth`、`ad_dcsync`、`host_header_injection`、`web_cache_deception`、`http_parameter_pollution`。
在每次阶段推进后，`EngagementRunner._suggested_next` 会根据已确认的漏洞（标签 + endpoint + 技术栈）构建一个升级状态，并运行 `adaptive.escalate`。排名前三的操作将作为 `Suggested next probes` 区块注入到下一次的观察摘要中；模型可以选择执行或忽略它们。无论哪种方式，建议都会记录在 `audit_event` 中（`event_type='escalation_suggested'`），以便 `aegis stats` 能够回答“模型采纳建议的频率有多高？”。
标签推断（`src/aegis/analysis/tag_inference.py`）会在 `FindingsDB.add_finding` 内部的持久化边界处运行。漏洞会从工具基础映射（例如 `impatch_get_userspns` → `[ad_kerberoast, ad_spn]`）中获取标签，并通过针对标题 + 证据文本的 31 条子字符串匹配规则进行标记（区分 `jwt_alg_confusion` 和 `jwt_weak_secret`，区分 `xss_stored` 和 `xss_reflected`，以及区分 payload 中的 IMDSv1 标记为 `cloud_metadata_v1`）。来自调用者的显式标签将被保留。
**横向枢纽（Lateral pivots）(v0.12)。** `src/a/reasoning/lateral.py` 编码了每个聪明的漏洞猎手在确认后都会问的问题：“有了原语 X，它能解锁哪些新类别？” 10 个手工挑选的行覆盖了最高杠杆率的攻击链 — SSRF → IMDS → IAM → S3 → 凭据转换；SQLi → 通过 INTO OUTFILE 读取文件 → 日志投毒 → RCE；.git 泄露 → 源码审查 → JWT 密钥提取 → 伪造任意 token。每确认一个原语，都会为每个解锁的类别自动生成一个假设（`proposed_by="lateral:"`），以便 agent 看到具体的后续探针，并将其直接构建为“鉴于 X，狩猎 Y，因为……”的形式。
**部分攻击链启动器（v0.12）。** 大多数攻击链需要 2-3 个必需的标签组。当一个组匹配但至少缺少一个组时，`chains.partial_matches()` 会返回这种“擦肩而过”的结果；编排器会将它们作为 `PARTIAL CHAINS (one probe away)` 呈现在观察摘要中，包含我们已有的内容和缺失的内容 — agent 可以直接看到距离一步之遥的具体机会，而无需进行 LLM 规划调用。
## Token 模型
Aegis 旨在以低于 2 美元的 LLM token 成本完成一次中等规模的全面测试任务。这是通过几种分层策略来实现的：
| 策略 | 影响 |
|---|---|
| 分层模型路由（Haiku 处理约 70% 的调用） | 成本 -60% |
| 对系统提示词 + 任务上下文进行 prompt caching | 输入 token 减少 40% |
| 解析工具输出，绝不向 LLM 发送原始 stdout | 工具密集型阶段减少 80% |
| 结构化的工具调用 schema，无需冗长文本规划 | 输出 token 减少 30% |
| 方法论驱动的操作空间修剪 | 无效调用减少 50% |
| 跨阶段重用经过 SQLite 缓存的侦察数据 | 视情况而定 |
| 在 LLM 查看结果之前进行漏洞去重 | -10-30% |
模型层级：
| 层级 | 模型 | 用于 |
|---|---|---|
| NANO | claude-haiku-4-5 | 解析、分类、总结 |
| MAIN | claude-sonnet-4-6 | 规划、假设生成、验证探针 |
| DEEP | claude-opus-4-7 | 攻击链分析、深度推理 |
| LOCAL | ollama (可选) | 离线预分类 |
实时成本计量器会在每个阶段的整个过程中在终端运行：
```
Phase: VULN_ANALYSIS [>>>>>>>>--] 80%
Budget: $0.74 / $5.00 Tokens: 41.2k / 200k Time: 12m / 60m
Tier breakdown: NANO 24% . MAIN 71% . DEEP 5% Cache hit: 82%
```
## 工具目录
Aegis 暴露了 **173 个 MCP 工具**，封装了 **105 个外部二进制文件**以及编排原语。原始输出永远不会传递给 LLM — 每个工具都有一个类型化的解析器，可生成结构化的 `Finding` 或 `Observation` 模型。一次返回 47 个开放端口的 nmap 扫描会变成 47 个每个约 80 字节的 `OpenPort` 观察，而不是 200 KB 的 XML。
所有工具都能优雅降级：如果未安装二进制文件，该工具会返回一个结构化错误，并附带确切的安装命令。
| 类别 | 工具 |
|---|---|
| **API 摄取** | `aegis ingest openapi`、`aegis ingest postman`、`aegis ingest har`（写入 Endpoint 观察结果 + paths.txt/params.txt 字典） |
| **子域名枚举** | subfinder, amass, assetfinder, findomain, dnsx, alterx, massdns, shuffledns, puredns, dnstwist, subdomain\_brute\_massive |
| **DNS 侦察** | dnsrecon, dnsx, massdns, fierce, crt.sh (cert transparency) |
| **OSINT / 被动** | uncover (Shodan/Fofa/Censys/ZoomEye), shodan CLI, censys CLI, asnmap, passive\_intel, github\_discover, pwndb\_search, theharvester, spiderfoot, recon\_ng, google\_dorks |
| **存活主机检测** | httpx, httpx\_batch, httprobe, naabu |
| **端口扫描** | nmap, naabu, masscan, rustscan |
| **Web 爬取** | katana, gospider, hakrawler, getjs |
| **URL / 历史记录侦察** | gau, waybackurls, wayback\_recon, meg, unfurl, qsreplace |
| **内容发现** | ffuf, feroxbuster, gobuster, dirsearch, wfuzz, content\_discovery, kiterunner |
| **Vhost 模糊测试** | ffuf\_vhost |
| **技术指纹识别** | whatweb, httpx -tech-detect, cdncheck, tlsx |
| **WAF 检测** | wafw00f, whatwaf |
| **TLS 审计** | sslscan, sslyze, tlsx |
| **参数发现** | arjun, paramspider, gf (pattern filtering) |
| **XSS** | dalfox, kxss, crlfuzz, xsstrike, nuclei, aegis\_verify (xss probe) |
| **SQLi** | sqlmap*, nosqlmap*, nuclei, aegis\_verify (sqli / timing\_sqli probes) |
| **SSTI** | sstimap*, aegis\_verify (ssti probe) |
| **命令注入** | commix*, aegis\_verify (cmdi\_oob probe) |
| **HTTP 走私** | smuggler* (CL/TE, TE/CL), h2csmuggler (HTTP/2 cleartext) |
| **CORS** | corsy |
| **SSRF / OOB** | oob\_init + oob\_poll (interactsh), aegis\_verify (ssrf\_oob / xxe probes) |
| **竞态条件** | race\_condition\_scan, aegis\_verify (race probe) |
| **OAuth** | oauth\_audit (open redirect, state bypass, PKCE) |
| **JWT 攻击** | jwt\_audit (alg:none, RS256→HS256, weak secret) |
| **GraphQL** | graphql\_audit (schema walk, batch DoS, deep nesting, per-query auth probe, rate-limit burst), graphql\_cop |
| **WebSocket** | websocket\_test (injection, origin validation, auth) |
| **API 发现** | api\_discover, kiterunner, openapi\_audit |
| **IDOR** | idor\_check (cross-user object access) |
| **JS 分析** | js\_recon, linkfinder, secretfinder |
| **Header 注入** | header\_injection\_scan (Host header, cache poisoning) |
| **403 绕过** | bypass\_403 (path tricks + header overrides) |
| **Prototype pollution** | aegis\_verify (prototype\_pollution probe) |
| **机密信息 / SAST** | trufflehog, semgrep, bandit, safety, npm\_audit, retire\_js, secret\_scan |
| **漏洞扫描** | nuclei, nuclei\_fuzz, nuclei\_ai\_generate, wapiti, nikto |
| **CMS 扫描** | wpscan*, cmseek, joomscan, droopescan |
| **网络 / SMB** | enum4linux, smbmap, snmpcheck |
| **Active Directory** | impacket (`GetUserSPNs.py`, `GetNPUsers.py`, secretsdump.py), kerbrute*, bloodhound-python, ldapdomaindump, crackmapexec*, certipy |
| **云配置审计** | scoutsuite (AWS/Azure/GCP/Aliyun/OCI), cloudsplaining, pmapper, iamspy, azurehound, roadtools, gcp-iam-collector, gcp-scanner |
| **云存储** | cloud\_enum, s3scanner, bucket\_finder, gitdumper, cloudfox |
| **Kubernetes** | kube\_bench, kube\_hunter, kdigger, kubectl-who-can |
| **容器 / SBOM** | trivy, grype, syft |
| **认证 / 暴力破解** | hydra* |
| **子域名接管** | subjack, subzy, subdomain\_takeover\_scan |
| **侦察编排** | bbot (multi-module OSINT), interlace (parallel execution) |
| **报告** | aegis\_report (md / html / json / sarif / h1 / bugcrowd) |
| **方法论** | wstg\_check (OWASP WSTG v4.2, 80+ checks) |
| **攻击图 (PTT)** | ptt\_add\_node, ptt\_update\_node, ptt\_get\_graph, ptt\_next\_targets, ptt\_spawn\_tasks, ptt\_summary |
| **编排** | aegis\_hotlist (asset risk scoring), aegis\_compress\_context (context compression), aegis\_engagement\_status |
| **PoC 生成** | generate\_poc (14 vuln classes: XSS, SQLi, SSRF, LFI, RCE, IDOR, open redirect, JWT, CORS, CSRF, HTTP smuggling, SSTI, XXE, prototype pollution) |
| **输出验证** | verify\_tool\_output (hallucination guard — validates tool output before Claude acts on it) |
| **现代 JS 攻击面** | nextjs\_data\_probe, astro\_endpoint\_probe, source\_map\_extract, spa\_route\_discover |
| **综合 nuclei 模板** | nuclei\_synth\_from\_probe, nuclei\_synth\_list |
| **移动端 + API 扩展** | mobsf\_static\_scan, dredd\_run, postman\_runner |
| **工具文档** | aegis\_tool\_help, aegis\_tool\_list\_help |
`*` 标记的工具在每次运行前都需要操作员批准（破坏性操作受限）。
## 工具 Playbook
165 个针对特定工具的 markdown playbook 随 wheel 打包在 `aegis/_docs/tools/` 下。agent 会按需获取它们，而不是在每一个回合的 system prompt 中都携带完整的参数说明。
| MCP 工具 | 返回结果 |
|---|---|
| `aegis_tool_help(name)` | 完整的 markdown 正文 — 用途、参数、常用标志、陷阱、何时使用、示例 — 当名称不匹配时，还会提供拼写错误的 `suggestions` |
| `aegis_tool_list_help(category)` | 跨所有文档的一行索引；支持按类别（`network`、`vuln`、`ad`、`cloud`、`k8s` 等）过滤 |
每份文档都遵循固定的 schema，因此模型可以依赖其固定的章节排序：
```
# tool_name
**Purpose:** one-sentence summary.
## Args
- arg (type): meaning
## 值得了解的通用 flags
- -X short note
## 注意事项
- short bullet
## 何时使用
- which phase, what precondition triggers it
## 示例
`tool_name(target="…", flags="…")`
```
11 个高频路径工具有手工挑选的 playbook；其余的则是由 `scripts/gen_tool_docs.py` 根据现有的 docstring + `ToolSpec.install` 提示生成的脚手架。你可以覆盖或手动编辑 `docs/tools//.md` 下的任何内容 — 在可编辑安装期间，磁盘上的源码布局优先于打包副本中的内容。
## 验证探针
43 个进程内探针（`aegis.verify.probes`）无需重新调用外部二进制文件即可确认漏洞发现。每个探针都针对特定的类别，并发出结构化的 `ProbeResult`。探针默认仅支持 HTTP，并针对每个范围进行速率限制。
```
blind_cmdi, blind_cmdi_oob, blind_sqli, cache, cache_poisoning,
cmdi_oob, cors, cors_misconfig, csrf, csrf_missing, exposure,
file_exposure, headers, http_smuggling, jwt, jwt_alg_confusion,
lfi, misconfig, oauth, oauth_redirect, open_redirect, pp,
prototype_pollution, race, race_condition, redirect,
request_smuggling, smuggling, sqli, sqli_error, ssrf, ssrf_oob,
ssti, subdomain_takeover, takeover, template_injection,
timing_cmdi, timing_sqli, toctou, xml_injection, xss,
xss_reflected, xxe
```
探针在 v0.12 中采用了三项可靠性升级：
- `aegis.verify.baseline` — 差异化的请求/响应差异对比（状态、body hash、超过 200 字节阈值的内容长度、重定向 Location）。消除了全盘返回 200 的误报（即服务器对每个 URL 都返回相同 HTML 的情况）。
- `aegis.verify.oob_waiter.confirm_oob` — 轮询 OOB 会话，直到回调与 nonce 匹配（子字符串或正则表达式）或达到截止时间。v0.11 发送 payload 后立即返回；这才是针对 Blind SSRF / CMDi / XXE 真正的确认环节。
- `aegis.verify.mutations` — 当 payload 遇到 403/406/419 时，针对每种探针类型进行 WAF 绕过重试。`sqli`（双重 URL 编码、反引号替换、`/**/` 注入注释）、`xss`（全角 unicode、大小写混合）、`lfi`（null 字节 + `.png`/`.jpg` 后缀），以及 `ssrf`、`ssti`、`cmdi`、`header_injection`。
## 报告与 Webhook
六种输出格式，均由相同的 `Reporter` 上下文驱动：
| 格式 | 用途 |
|---|---|
| `md` / `html` | 供人类阅读 |
| `json` | 结构稳定，供机器的 schema |
| `sarif` | GitHub Code Scanning、GitLab Security、Azure DevOps |
| `h1` | HackerOne 提交 — `reports/h1/` 下每个发现对应一个 JSON 文件 |
| `bugcrowd` | Bugcrowd VRT 映射的 JSON 包 |
通过 `[reporting] redact_pii = true` 可选择性开启 PII 脱敏。会扫描并清除电子邮件、JWT、AWS 密钥、GitHub PAT、Slack token、美国社会安全号码（SSN）、信用卡形式的数字以及电话号码。IP 脱敏是一个单独的开关。审计日志只记录数量 — 绝不记录内容。范围元数据（`engagement_id`、`client`）会被特意保留。
通过 `aegis watch` 实现实时漏洞 Webhook：
```
aegis watch engagements/2026-acme \
--webhook https://hooks.slack.com/services/... \
--webhook-format slack \
--webhook-min-severity high
```
支持的平台：`slack` (Block Kit)、`discord`（按严重性着色的嵌入内容）、`linear`（工单标题/描述/优先级）、`json`（适用于 n8n / Zapier 的稳定 schema）。
## 环境分析
首次运行时，`aegis init` 会对主机进行性能分析，并派生出自动调整的并发设置：
```
Host: arch-workstation
OS Arch Linux (rolling, kernel 6.9.3-arch1-1)
CPU AMD Ryzen 7 5800X . 8 cores / 16 threads . 4.7 GHz
Memory 32 GB total . 24 GB available
Repos core, extra, multilib, blackarch
Pentest toolchain: 28/35 detected
nmap 7.95 nuclei 3.2.9 httpx 1.6.6
ffuf 2.1.0 subfinder 2.6.6 katana 1.1.0
sqlmap 1.8.5 wpscan 3.8.27 nikto 2.5.0
gobuster 3.6.0 amass 4.2.0 gowitness 3.0.3
Missing: testssl.sh feroxbuster dnsrecon arjun paramspider trufflehog
-> Run: aegis env install --missing
Auto-tuned concurrency:
nmap_parallelism=16 nuclei_concurrency=32 ffuf_threads=64
httpx_concurrency=80 max_parallel_tools=4
```
## CLI 参考
```
aegis init First-run setup and env profile
aegis env show Display host profile
aegis env tools Tool inventory
aegis env install --missing Generate install commands for missing tools
aegis env refresh Re-detect host profile
aegis kb sync [--source nvd|ghsa|nuclei|kev|epss] Sync knowledge base
aegis kb stats Knowledge base summary
aegis kb query --product nginx --min-cvss 7 Query CVEs
aegis engagement new --client X --domain Y Scaffold engagement dir and scope.yaml
aegis engagement list List engagements
aegis ingest openapi --engagement Seed endpoints from OpenAPI / Swagger
aegis ingest postman --engagement Seed endpoints from Postman v2.x
aegis ingest har --engagement [--replay] Seed endpoints from a browser HAR; --replay re-issues each request and diffs the response
aegis run [--phase PHASE] Run engagement (resumes from state.json)
aegis run --dry-run Preview planned actions
aegis run --budget-usd 2.00 Cap spend
aegis watch --webhook Live findings webhook
--webhook-format slack|discord|linear|json
--webhook-min-severity critical|high|medium|low|info
aegis report [--format md|html|json|sarif|h1|bugcrowd|all] Generate report
aegis findings list [--severity high] List findings
aegis findings suppress --reason "..."
aegis cost Detailed cost breakdown
aegis audit Full audit log
aegis stats [] [--json] Cross-engagement metrics
aegis shells Tool execution history (last scan)
aegis shells --all [--tool X] [--engagement Y] Cross-engagement shell history (SQLite)
aegis docker build|run|shell|pull|status Docker sub-app
```
所有命令都支持用于脚本化处理的 `--json`，用于控制详细程度的 `-v/-vv/-vvv`，以及用于 CI 的 `--quiet`。
## 配置
全局配置位于 `~/.config/aegis/config.toml`。在 `engagement_dir/config.toml` 中可以按测试任务覆盖任何键值。
```
[api]
anthropic_api_key_env = "ANTHROPIC_API_KEY"
[models]
nano = "claude-haiku-4-5-20251001"
main = "claude-sonnet-4-6"
deep = "claude-opus-4-7"
[models.local]
enabled = false
endpoint = "http://localhost:11434"
model = "qwen2.5:7b"
[budgets]
tokens_per_phase = 30000
tokens_per_engagement = 200000
usd_per_engagement = 5.00
wall_time_per_phase_sec = 1800
[caching]
prompt_cache = true
kb_cache_dir = "~/.cache/aegis/kb"
fingerprint_cache_ttl_hours = 168
[tooling]
docker_isolate = false
default_rate_limit_rps = 10
respect_robots_txt = false
[reporting]
default_format = "html"
include_audit_log = true
redact_pii = false
redact_ips = false
```
## 技术栈
| 层级 | 选择 |
|---|---|
| 语言 | Python 3.12+ |
| CLI | Typer + Rich |
| TUI | React + Ink (TypeScript) |
| 异步 | asyncio + anyio |
| HTTP | httpx (async, HTTP/2) |
| 模型 | Pydantic v2 |
| 存储 | SQLite + SQLModel + Alembic |
| MCP | FastMCP |
| LLM | Anthropic SDK (Claude) |
| 模板 | Jinja2 |
| 日志 | structlog + rich |
| 打包 | uv (开发), hatch (构建) |
| 测试 | pytest + pytest-asyncio + respx (494 个测试) |
## 许可证
MIT。请负责任地使用，且仅限于对你获得授权的系统进行测试。
由 [Majd Bnat](https://majdb.com) 构建
标签：AI代理, CISA项目, MITM代理, Python, Web安全, 实时处理, 密码管理, 无后门, 自动化渗透测试, 蓝队分析, 请求拦截, 逆向工具