README

AI-powered multi-agent security auditor for Symfony applications. Catches business logic flaws, broken access control, missing Voters, mass assignment, and complex injection chains that traditional SAST tools miss. Provider-agnostic via symfony/ai — works with Claude, GPT, Gemini, Mistral, Llama, DeepSeek, and Ollama.

Stable & predictable. symfony-security-auditor follows Semantic Versioning 2.0.0. The public API — configuration keys, audit:run arguments and options, exit codes, JSON / SARIF output schemas, and the Domain ports listed in docs/extending.md — is covered by our backward compatibility promise. Details: docs/versioning.md.

What it does
Getting Started
Features
Why this auditor?
Example Output
Supported Platforms
Documentation
FAQ
Contributing
Security
License

What it does

Feeds your Symfony project through a three-stage AI pipeline that catches what SAST tools miss: broken access control, complex injection chains, business logic flaws, missing Voters, and mass assignment vulnerabilities. An adversarial Attacker agent hunts for issues; a skeptical Reviewer agent eliminates false positives over up to three iterations. Output is a validated vulnerability report in your console, as JSON, or as SARIF for 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

Getting Started

1. Install

composer require --dev vinceamstoutz/symfony-security-auditor

2. Install a platform bridge (Anthropic shown)

composer require symfony/ai-anthropic-platform

Full list of supported providers: Configuration → Supported platforms.

3. Register bundles (`config/bundles.php`)

Symfony Flex does this automatically via recipe. Otherwise:

return [
    // ...
    Symfony\AI\AiBundle\AiBundle::class => ['all' => true],
    VinceAmstoutz\SymfonySecurityAuditor\SymfonySecurityAuditorBundle::class => ['dev' => true, 'test' => true],
];

4. Configure the platform (`config/packages/ai.yaml`)

ai:
  platform:
    anthropic:
      api_key: '%env(ANTHROPIC_API_KEY)%'

5. Configure the auditor (`config/packages/symfony_security_auditor.yaml`)

symfony_security_auditor:
    model: 'claude-opus-4-5'

6. Run

bin/console audit:run /path/to/your/symfony/project

Want JSON or SARIF instead? Add --format json --output report.json or --format sarif --output report.sarif. See CLI reference.

Warning

Security audit reports contain a list of vulnerabilities in your application. On a public repository, GitHub Actions artifacts and GitLab CI artifacts are publicly downloadable — storing the report as an artifact exposes your attack surface to anyone.

Safe options: GitHub Code Scanning (SARIF upload — restricted to collaborators even on public repos), external private storage (S3, GCS with IAM), or notification-only (Slack/email, no stored file). See Report Visibility on Public Repositories for details.

Tip

Schedule the audit as a nightly CI job — the multi-agent LLM loop can take minutes, so blocking PRs on it hurts productivity. See CI Integration for ready-to-copy GitHub Actions and GitLab CI schedules (SARIF → Code Scanning / Security Dashboard). Use a split-model config (large attacker, cheap reviewer) to control API costs.

For dependency CVEs, use Dependabot or Renovate — they automate composer audit checks and open PRs automatically. This auditor targets application-level logic flaws (broken access control, injection chains, missing Voters) that static dependency scanners cannot see.

Features

Multi-agent loop — adversarial Attacker + skeptical Reviewer cut false positives across up to 3 iterations.
32 vulnerability types covering 6 OWASP-aligned categories: Injection, Broken Access Control, Logic Flaws, Symfony-specific, Data Exposure, Cryptographic.
Symfony-aware — understands Controllers, Voters, Forms, Firewalls, Routes, #[IsGranted], denyAccessUnlessGranted, and surfaces controllers without proper access checks.
Provider-agnostic — swap Claude / GPT / Gemini / Mistral / Llama / DeepSeek / Ollama with a 2-line YAML change. No code edits.
Cross-file investigation tools — the Attacker can read_file, grep, list_files, and lookup_advisory (live CVE lookups via composer audit).
Split-model support — pair a powerful Attacker (e.g. Claude Opus) with a fast Reviewer (e.g. Claude Haiku) to cut cost ~20×.
Prompt caching — Anthropic prompt caching enabled by default (~90% input-token discount), silently ignored elsewhere.
Content-hash cache — identical chunks skip the LLM entirely. Massive savings on repeated CI runs.
Three output formats — console (human-readable), json (machine-readable), sarif (GitHub Code Scanning / GitLab Security Dashboard).
CI-ready — drop-in GitHub Actions and GitLab CI templates with SARIF upload included.
Zero-config CVE feed — lookup_advisory is backed by composer audit (Packagist + GitHub Security Advisories) out of the box.
DDD architecture — strict layering, sole LLMClientInterface seam means you can plug in custom providers, agents, stages, advisory feeds, or report formats.

Why this auditor?

Traditional PHP static analysis tools (PHPStan, Psalm) catch type errors. Static SAST tools (Psalm Security, Progpilot) follow taint flows but cannot reason about business logic, missing authorization, or multi-file attack chains. Dependency scanners (Dependabot, Renovate, Snyk) only flag known CVEs in third-party packages.

Concern	This auditor	PHPStan / Psalm	Psalm Security / Progpilot (SAST)	Dependabot / Snyk
Type bugs	❌	✅	partial	❌
Taint flow (SQLi, XSS)	✅	❌	✅	❌
Missing `#[IsGranted]` / Voter	✅	❌	❌	❌
Business logic flaws	✅	❌	❌	❌
IDOR / mass assignment	✅	❌	partial	❌
Firewall misconfiguration	✅	❌	❌	❌
Cross-file attack chains	✅	❌	partial	❌
Dependency CVEs	✅ (via `lookup_advisory`)	❌	❌	✅
OWASP Top 10 application-level coverage	✅	❌	partial	❌

Use this alongside — not instead of — PHPStan/Psalm and Dependabot. It targets the application-level logic flaws those tools cannot see.

Example Output

Console mode (truncated):

══════════════════════════════════════════════════════════════════════
  🔍 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)

JSON / SARIF formats are documented in CLI Reference and Output Formats Reference.

Supported Platforms

Platform	Bridge package	Key env var
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)

Swapping providers requires only a config/packages/ai.yaml change — no PHP edits.

Documentation

Configuration — every config key, all platforms, split-model, model options, CLI reference
Architecture — DDD layers, pipeline, agent loop, domain model, design decisions
CI Integration — scheduled GitHub Actions & GitLab CI, SARIF upload, cost management
Extending — custom LLM clients, agents, pipeline stages, report formats
FAQ — accuracy, cost, privacy, model picks, comparisons
Troubleshooting — empty reports, LLM errors, composer audit failures, cache issues
Contributing — dev setup, Docker workflow, QA, PR checklist

FAQ

Is this a replacement for PHPStan or Psalm? No. PHPStan/Psalm catch type errors; this auditor catches application-level logic flaws (missing authorization, mass assignment, business logic bugs). Use both.

How much does an audit cost? Depends on project size and model. A medium Symfony app (~150 files) on Claude Opus + Haiku split-model with prompt caching enabled costs roughly $0.50 per nightly run. See CI → Managing LLM Costs.

Does it send my code to the cloud? Only to the LLM provider you configure. For zero-cloud operation, use the Ollama local platform. See FAQ → Privacy.

Are false positives a problem? The Reviewer agent filters them out — only reviewer_validated findings appear in the final report. Tune audit.min_confidence (default 0.6) up for stricter precision, down for higher recall.

Which model should I pick? For accuracy: Claude Opus / GPT-4o / Gemini 2.5 Pro. For speed/cost: Claude Haiku / DeepSeek / Mistral Large. For zero-cost local: Ollama (llama3.3, deepseek-r1). See FAQ → Model picks.

Full FAQ: docs/faq.md.

Contributing

Contributions welcome, please refer to CONTRIBUTING.md.

Security

Found a vulnerability in the auditor itself? Do not open a public issue. Report privately via GitHub Security Advisories. See SECURITY.md.

vinceamstoutz / symfony-security-auditor

Maintainers

Package info

Statistics

Security

README

Table of Contents

What it does

Getting Started

1. Install

2. Install a platform bridge (Anthropic shown)

3. Register bundles (`config/bundles.php`)

4. Configure the platform (`config/packages/ai.yaml`)

5. Configure the auditor (`config/packages/symfony_security_auditor.yaml`)

6. Run

Features

Why this auditor?

Example Output

Supported Platforms

Documentation

FAQ

Contributing

Security

License

vinceamstoutz / symfony-security-auditor

Maintainers

Package info

Statistics

Security

README

Table of Contents

What it does

Getting Started

1. Install

2. Install a platform bridge (Anthropic shown)

3. Register bundles (config/bundles.php)

4. Configure the platform (config/packages/ai.yaml)

5. Configure the auditor (config/packages/symfony_security_auditor.yaml)

6. Run

Features

Why this auditor?

Example Output

Supported Platforms

Documentation

FAQ

Contributing

Security

License

3. Register bundles (`config/bundles.php`)

4. Configure the platform (`config/packages/ai.yaml`)

5. Configure the auditor (`config/packages/symfony_security_auditor.yaml`)