vinceAmstoutz/symfony-security-auditor
GitHub: vinceAmstoutz/symfony-security-auditor
一款基于 AI 多智能体对抗循环的 Symfony 应用安全审计工具，专注于发现传统 SAST 工具遗漏的访问控制缺陷、业务逻辑漏洞和跨文件攻击链。
Stars: 29 | Forks: 1
# symfony-security-auditor
[](https://github.com/vinceamstoutz/symfony-security-auditor/actions/workflows/ci.yaml)
[](https://packagist.org/packages/vinceamstoutz/symfony-security-auditor)
[](docs/versioning.md)
## 目录
- [功能简介](#what-it-does)
- [快速入门](#getting-started)
- [特性](#features)
- [为什么选择这款审计工具？](#why-this-auditor)
- [示例输出](#example-output)
- [支持的平台](#supported-platforms)
- [文档](#documentation)
- [常见问题](#faq)
- [贡献指南](#contributing)
- [安全](#security)
- [许可证](#license)
## 功能简介
通过一个三阶段的 AI pipeline 对你的 Symfony 项目进行扫描，以捕捉 SAST 工具遗漏的问题：失效的访问控制、复杂的注入链、业务逻辑漏洞、缺失的 Voters 以及批量赋值漏洞。一个对抗性的 **Attacker** agent 负责搜寻问题；而一个多疑的 **Reviewer** agent 会在最多三次迭代中消除误报。最终的验证漏洞报告可以输出到你的控制台，或者保存为 JSON，或作为 SARIF 格式用于 GitHub Code Scanning / GitLab Security Dashboard。
```
Project files
│
▼
1. Ingestion — scans .php / .twig / .yaml / .xml recursively
│
▼
2. Mapping — classifies Controllers, Entities, Voters, Forms, Routes
│
▼
3. Audit — Attacker ⚔ Reviewer multi-agent loop (up to 3 iterations)
│
▼
Validated vulnerability report: console, JSON, or SARIF
```
## 快速入门
### 1. 安装 — Symfony Flex 会自动配置一切
```
composer require --dev vinceamstoutz/symfony-security-auditor
```
官方的
[Flex recipe](https://github.com/symfony/recipes-contrib/tree/main/vinceamstoutz/symfony-security-auditor)
（发布在
[`symfony/recipes-contrib`](https://github.com/symfony/recipes-contrib)）
会自动：
- 在 `config/bundles.php` 中为 `dev` 和 `test` 环境注册 `SymfonySecurityAuditorBundle`；
- 创建一个预配置的 `config/packages/symfony_security_auditor.yaml`，其中包含默认模型以及已注释的拆分模型和速率限制示例，随时可以取消注释。
没有使用 Flex？请查看 [手动设置](#manual-setup-without-flex)。
### 2. 安装平台 bridge（以 Anthropic 为例）
```
composer require symfony/ai-anthropic-platform
```
受支持的提供商完整列表请见：
[配置 → 支持的平台](docs/configuration.md#supported-platforms)。
### 3. 配置平台 (`config/packages/ai.yaml`)
```
ai:
platform:
anthropic:
api_key: '%env(ANTHROPIC_API_KEY)%'
```
### 4. 调整审计工具配置 (`config/packages/symfony_security_auditor.yaml`)
Flex recipe 已经创建了这个文件 —— 只需选择你的模型：
```
symfony_security_auditor:
model: 'claude-opus-4-8'
```
也可以选择一键预设模式 —— `fast`（快速）、`balanced`（均衡，默认）或 `thorough`（彻底）；任何显式配置的键始终具有最高优先级：
```
symfony_security_auditor:
profile: 'fast'
```
### 5. 运行
```
# audit 当前目录
bin/console audit:run
# 或指向另一个 project
bin/console audit:run /path/to/your/symfony/project
```
想要输出为 JSON 或 SARIF？只需添加 `--format json --output report.json` 或 `--format sarif --output report.sarif`。请参阅 [CLI 参考](docs/configuration.md#cli-reference)。
在运行前预估成本：
```
bin/console audit:run --dry-run
```
### 手动设置（不使用 Flex）
如果不使用 Symfony Flex（或在使用 `composer require --no-scripts` 时），你需要手动完成 recipe 自动化的工作：
1. 在 `config/bundles.php` 中注册 bundle：
return [
// ...
Symfony\AI\AiBundle\AiBundle::class => ['all' => true],
VinceAmstoutz\SymfonySecurityAuditor\SymfonySecurityAuditorBundle::class => ['dev' => true, 'test' => true],
];
2. 自行创建 `config/packages/symfony_security_auditor.yaml`（参见上文第 4 步），或者复制
[recipe 的模板](https://github.com/symfony/recipes-contrib/blob/main/vinceamstoutz/symfony-security-auditor/1.0/config/packages/symfony_security_auditor.yaml)。
## 特性
- **Symfony Flex recipe** — 一条 `composer require` 命令即可注册 bundle 并附带一个预配置好的 `symfony_security_auditor.yaml`
（[官方 recipe](https://github.com/symfony/recipes-contrib/tree/main/vinceamstoutz/symfony-security-auditor)
位于 `symfony/recipes-contrib` 中）。
- **多 agent 循环** — 对抗性的 Attacker + 多疑的 Reviewer 在最多 3 次迭代中减少误报，并将已确认的发现反馈回去，以便后续迭代能够归纳模式，而不是重复发现相同的 bug。
- **39 种漏洞类型** 涵盖对齐 OWASP 的类别：注入、失效的访问控制、逻辑漏洞、Symfony 特定问题、数据暴露、加密问题 —— 包括现代 Symfony 7.x/8.x 层面（Authenticators、Messenger 处理程序、Webhooks、Serializer denormalizers、Schedules、RateLimiter、Mailer、缓存中毒）。
- **Symfony 感知** — 能够理解 Controllers、Voters、Forms、Firewalls、Routes、`#[IsGranted]`、`denyAccessUnlessGranted`、`#[MapRequestPayload]`、Twig/Live Components，并会标记出缺乏适当访问检查的控制器。
- **基于功能的分块** — 将控制器与其 entity、repository、form、voter 和模板分为一组，以便 Attacker 能够追踪跨文件的数据流。
- **确定性预扫描** — 零 token 的风险标记扫描会标记出具体位置（unserialize、`|raw`、硬编码密钥、不安全的 Doctrine 等），从而让 LLM 更加聚焦；可选的 **lean mode** 会丢弃无标记的文件以减少 token 消耗。
- **Diff mode** — `audit:run --since=main` 仅审计发生更改的文件，适用于快速的 pull-request CI。
- **成本控制杠杆** — 可选择从便宜到昂贵的升级、代码切片、并发 reviewer 调用以及精简预扫描，从而灵活调整 token 消耗。
- **提供商无关** — 只需修改 2 行 YAML 即可在 Claude / GPT / Gemini / Mistral / Llama / DeepSeek / Ollama 之间切换。无需修改代码。
- **跨文件调查工具** — Attacker（以及可选的 Reviewer）可以使用 `read_file`、`grep`、`list_files` 和 `lookup_advisory`（通过 `composer audit` 进行实时 CVE 查询）。
- **PoC 合成** — 可选地为每个高危发现附加一个具体的、可直接复制粘贴的复现方法（curl/console/payload）。
- **拆分模型支持** — 将强大的 Attacker（例如 Claude Opus）与快速的 Reviewer（例如 Claude Haiku）搭配使用，可将成本降低约 20 倍。
- **Prompt caching** — 默认启用 Anthropic prompt caching（约 90% 的输入 token 折扣），在其他平台上会被静默忽略。
- **Content-hash cache** — 完全相同的代码块将完全跳过 LLM。在重复的 CI 运行中可节省大量成本。
- **三种输出格式** — `console`（人类可读）、`json`（机器可读）、`sarif`（用于 GitHub Code Scanning / GitLab Security Dashboard）。
- **CI-ready** — 开箱即用的 GitHub Actions 和 GitLab CI 模板，并包含 SARIF 上传功能。
- **零配置 CVE 数据源** — `lookup_advisory` 由 `composer audit`（Packagist + GitHub Security Advisories）提供开箱即用的支持。
- **DDD 架构** — 严格的分层，唯一的 `LLMClientInterface` 接缝意味着你可以插入自定义的提供商、agents、阶段、安全公告数据源或报告格式。
## 为什么选择这款审计工具？
传统的 **PHP 静态分析** 工具（PHPStan、Psalm）只能捕捉类型错误。**静态 SAST 工具**（Psalm Security、Progpilot）虽然能追踪污点流，但无法对业务逻辑、缺失的授权或多文件攻击链进行推理。**依赖扫描器**（Dependabot、Renovate、Snyk）只会标记第三方包中已知的 CVE。
| 关注点 | 本审计工具 | PHPStan / Psalm | Psalm Security / Progpilot (SAST) | Dependabot / Snyk |
| --------------------------------------- | -------------------------- | --------------- | --------------------------------- | ----------------- |
| 类型 bug | ❌ | ✅ | partial | ❌ |
| 污点流 (SQLi, XSS) | ✅ | ❌ | ✅ | ❌ |
| 缺失 `#[IsGranted]` / Voter | ✅ | ❌ | ❌ | ❌ |
| 业务逻辑漏洞 | ✅ | ❌ | ❌ | ❌ |
| IDOR / 批量赋值 | ✅ | ❌ | partial | ❌ |
| Firewall 配置错误 | ✅ | ❌ | ❌ | ❌ |
| 跨文件攻击链 | ✅ | ❌ | partial | ❌ |
| 依赖项 CVEs | ✅ (通过 `lookup_advisory`) | ❌ | ❌ | ✅ |
| OWASP Top 10 应用层面覆盖 | ✅ | ❌ | partial | ❌ |
## 示例输出
### 控制台模式（已截断）
当 pipeline 运行时，命令会显示一个实时进度条（在向 stdout 输出 `--format=json/sarif` 时以及在使用 `--dry-run` 时会隐藏）：
```
Running audit pipeline...
─────────────────────────
1/3 [=======> ] 33% — ingestion
2/3 [===============> ] 67% — mapping
3/3 [==========================] 100% — audit
```
pipeline 完成后的完整输出：
```
══════════════════════════════════════════════════════════════════════
🔍 SYMFONY LLM AUDIT REPORT — AUDIT-a1b2c3d4
vinceamstoutz/symfony-security-auditor
══════════════════════════════════════════════════════════════════════
Project : /var/www/my-app
Started : 2026-05-22 09:14:02
Duration: 2m 31s
Files : 142 scanned
──────────────────────────────────────────────────────────────────────
RISK LEVEL: HIGH (Score: 34)
──────────────────────────────────────────────────────────────────────
[1] VULN-7f3a1b2c CRITICAL broken_access_control
src/Controller/AdminController.php:42-58
Title: Missing #[IsGranted] on admin DELETE endpoint
OWASP: A01:2021 — Broken Access Control
Confidence: 0.95 Reviewer: ✓ validated
[2] VULN-2e9d5c1a HIGH mass_assignment
src/Controller/UserController.php:71-89
Title: Form type binds isAdmin field from untrusted request
OWASP: A04:2021 — Insecure Design
Confidence: 0.88 Reviewer: ✓ validated
... (3 more findings)
```
### `--dry-run` 模式
扫描文件并在不调用 LLM 的情况下估算 token 使用量和成本。在进行全面审计之前，可以使用此功能来评估成本。
```
bin/console audit:run --dry-run
```
```
Symfony LLM Security Auditor
=============================
Project: /var/www/my-app
Pipeline: Ingestion → Mapping → Audit (Attacker ⚔ Reviewer)
Estimating audit cost (dry run)...
───────────────────────────────────
* Model : claude-opus-4-8
* Tokens: 52,400 in / 4,200 out (total: 56,600)
* Cost : $0.3670 (estimate)
! [NOTE] Dry run — no LLM calls were made. This is a cost estimate only.
[OK] Dry run complete.
```
不会进行任何 LLM 调用；退出代码始终为 `0`。
JSON / SARIF 格式已记录在
[CLI 参考](docs/configuration.md#cli-reference) 和
[输出格式参考](docs/ci.md#output-formats-reference) 中。
## 支持的平台
| 平台 | Bridge 包 | 关键环境变量 |
| -------------------- | ------------------------------------ | ---------------------- |
| Anthropic (Claude) | `symfony/ai-anthropic-platform` | `ANTHROPIC_API_KEY` |
| OpenAI | `symfony/ai-open-ai-platform` | `OPENAI_API_KEY` |
| OpenAI Responses API | `symfony/ai-open-responses-platform` | `OPENAI_API_KEY` |
| Azure OpenAI | `symfony/ai-azure-platform` | `AZURE_OPENAI_API_KEY` |
| Google Gemini | `symfony/ai-gemini-platform` | `GEMINI_API_KEY` |
| Google Vertex AI | `symfony/ai-vertex-ai-platform` | GCP credentials |
| AWS Bedrock | `symfony/ai-bedrock-platform` | AWS credentials |
| DeepSeek | `symfony/ai-deep-seek-platform` | `DEEPSEEK_API_KEY` |
| Mistral | `symfony/ai-mistral-platform` | `MISTRAL_API_KEY` |
| Meta (Llama) | `symfony/ai-meta-platform` | `META_API_KEY` |
| Ollama (local) | `symfony/ai-ollama-platform` | _(none)_ |
切换提供商只需更改 `config/packages/ai.yaml` 即可 —— 无需修改 PHP 代码。
## 文档
- [配置](docs/configuration.md) — 每一个配置键、所有平台、拆分模型、模型选项、CLI 参考
- [架构](docs/architecture.md) — DDD 分层、pipeline、agent 循环、领域模型、设计决策
- [CI 集成](docs/ci.md) — 定时运行的 GitHub Actions 和 GitLab CI、SARIF 上传、成本管理
- [扩展](docs/extending.md) — 自定义 LLM clients、agents、pipeline 阶段、报告格式
- [常见问题](docs/faq.md) — 准确性、成本、隐私、模型选择、对比
- [故障排除](docs/troubleshooting.md) — 空报告、LLM 错误、composer audit 失败、缓存问题
- [贡献指南](CONTRIBUTING.md) — 开发环境设置、Docker 工作流、质量保证 (QA)、PR 检查清单
## 常见问题
**这是 PHPStan 或 Psalm 的替代品吗？** 不是。PHPStan/Psalm 用于捕捉类型错误；而这款审计工具用于捕捉应用层面的逻辑漏洞（缺失授权、批量赋值、业务逻辑 bug）。建议同时两者。
**一次审计的成本是多少？** 取决于项目规模和模型。一个中型 Symfony 应用（约 150 个文件）在使用 Claude Opus + Haiku 拆分模型并启用 prompt caching 的情况下，每次夜间运行的成本约为 $0.50。请参阅 [CI → 管理 LLM 成本](docs/ci.md#managing-llm-costs)。
**它会把我的代码发送到云端吗？** 仅会发送到你配置的 LLM 提供商。如需零云端操作，请使用 [Ollama 本地平台](docs/configuration.md#supported-platforms)。请参阅 [FAQ → 隐私](docs/faq.md#does-this-send-my-source-code-to-a-third-party)。
**误报是个问题吗？** Reviewer agent 会将它们过滤掉 —— 最终报告中只会出现 `reviewer_validated` 的发现。调高 `audit.min_confidence`（默认为 `0.6`）以提高查准率，调低则以提高查全率。
**我应该选择哪个模型？** 追求准确率：Claude Opus / GPT-4o / Gemini 2.5 Pro。追求速度/成本：Claude Haiku / DeepSeek / Mistral Large。追求零成本的本地运行：Ollama (`llama3.3`, `deepseek-r1`)。请参阅 [FAQ → 模型选择](docs/faq.md#which-llm-model-should-i-use)。
完整 FAQ：[docs/faq.md](docs/faq.md)。
## 安全
在**审计工具本身**中发现了漏洞？请**不要**公开提 issue。
请通过
[GitHub Security Advisories](https://github.com/vinceamstoutz/symfony-security-auditor/security/advisories/new)
私下报告。请参阅 [SECURITY.md](SECURITY.md)。
## 许可证
[MIT](LICENSE) — Copyright © Vincent Amstoutz
标签：ffuf, LNA, OpenVAS, PHP, SAST, Symfony, 人工智能, 多智能体, 用户模式Hook绕过, 盲注攻击, 错误基检测, 静态代码分析