# 🔒 Security Audit Agent System

Turns any coding agent (Claude Code, Codex, Cursor, etc.) into a security auditor for your codebase. No paid tools. No accounts. No frameworks.

## System Architecture

```mermaid
flowchart LR
    U["User input<br/>(repo URL or local path)"] --> O["ORCHESTRATOR_PROMPT.md"]

    O --> P0["Phase 0<br/>Preflight"]
    P0 --> P1["Phase 1<br/>Ingestion + Manifest"]
    P1 --> P2["Phase 2<br/>Scan Groups A/B/C/D"]
    P2 --> P3["Phase 3<br/>Merge + Report"]
    P3 --> D{"User decision"}

    D -->|"Approve fixes"| P4["Phase 4<br/>Apply approved fixes"]
    D -->|"No fixes"| END["Audit complete"]
    P4 --> END

    P0 -. writes .-> W1["progress.json"]
    P1 -. writes .-> W2["repo-manifest.json"]
    P2 -. writes .-> W3["findings/GROUP-*.json"]
    P3 -. writes .-> W4["output/report.md"]
    P4 -. updates .-> W1

    classDef phase fill:#e8f0ff,stroke:#3556a8,stroke-width:1px,color:#0f1e4d;
    classDef io fill:#eefaf1,stroke:#2f7d4b,color:#1a4d2e;
    classDef decision fill:#fff4e6,stroke:#b26a00,color:#6b3f00;
    classDef artifact fill:#f6f6f6,stroke:#666,color:#333;

    class U,O io;
    class P0,P1,P2,P3,P4 phase;
    class D decision;
    class W1,W2,W3,W4 artifact;
```

**How to read this diagram**

- **Main flow (left to right):** orchestrator runs 4 phases in order, then pauses for user decision.
- **Decision gate:** fixes only run after explicit approval.
- **Artifacts:** each phase writes state to `audit-workspace/` so the process is resumable and auditable.
- **Scope split in Phase 2:** vulnerability checks are distributed across Groups A/B/C/D, in parallel when possible.

## Vulnerability Coverage (47 Checks)

| Group | Category | Key Vulnerabilities |
|---|---|---|
| **A** | Injection | SQL, Command, Template, XSS, NoSQL, Log, Prompt Injection |
| **B** | Auth & Session | Hardcoded Secrets, JWT Issues, IDOR, Rate Limiting, RLS/Firebase, OAuth |
| **C** | Crypto & Infrastructure | Weak Hashing, TLS, CORS, SSRF, File Upload, Dependencies, CI/CD |
| **D** | Logic & Integrity | Deserialization, XXE, Race Conditions, Mass Assignment, Business Logic |

## Quick Start

Tell your coding agent:

```
Read ORCHESTRATOR_PROMPT.md and audit: [repo URL or local folder path]
```

That's it. The agent reads these files and knows what to do.

**To let the agent clone this system itself:**
```
Clone [https://github.com/artificialguybr/security-audit-system](https://github.com/artificialguybr/one-prompt-security-audit), read its ORCHESTRATOR_PROMPT.md,
and audit: [your repo URL or local path]
```

## What Gets Checked

**47 vulnerability checks across 4 groups (grep + semantic verification):**

| Group | Checks |
|---|---|
| A · Injection | SQL, command, template, XSS, NoSQL, log, prompt injection |
| B · Auth & Session | Secrets, JWT, IDOR, rate limiting, RLS/Firebase, session, OAuth |
| C · Crypto & Infra | Weak hashing, TLS, CORS, headers, SSRF, file upload, dependencies, CI/CD |
| D · Logic & Integrity | Deserialization, XXE, race conditions, mass assignment, business logic |

Plus preflight: git hygiene, .env exposure, secrets in history, repo visibility.

Full catalog: `VULNERABILITY_CATALOG.md`

## Files

```
ORCHESTRATOR_PROMPT.md    ← Agent entry point
SCANNING_PROMPT.md        ← Vulnerability scanning instructions
REPORT_PROMPT.md          ← Report generation
FIX_PROMPT.md             ← Fix application (git-backed)
VULNERABILITY_CATALOG.md  ← All 47 checks with detection guidance
SYSTEM_SPEC.md            ← Architecture reference
schema/                   ← JSON schemas for generated files
examples/                 ← Example outputs
audit-workspace/          ← Generated during audit (gitignored)
```

## How It Works

1. Agent runs preflight (git hygiene, .env, secrets in history)
2. Agent maps your codebase and writes a manifest
3. Agent scans all 4 groups — parallel if it can spawn sub-agents, sequential otherwise
4. Agent presents all findings in plain language and **waits for your decisions**
5. You approve what gets fixed — agent never touches code without permission
6. Fixes are committed individually to git so you can revert any of them