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.

Table of Contents

• 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 — Symfony Flex wires everything

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

The official Flex recipe (published in symfony/recipes-contrib) automatically:

• registers SymfonySecurityAuditorBundle in config/bundles.php for the dev and test environments;
• creates a pre-configured config/packages/symfony_security_auditor.yaml with a default model and commented split-model and rate-limit examples ready to uncomment.

Not using Flex? See Manual setup.

2. Install a platform bridge (Anthropic shown)

composer require symfony/ai-anthropic-platform

Full list of supported providers: Configuration → Supported platforms.

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

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

4. Adjust the auditor config (config/packages/symfony_security_auditor.yaml)

The Flex recipe already created this file — pick your model:

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

5. Run

# audit the current directory
bin/console audit:run

# or point at another project
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.

Estimate cost before running:

bin/console audit:run --dry-run

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.

Manual setup (without Flex)

Without Symfony Flex (or with composer require --no-scripts), do by hand what the recipe automates:

1. Register the bundles in config/bundles.php:

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

2. Create config/packages/symfony_security_auditor.yaml yourself (step 4 above), or copy the recipe's template.

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

• Symfony Flex recipe — one composer require registers the bundle and ships a pre-configured symfony_security_auditor.yaml (official recipe in symfony/recipes-contrib).
• Multi-agent loop — adversarial Attacker + skeptical Reviewer cut false positives across up to 3 iterations, with confirmed findings fed back so later iterations generalize patterns instead of re-finding the same bugs.
• 39 vulnerability types covering OWASP-aligned categories: Injection, Broken Access Control, Logic Flaws, Symfony-specific, Data Exposure, Cryptographic — including the modern Symfony 7.x/8.x surface (Authenticators, Messenger handlers, Webhooks, Serializer denormalizers, Schedules, RateLimiter, Mailer, cache poisoning).
• Symfony-aware — understands Controllers, Voters, Forms, Firewalls, Routes, #[IsGranted], denyAccessUnlessGranted, #[MapRequestPayload], Twig/Live Components, and surfaces controllers without proper access checks.
• Feature-based chunking — groups a controller with its entity, repository, form, voter, and templates so the Attacker can follow data flow across files.
• Deterministic pre-scan — a zero-token risk-marker pass flags concrete locations (unserialize, |raw, hardcoded secrets, unsafe Doctrine, …) to focus the LLM; optional lean mode drops marker-free files to cut tokens.
• Diff mode — audit:run --since=main audits only changed files for fast pull-request CI.
• Cost levers — opt-in cheap→expensive escalation, code slicing, concurrent reviewer calls, and lean pre-scan to dial token spend up or down.
• Provider-agnostic — swap Claude / GPT / Gemini / Mistral / Llama / DeepSeek / Ollama with a 2-line YAML change. No code edits.
• Cross-file investigation tools — Attacker (and optionally Reviewer) can read_file, grep, list_files, and lookup_advisory (live CVE lookups via composer audit).
• PoC synthesis — optionally attach a concrete, copy-pasteable reproduction (curl/console/payload) to every high-severity finding.
• 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.

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)

The command renders a live progress bar while the pipeline runs (suppressed for --format=json/sarif to stdout and for --dry-run):

 Running audit pipeline...
 ─────────────────────────
 1/3 [=======>                  ]  33% — ingestion
 2/3 [===============>          ]  67% — mapping
 3/3 [==========================] 100% — audit

Full output after the pipeline completes:

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

Scans files and estimates token usage and cost without calling the LLM. Use this to gauge cost before committing to a full audit.

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-7
 * 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.

No LLM calls are made; exit code is always 0.

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

Supported Platforms

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.

License

MIT — Copyright © Vincent Amstoutz