F --> G1[Passive scanners]
F --> G2[Active scanners]

I[template-tool] --> H[CVE templates]
H --> G2

G1 --> J[Findings]
G2 --> J
J --> K[Reporter]
K --> L[Auto Reports]
K --> M[CI/CD Controls]

## 为什么选择 ApiHunter？

### 核心优势

- **API 优先架构**：专为 REST/GraphQL API 构建，而非从 Web 应用扫描器改造而来
- **智能误报抑制**：
  - 通过金丝雀探测进行 SPA 兜底路由检测
  - 上下文感知的密钥验证（前端与后端）
  - 响应体内容验证和 Referer 检查
  - 响应指纹识别以跳过重复发现
- **设计上对生产环境安全**：
  - 自适应并发（AIMD），出错时自动退避
  - 按主机限速，可配置延迟
  - 礼貌性控制（重试、超时、WAF 规避）
  - 主动检查的干运行模式
- **隐蔽与规避**：
  - 从精选池（assets/user_agents.txt）运行时轮换 User-Agent
  - 带抖动的随机请求延迟
  - 按主机强制延迟（避免突发模式）
  - 带指数退避的重试逻辑
  - 自定义请求头注入，以与合法流量混杂
  - 基于服务器响应的自适应计时
  - 默认模式下无硬编码扫描器指纹

### 隐蔽技术深度解析

ApiHunter 使用多种隐蔽技术来避免被 WAF（Web 应用防火墙）和机器人防护系统检测：

#### 1. User-Agent 轮换
**作用：** 从文件（`assets/user_agents.txt`）中随机轮换使用 100+ 个真实浏览器 User-Agent 字符串

**原理：** 机器人通常使用相同的 User-Agent（如 `curl/7.68.0`）。通过伪装成 Chrome、Firefox、Safari 等浏览器，你能与合法流量混杂在一起

**简单类比：** 就像穿着不同的伪装，而不是总是穿着同一套制服

#### 2. 随机计时与抖动
**作用：** 在请求之间添加随机延迟（由 `--delay-ms` 控制），并带有抖动（小幅随机变化）

**原理：** 机器人以完美间隔发送请求（恰好相隔 100ms）。人类行为不可预测。随机计时使流量看起来更自然

**简单类比：** 用不规则步伐行走，而不是像机器人一样齐步前进

#### 3. 按主机强制延迟
**作用：** 分别跟踪每个域的延迟，而不是全局统一

**原理：** 防止你瞬间对同一主机发起 50 次请求的突发模式。每个主机看到的是礼貌、间隔均匀的请求

**简单类比：** 在不同对话中轮流发言，而不是反复对一个人大喊

#### 4. 自适应并发（AIMD）
**作用：** 在遇到 429（限流）或 503（服务器繁忙）错误时自动减速，成功时加速

**原理：** 被发现时退避，模拟浏览器的重试方式。WAF 会认为“此客户端尊重我们的限制”

**简单类比：** 交通拥堵时减速，开阔道路上加速

#### 5. 指数退避重试
**作用：** 当请求失败时，重试前依次等待 1 秒、2 秒、4 秒

**原理：** 合法客户端会优雅地重试。机器人通常立即重试或放弃

**简单类比：** 敲门时每次等待更久，而不是持续猛敲

#### 6. 无扫描器指纹
**作用：** 不发送如 `X-Scanner: ApiHunter` 之类的请求头，也不使用可预测的模式

**原理：** 许多工具会留下签名（Nuclei 模板、sqlmap 模式）。ApiHunter 避免明显的标记

**简单类比：** 不佩戴写着“安全测试员”的名牌

#### 7. 连接复用与池化
**作用：** 使用按主机的 HTTP 客户端连接池，保持连接存活

**原理：** 浏览器会复用连接。每个请求都打开/关闭连接看起来很可疑

**简单类比：** 保持门开着，而不是猛地关上门再按门铃

#### 8. 自定义请求头注入
**作用：** 可以添加 `Referer`、`X-Forwarded-For`、自定义 Cookie 等请求头

**原理：** 使请求看起来像是来自合法的应用程序流程（点击了链接、具备会话 Cookie）

**简单类比：** 进入场馆时出示票根，而不是翻越围栏

#### 检测对比

| 技术 | 无规避 | 有规避 |
|-----------|----------------|-------------|
| **User-Agent** | `python-requests/2.28.0`（明显的机器人） | `Mozilla/5.0 (Windows NT 10.0; Win64; x64)...`（看起来像 Chrome） |
| **计时** | 完美 100ms 间隔 → WAF 拦截 | 120ms、95ms、180ms → 看起来像人类 |
| **重试** | 立即重试 → 封禁 | 等待 1s→2s→4s → “耐心客户端” |
| **并发** | 100 个并行请求 → 触发警报 | 基于响应自适应 5→10→3 → “礼貌浏览器” |

#### 何时使用 `--waf-evasion`

- 测试带有 Cloudflare/Akamai/AWS WAF 的生产 API
- 在大型扫描中避免 IP 封禁
- 需要隐匿行踪的渗透测试

- **原生 CI/CD**：
  - 基线差异对比（仅报告新发现）
  - 流式 NDJSON 输出，用于实时监控
  - SARIF 2.1.0，用于 GitHub/GitLab 代码扫描
  - 退出码位掩码，用于管道控制
  - 基于严重级别的过滤和失败阈值
- **大规模性能**：
  - 基于 Rust 异步运行时（tokio），零成本抽象
  - 通过信号量限制并行度的并发扫描
  - 按主机的 HTTP 客户端连接池，避免连接瓶颈
  - 高效内存使用（无 GC 暂停）
- **全面的认证支持**：
  - 基于 JSON 的认证流程，支持 Cookie/请求头提取
  - 双身份 IDOR/BOLA 测试
  - 会话文件导入（Excalibur 集成）
  - Bearer、Basic 和自定义请求头认证
  - 自动使用未认证客户端进行权限提升检查

## 扫描器模块

ApiHunter 包含 13 个内置扫描器模块。有关详细的检测逻辑，请参阅 [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md)。

| 扫描器 | 类型 | 检测内容 |
|---------|------|----------------|
| **CORS** | 被动 | 通配符来源、带凭据的反射来源、接受 null 来源、正则绕过漏洞（后缀/前缀攻击）、缺少 Vary: Origin、不安全的预检方法 |
| **CSP** | 被动 | 缺少 Content-Security-Policy、unsafe-inline/unsafe-eval 指令、通配符来源、可绕过的 CDN 主机（JSONP 小工具）、缺少 frame-ancestors |
| **GraphQL** | 被动 | 启用了 Introspection、敏感 Schema 字段（user/password/token 类型）、字段建议（Schema 泄露）、查询批处理、别名放大（DoS）、GraphiQL/Playground 暴露 |
| **JWT** | 被动 | alg=none 令牌、弱 HS256 密钥（基于字典）、缺少/过期时间过长、payload 中的敏感声明、算法混淆漏洞 |
| **OpenAPI** | 被动 | 缺少安全方案、无认证要求的操作、文件上传端点、仍存在的弃用操作、未受保护的安全敏感端点 |
| **API 版本管理** | 被动 | 版本头泄露、旧/新 API 版本并存、弃用头，以及良性查询/版本变体之间的响应漂移（另外可通过 `--response-diff-deep` 启用深度模式） |
| **gRPC/Protobuf** | 被动 + 主动 | gRPC 传输/content-type 信号、protobuf 表面提示，以及可选的 reflection/health 探测信号 |
| **API 安全** | 被动 + 主动 | 缺少安全响应头（X-Content-Type-Options、X-Frame-Options）、服务器版本泄露、未认证访问敏感路径、HTTP 方法枚举、调试端点、密钥暴露模式、主动 IDOR/BOLA 检查（响应体 + 选定响应头对比）、盲 SSRF 回调探测，以及网关/绕过探测信号 |
| **Mass Assignment** | 主动 | 反射的敏感字段（is_admin、role、permissions）、持久化状态更改、通过字段注入进行权限提升 |
| **OAuth/OIDC** | 主动 | 重定向 URI 校验绕过、缺少 state 参数、PKCE 支持问题（缺少 S256、允许明文）、启用了隐式流程、启用了密码授权 |
| **Rate Limit** | 主动 | 缺少限流（突发探测）、缺少 Retry-After 响应头、IP 头欺骗绕过（X-Forwarded-For） |
| **WebSocket** | 主动 | 常见路径上接受 WebSocket 升级、缺少来源校验、未认证的 WebSocket 连接 |
| **CVE 模板** | 主动 | 基于模板的 CVE 检测，来源 `assets/cve_templates/*.toml`（目前 168 个模板），基线与绕过的差异对比 |

**被动扫描器** 默认运行，在不发送构造请求的情况下分析响应。  
**主动扫描器/检查** 需要 `--active-checks`，并会发送可能具有侵入性的探测（IDOR/BOLA、变更、绕过测试）。  
IDOR/BOLA 位于 `API Security` 扫描器下（没有专门的 `--no-idor` 标志；使用 `--no-api-security` 可禁用它）。

### 模块输出与信号说明

以下说明总结了发现的输出方式以及通常造成噪音的原因：

| 模块 | 发现前缀 / 形态 | 常见误报 | 常见漏报 |
|---------|-------------------------|-------------------------|-------------------------|
| CORS | `cors/*`，包含 origin/evidence 字段 | 非敏感路由上的反射 | 仅在经过认证的路由上应用来源检查 |
| CSP | `csp/*`，包含指令证据 | 迁移期间有意应用的旧版 CSP | CSP 仅在生产 CDN 边缘路径上提供 |
| GraphQL | `graphql/*`，包含端点 + 能力信号 | 面向内部/测试租户的公开 playground | Schema 控制仅在认证后启用 |
| JWT | `jwt/*`，包含令牌声明/请求头证据 | 合成响应中的测试/演示令牌 | 令牌从未出现在被扫描的响应中 |
| OpenAPI | `openapi/*`，包含操作/安全上下文 | 规范有意包含已弃用但被阻止的端点 | 规范不可用或分散在私有文档中 |
| API 版本管理 | `api_versioning/*` + `response_diff/*` | 受控迁移期间支持多个版本 | 从当前种子集中无法发现版本化路径 |
| gRPC/Protobuf | `grpc_protobuf/*`，包含传输/反射证据 | 边缘代理上类似 gRPC 的元数据但未暴露 RPC 表面 | 位于独立主机/路径后的 gRPC 端点无法从种子集达到 |
| API 安全 | `api_security/*`，包含请求头/路径/方法证据 | 非生产环境中故意暴露的调试/测试端点 | 在认证/会话上下文之后实施的控制 |
| Mass Assignment | `mass_assignment/*`，包含反射/持久化差异 | 不回写后端状态的回应行为 | 变更被隐藏的验证规则拒绝 |
| OAuth/OIDC | `oauth/*`，包含重定向/元数据证据 | 策略宽松的非生产 IdP 配置 | 动态策略实施在元数据中不可见 |
| Rate Limit | `rate_limit/*`，包含突发/429 行为 | 全局流量整形掩盖了应用级限流器行为 | 长时间窗口的限流器未被短探测窗口触发 |
| WebSocket | `websocket/*`，包含升级/来源检查 | 有意保持匿名的公开 WS 端点 | 需要通过握手头进行认证但探测中未提供 |
| CVE 模板 | `cve/<id>/<check>`，包含模板证据 | 通用端点上的指纹冲突 | 易受攻击的路径/上下文无法从种子 URL 达到 |

有关逐项检查的详细信息和修复指导，请参阅 [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md) 和 [docs/findings.md](https://github.com/teycir/apihunter/blob/main/docs/findings.md)。
扫描器文档现在包含与源代码对齐的 [模块检查目录](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#module-check-catalog) 和 [误报预期模型](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#false-positive-expectation-model)。

## 功能特性

### 被动安全分析
- **CORS 错误配置检测**：
  - 基于目标域名的动态来源生成
  - 正则绕过测试（后缀/前缀攻击）
  - 凭据感知的严重性评分
  - 通配符和 null 来源检测
- **CSP 策略分析**：
  - 缺失/弱 Content Security Policy 检测
  - 不安全的 inline/eval 指令
  - 通配符来源检测
  - 策略绕过模式
- **GraphQL 安全**：
  - Introspection 查询检测
  - 敏感类型/字段名称分析
  - 查询批处理支持检测
  - 别名放大（DoS）探测
  - 主动变更模糊测试（`--active-checks`，支持 `--dry-run`）
  - GraphiQL/Playground 暴露
- **JWT 令牌分析**：
  - 算法混淆（alg=none，HS256→RS256）
  - 弱密钥检测（精选字典）
  - 长寿命令牌检测（缺少/过期时间过长）
  - 敏感声明暴露
  - 从请求头和 Cookie 中提取令牌
- **OpenAPI/Swagger 分析**：
  - 安全方案验证
  - 文件上传端点检测
  - 弃用操作标记
  - 缺少安全定义
  - 规范缓存以提升性能
- **gRPC/Protobuf 覆盖**：
  - gRPC 响应元数据/content-type 检测
  - 从端点元数据/路径形状检测 protobuf 表面提示
  - 已知 gRPC 路径上的可选 reflection/health 主动探测信号
- **密钥暴露检测**：
  - AWS 密钥（AKIA*、secret keys）
  - Google API 密钥（AIza*）
  - GitHub 令牌（ghp_*、github_pat_*）
  - Slack 令牌（xox*）
  - Stripe 密钥（sk_live_*、pk_live_*）
  - 数据库 URL、私钥、Bearer 令牌
  - 上下文感知验证（减少误报）
- **API 安全检查**：
  - HTTP 方法枚举
  - 调试端点检测
  - 目录列表暴露
  - Security.txt 是否存在
  - 响应头分析（HSTS、X-Frame-Options 等）
  - 错误信息泄露

### 主动安全测试（--active-checks）
- **API 安全 IDOR/BOLA 检查**（三层方法）：
  - 未认证访问测试
  - 通过响应体指纹加上稳定请求头快照进行响应对比
  - ID 枚举（±2 范围遍历）
  - 跨用户授权绕过（双身份）
  - 通过回调式查询参数进行盲 SSRF 回调探测（`APIHUNTER_OAST_BASE`，支持 `--dry-run`）
  - 网关指纹与绕过探测（`api_security/gateway-*`）
- **Mass Assignment 漏洞**：
  - 反射的敏感字段注入
  - 持久化状态更改检测
  - 基线→变更→确认 验证
  - 通过字段注入进行权限提升
- **OAuth/OIDC 安全**：
  - 重定向 URI 校验绕过
  - State 参数处理
  - PKCE 支持检测
  - 元数据配置加固
  - 隐式流程和密码授权检测
- **限流**：
  - 突发请求探测
  - 缺少限流检测
  - Retry-After 响应头验证
  - IP 头欺骗绕过测试
- **WebSocket 安全**：
  - 常见路径上的升级接受
  - 来源验证测试
  - 缺少认证检查
- **CVE 模板引擎**：
  - 基于 TOML 的模板目录
  - 支持 Nuclei YAML 导入
  - 基线与绕过的差异比对
  - 主机+模板去重
  - 加载器质量门控跳过无效/不安全的请求模板（例如未解析的请求占位符）
  - 分段感知的上下文匹配减少宽泛路径子串的过度触发
  - 当前本地目录：168 个模板（包括精选的加固检查，如 CVE-2022-22947、CVE-2021-29442、CVE-2021-29441、CVE-2020-13945、CVE-2021-45232、CVE-2022-24288）

### 发现与枚举
- **端点发现**：
  - robots.txt 解析
  - sitemap.xml 解析
  - OpenAPI/Swagger 规范导入
  - HAR 文件导入（Excalibur 集成）
  - Postman/Insomnia 集合导入（`--collection`）
  - JavaScript 端点提取
  - 同主机过滤
- **URL 可达性预过滤**：
  - 快速预检查以跳过无效端点
  - 可配置超时
  - 可通过 --no-filter 选择绕过

### 性能与可靠性
- **自适应并发（AIMD）**：
  - 根据错误自动调整速率
  - 加性增加（每 5 秒）
  - 遇到 429/503/超时时乘法减少
- **隐蔽与 WAF 规避**：
  - 从运行时池中轮换 User-Agent（assets/user_agents.txt，包含 100+ 个真实 UA）
  - 文件不可用时使用内置备用 UA
  - 随机延迟抖动以避免检测模式
  - 按主机执行计时（非全局）
  - 带指数退避的重试逻辑
  - 自定义请求头注入（X-Forwarded-For、Referer 等）
  - 基于 429/503 响应的自适应计时
  - 礼貌模式，用于协作测试
  - 默认情况下 User-Agent 或请求头中没有扫描器指纹
- **资源管理**：
  - 信号量限制的并行度
  - 按主机 HTTP 客户端连接池
  - 连接复用与池化
  - 可配置超时和重试
- **错误处理**：
  - 通过 JoinSet 进行 panic 恢复
  - 捕获的错误单独报告
  - 扫描器失败时优雅降级

### 输出与报告
- **多种输出格式**：
  - Pretty JSON（人类可读）
  - NDJSON（流式、可解析）
  - SARIF 2.1.0（GitHub/GitLab 代码扫描）
- **基线差异对比**：
  - 生成基线快照
  - 对比扫描结果，仅报告新发现
  - 非常适合回归测试
- **自动保存报告**（默认启用，使用 `--no-auto-report` 禁用）：
  - 保存至 ~/Documents/ApiHunterReports/<timestamp>/
  - findings.json（结构化发现）
  - summary.md（Markdown 报告）
  - scan.log（执行日志）
- **实时流式输出**：
  - 发现即流式输出
  - NDJSON 格式，便于实时解析
  - 进度跟踪
- **严重性过滤**：
  - 按最低严重性过滤（info/low/medium/high/critical）
  - CI/CD 失败阈值
  - 退出码位掩码（0x01 发现，0x02 错误）

### 集成与可扩展性
- **可插拔扫描器架构**：
  - 实现 Scanner trait 以添加模块
  - 异步优先设计
  - 扫描器独立执行
  - 每个扫描器 panic 隔离
- **基于 TOML 的可扩展性**：
  - CVE 模板目录位于 assets/cve_templates/*.toml
  - 添加新检查无需修改代码
  - 模板驱动的漏洞检测
  - 可社区共享的模板格式
- **Nuclei 模板导入**：
  - template-tool 二进制，用于 YAML → TOML 转换
  - 自动匹配器转换（status、word、regex、dsl）
  - 安全的预检请求链提取
  - 保留上游模板的检测逻辑
- **双扩展模型**：
  - **基于代码**：编写实现 Scanner trait 的 Rust 扫描器，用于复杂逻辑
  - **基于模板**：编写 TOML 模板，用于基于签名的检查（CVE、错误配置）
  - 两全其美：性能 + 灵活性
- **互补工具**：
  - Excalibur 浏览器扩展（HAR 捕获）
  - BurpAPIsecuritysuite（手动测试）
  - 工作流：捕获 → 自动化 → 深度测试

### 配置与控制
- **灵活输入**：
  - 基于文件的 URL 列表
  - stdin（从其他工具管道输入）
  - HAR 文件导入
  - Postman/Insomnia 集合导入
  - OpenAPI 规范导入
- **细粒度扫描器控制**：
  - 启用/禁用单个扫描器
  - 主动与被动模式
  - 主动检查的干运行
  - 每扫描器配置
- **网络配置**：
  - HTTP/HTTPS 代理支持
  - TLS 证书验证控制
  - 自定义请求头和 Cookie
  - 可配置超时和重试
- **扫描配置文件**：
  - quickscan.sh（快速、低影响）
  - deepscan.sh（全面、主动检查）
  - inaccessiblescan.sh（以较慢的设置重新检查之前无法访问的目标）
  - baselinescan.sh（生成基线）
  - diffscan.sh（与基线对比）
  - authscan.sh（认证扫描）
  - sarifscan.sh（CI/CD 集成）
  - scan-and-report.sh（运行扫描 + 打印最新报告路径）
  - split-by-host.sh（按主机拆分目标，并可选择扇出扫描）

## 与其他工具的比较| 功能 | ApiHunter | Nuclei | ZAP | Burp Suite | ffuf |
|---------|-----------|--------|-----|------------|------|
| **语言** | Rust | Go | Java | Java | Go |
| **性能** | ⚡⚡⚡ 异步、自适应并发 | ⚡⚡ 快速并行 | ⚡ 中等 | ⚡ 中等 | ⚡⚡⚡ 非常快 |
| **API 优先设计** | ✅ 专为 API 构建 | ❌ 通用 Web | ⚠️ 混合 | ⚠️ 混合 | ❌ 聚焦模糊测试 |
| **误报过滤** | ✅ SPA 检测、响应体校验、referer 检查 | ⚠️ 依赖模板 | ⚠️ 误报较多 | ✅ 良好 | N/A |
| **CORS/CSP 分析** | ✅ 深度策略解析 | ⚠️ 基础模板 | ✅ 良好 | ✅ 良好 | ❌ |
| **GraphQL 内省** | ✅ Schema 暴露 + 敏感字段检查 | ⚠️ 基础检测 | ⚠️ 有限 | ✅ 通过扩展 | ❌ |
| **OpenAPI/Swagger** | ✅ 安全方案分析 | ❌ | ✅ 仅导入 | ✅ 导入 + 扫描 | ❌ |
| **JWT 分析** | ✅ alg=none、弱密钥、过期检查 | ⚠️ 通过模板 | ⚠️ 有限 | ✅ 通过扩展 | ❌ |
| **IDOR/BOLA 检测** | ✅ 三级（未授权/范围/跨用户） | ⚠️ 手动模板 | ⚠️ 有限 | ✅ 手动测试 | ❌ |
| **敏感信息检测** | ✅ 上下文感知（前端 vs 后端） | ⚠️ 基于正则 | ⚠️ 基础 | ⚠️ 基础 | ❌ |
| **主动检查** | ✅ 可选启用（IDOR、批量赋值、OAuth/OIDC、WebSocket、速率限制、CVE 模板） | ✅ 基于模板 | ✅ 主动扫描 | ✅ 主动扫描 | ✅ 模糊测试 |
| **WAF 绕过** | ✅ UA 轮换、延迟、重试、自适应时序 | ⚠️ 基础 | ⚠️ 有限 | ✅ 良好 | ⚠️ 基础 |
| **CI/CD 集成** | ✅ NDJSON、SARIF、退出码 | ✅ JSON、SARIF | ⚠️ XML 报告 | ⚠️ XML/JSON | ✅ JSON |
| **基线差异对比** | ✅ 内置 | ❌ 外部工具 | ❌ | ❌ | ❌ |
| **认证流程** | ✅ 基于 JSON 的预扫描登录 | ⚠️ 请求头注入 | ✅ 会话管理 | ✅ 会话管理 | ⚠️ 请求头注入 |
| **流式输出** | ✅ 实时 NDJSON | ❌ 仅批量 | ❌ | ❌ | ✅ |
| **资源占用** | 🟢 低（Rust） | 🟢 低（Go） | 🟡 高（Java） | 🟡 高（Java） | 🟢 低（Go） |
| **学习曲线** | 🟢 简单 CLI | 🟢 模板语法 | 🟡 GUI 复杂 | 🔴 陡峭 | 🟢 简单 |
| **扩展性** | ✅ Rust trait 系统 | ✅ YAML 模板 | ✅ 插件 | ✅ 扩展 | ⚠️ 有限 |
| **许可证** | MIT（免费） | MIT（免费） | Apache 2.0（免费） | 商业 | MIT（免费） |
| **适用场景** | CI/CD 中的 API 安全、回归测试、CORS/GraphQL/JWT 分析 | 通用漏洞扫描、CVE 检测 | 完整 Web 应用渗透测试 | 手动渗透测试、复杂工作流 | 目录/参数模糊测试 |

### 关键区别

**ApiHunter:** API 优先设计、SPA 检测、基线差异对比、三级 IDOR/BOLA、上下文感知敏感信息、AIMD 并发、**隐身/WAF 绕过（UA 轮换、抖动、自适应时序）**、**双重扩展性（TOML 模板 + Rust 模块）**  
**Nuclei:** 更广的 CVE 覆盖、仅 YAML 模板、基础绕过  
**ZAP/Burp:** 手动测试、代理工作流、基于 GUI 的扩展、隐身能力有限  
**ffuf:** 纯粹模糊测试、内容发现、扩展性有限、基础绕过

## 快速开始```bash
cargo build --release

# Scan URLs from a file (newline-delimited)
./target/release/apihunter --urls ./targets/cve-regression-real-public.txt --format ndjson --output ./results.ndjson

# Or scan URLs from stdin
cat ./targets/cve-regression-real-public.txt | ./target/release/apihunter --stdin --min-severity medium

桌面扫描输入支持：
- 手动多目标输入（每行一个 URL 或以逗号分隔）
- 通过 `Load CSV` 导入 CSV（最大 307,200 字节 / 300 KiB）
- 引导式扫描预设：`Quick Passive` 与 `Deep Active`
- 硬性限制：每次运行最多 3,000 个目标（去重后验证为绝对 `http/https` URL）
- 范围控制：发现功能开关、可达性过滤与超时、每个站点的最大端点数
- API 版本控制：可选的深度响应差异探测开关
- 高级控制：代理、请求头、Cookie、Bearer/Basic 认证、TLS 无效证书开关
- 用于主动检测的盲 SSRF 回调关联输入（`OAST callback base`）
- 性能控制：每主机客户端数、自适应并发、带自定义 User-Agent 池的 WAF 绕过
- 完整的扫描器开关覆盖，包括 `API Versioning` 与 `gRPC/Protobuf`
- 可折叠扫描分区，右侧对齐的插入符；`Safety and Scan Behavior`、`Runtime Limits` 与 `Scanner toggles` 默认折叠
- 并行运行进度卡片，含每个目标的完成度/发现结果快照
- 结果分析仪表板：严重程度热力图、最差目标卡片、扫描效率、扫描器覆盖、最易受攻击路径、检查严重程度细分
- 会话持久化：下次启动时自动恢复上次扫描结果
- Enrich Mode 面板：加载 findings NDJSON、运行威胁情报富化、直接将高分主机提升到带 Deep Active 预设的 Full Scan
- 导出体验：大小标签 + `Save All Reports` + 每次运行带时间戳的文件名；导出内容包括每个目标的 JSON 包、NDJSON、SARIF、Insomnia 集合与 Insomnia Runner 数据

详见 [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md) 了解详细用法，[docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md) 了解基于 Vulhub 的 CVE 验证实验环境，以及 [docs/](https://github.com/teycir/apihunter/blob/main/docs) 了解内部实现。

如果你想要发布版桌面二进制：```bash
cd apps/desktop
npm run tauri build
./src-tauri/target/release/apihunter-desktop

注意：桌面开发环境的启动现在直接使用构建好的前端资源，不再需要单独的 `localhost:1420` 服务器。

详细用法请参阅 [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md)，基于 Vulhub 的 CVE 验证实验环境请参阅 [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md)，内部细节请参阅 [docs/](https://github.com/teycir/apihunter/blob/main/docs)。

### NDJSON 发现示例```json
{
  "url": "https://api.example.com/graphql",
  "check": "graphql/introspection-enabled",
  "title": "GraphQL introspection is enabled",
  "severity": "MEDIUM",
  "detail": "Introspection query returned schema metadata from a public endpoint.",
  "evidence": "POST /graphql -> HTTP 200 with __schema fields in response body",
  "scanner": "graphql",
  "timestamp": "2026-03-19T14:02:11.824Z"
}

**流程：** CLI 参数 → Config → Runner 编排 Discovery + Scanners → HTTP Client（含 Auth/WAF）→ Reports

## 模板工具

ApiHunter 支持**双重扩展**：可通过 **TOML 模板**添加检查（无需代码），或通过 **Rust 模块**添加检查（完全控制）。

### TOML 模板格式
在 `assets/cve_templates/*.toml` 中创建自定义检查：```toml
id = "custom-api-check"
name = "Custom API Vulnerability"
severity = "high"

[[requests]]
method = "GET"
path = "/api/vulnerable"

[[requests.matchers]]
type = "status"
values = [200]

[[requests.matchers]]
type = "word"
part = "body"
words = ["sensitive_data", "exposed"]

### 添加自定义 Rust 扫描器
为复杂逻辑实现 `Scanner` trait：```rust
#[async_trait]
impl Scanner for MyCustomScanner {
    async fn scan(
        &self,
        url: &str,
        client: &HttpClient,
        config: &Config,
    ) -> (Vec<Finding>, Vec<CapturedError>) {
        // Your custom scanning logic
    }
}

所有包装脚本（`split-by-host.sh` 除外）均支持 `--stdin` 及尾部 ApiHunter 标志。

## 测试策略

ApiHunter 的测试按意图分为以下几类：

- **单元测试**（`tests/*_scanner.rs`、解析器/配置测试）：涵盖扫描器逻辑与边界情况。
- **集成测试**（`tests/integration_runner.rs`、启动/命令行行为）：涵盖编排与运行时接线。
- **固件回归测试**（`tests/cve_templates_real_data.rs`、`tests/cve_templates_upstream_parity.rs`）：重放真实载荷并与固定的上游模板进行比对。
- **模拟服务器测试**（多个扫描器套件）：在不依赖互联网目标的前提下进行确定性行为验证。
- **实时目标检查**：仅可选/手动执行（不属于默认的 `cargo test` 部分）。

完整的测试矩阵与覆盖率映射请参阅专门的 [测试指南](https://github.com/teycir/apihunter/blob/main/docs/testing.md)。

运行聚焦的测试套件：```bash
cargo test --test cors_scanner
cargo test --test graphql_scanner
cargo test --test cve_templates_runtime_ext
cargo test --test integration_runner

运行真实数据集成门禁（fixtures + 实时忽略的套件）：```bash
# Fixture-backed real payload regression suites
cargo test --test cve_templates_real_data --test cve_templates_upstream_parity --test cve_templates_runtime_ext

# Manual live internet integration suites (ignored by default)
cargo test --test live_vulnerable_apis --test live_real_world_targets -- --ignored

### 预构建的发布工件

带标签的发布（`v*`）会发布适用于以下平台的预构建 `apihunter` 二进制文件：

- Linux（`x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu`）
- macOS（`x86_64-apple-darwin`）
- Windows（`x86_64-pc-windows-msvc`）

每次发布版本还会发布供应链工件：

- SHA256 校验和文件（`*.sha256`）
- Sigstore 无密钥签名材料（`*.sig`、`*.pem`、`*.sigstore.json`）
- SPDX JSON SBOM（`apihunter-release-assets-sbom.spdx.json`）
- GitHub 工件证明（来源和 SBOM 证明元数据）

从 [GitHub Releases](https://github.com/Teycir/ApiHunter/releases) 下载。

### 桌面安装（Tauri + React）

桌面应用源代码位于 `apps/desktop`。

构建并运行生产桌面二进制文件：```bash
cd apps/desktop
npm install
npm run tauri build
./src-tauri/target/release/apihunter-desktop

安装一个可点击的 Linux 启动器图标：```bash
cd apps/desktop
npm run desktop:install-icon

从当前目录中的文件运行扫描：```bash
docker run --rm -v "$PWD:/work" apihunter:local \
  --urls /work/targets/cve-regression-real-public.txt \
  --format ndjson \
  --output /work/results.ndjson

**问：基线差异比较？**```bash
./target/release/apihunter --urls targets/cve-regression-real-public.txt --format ndjson --output baseline.ndjson
./target/release/apihunter --urls targets/cve-regression-real-public.txt --baseline baseline.ndjson --format ndjson