cloudflare-security-audit-skill

# cloudflare-security-audit-skill > Skill by [ara.so](https://ara.so) — Security Skills collection. A coding-agent skill that orchestrates multi-phase security audits through parallel agents. It runs six phases: reconnaissance, hunting, adversarial validation, reporting, structured output generation, and independent verification. Designed to find exploitable vulnerabilities with real impact, not theoretical issues. This is the open-source skill that seeded Cloudflare's vulnerability discovery harness. Multiple runs against the same codebase are additive—each explores different attack surfaces while reading prior findings to avoid duplicates. ## What it does The skill coordinates multiple parallel agents through a structured pipeline: 1. **Recon** — Maps architecture, trust boundaries, input surfaces → `architecture.md` 2. **Hunt** — 7 parallel agents attack from different angles (injection, access control, business logic, crypto, feature abuse, chained attacks, wildcard) 3. **Validate** — Separate agents adversarially review each finding to eliminate false positives 4. **Report** — Generates `REPORT.md` and `FINDINGS-DETAIL.md` 5. **Structured output** — Produces `findings.json` validated against `report-schema.json` 6. **Independent verification** — Fresh agents verify every claim against actual source code ## Installation Install using the Skills CLI: ```bash npx skills add https://github.com/cloudflare/security-audit-skill \ --skill security-audit ``` For user-level installation (available across all projects): ```bash npx skills add https://github.com/cloudflare/security-audit-skill \ --skill security-audit \ --global ``` Check installation: ```bash npx skills list ``` ## Usage ### Basic audit Navigate to the codebase you want to audit and invoke: ``` security audit this codebase ``` ``` find security vulnerabilities in ./src ``` ``` do a security review ``` The skill activates on trigger phrases and prompts for an output directory if not specified. ### Specify output directory ``` security audit this project, output to ~/audits/myapp ``` ``` run security-audit skill on ./api, save to /tmp/audit-results ``` Default output location: `~/security-audit-skill/<repo-name>/run-<N>` ### Target specific directories ``` audit the authentication module in ./src/auth ``` ``` find vulnerabilities in ./payment-processing ``` ### Multi-run strategy Run multiple audits for better coverage (each explores different paths): ``` security audit this codebase (run 1 of 3) ``` The skill reads prior `findings.json` files to skip known issues and target unexplored areas. ## Core principles The skill enforces strict security research standards: ### Only report exploitable findings Every finding requires: - Concrete attack scenario - Actual input/payload - Observable impact - Not "could theoretically" or "might allow" **Good**: "CSRF in `/api/delete-account` — no token validation. POST from attacker.com deletes victim's account." **Bad**: "Endpoint lacks CSRF protection and could be vulnerable." ### Adversarial validation - The validator agent is never the finder agent - Validators attempt to disprove findings - Findings survive only if exploitation path is reproducible ### Severity = Likelihood × Impact Not "deviates from best practice" but actual risk: - **CRITICAL**: Full system compromise, data exfiltration, RCE - **HIGH**: Authentication bypass, privilege escalation, PII leak - **MEDIUM**: Partial data exposure, limited privilege escalation - **LOW**: Information disclosure with minimal impact - **INFO**: Defense-in-depth gaps, hardening opportunities ### Defense-in-depth gaps ≠ vulnerabilities If Layer A blocks the attack, missing Layer B is a hardening note, not a vulnerability. Example: If input validation prevents SQL injection, missing prepared statements is INFO at best. ## Output files After a complete audit run, the output directory contains: | File | Purpose | |------|---------| | `architecture.md` | Recon phase: trust boundaries, data flows, input surfaces | | `REPORT.md` | Executive summary with confirmed findings | | `FINDINGS-DETAIL.md` | Detailed traces for MEDIUM+ findings | | `findings.json` | Machine-readable findings conforming to `report-schema.json` | | `validation-logs/` | Adversarial review transcripts | ## Schema validation The skill includes zero-dependency validation: ```javascript // validate-findings.cjs usage const { validateFindings } = require('./validate-findings.cjs'); const findings = require('./findings.json'); const result = validateFindings(findings); if (!result.valid) { console.error('Validation errors:', result.errors); process.exit(1); } ``` Run standalone validation: ```bash node validate-findings.cjs path/to/findings.json ``` ## findings.json structure ```json { "audit_metadata": { "audit_date": "2026-06-20T10:30:00Z", "target_repository": "acme/payments-api", "skill_version": "1.0.0", "run_number": 1 }, "confirmed_findings": [ { "id": "VULN-001", "title": "SQL Injection in transaction search", "severity": "CRITICAL", "category": "Injection", "description": "User-supplied 'query' parameter concatenated directly into SQL", "location": { "file": "src/transactions.js", "line_start": 45, "line_end": 48, "function": "searchTransactions" }, "exploit_scenario": { "attack_vector": "GET /api/transactions?query=' OR '1'='1", "preconditions": ["Authenticated user"], "impact": "Full database read access, including other users' transactions" }, "evidence": { "vulnerable_code": "const sql = `SELECT * FROM transactions WHERE description LIKE '%${req.query.query}%'`;", "proof_of_concept": "curl -H 'Authorization: Bearer $TOKEN' 'https://api.example.com/api/transactions?query=%27%20OR%20%271%27=%271'" }, "remediation": "Use parameterized queries: `SELECT * FROM transactions WHERE description LIKE ?` with bound parameter", "cwe_ids": ["CWE-89"], "verification_status": "independently_verified", "verification_notes": "Confirmed vulnerable code at src/transactions.js:45-48. No input sanitization present." } ], "rejected_findings": [ { "id": "REJECT-001", "title": "Missing rate limiting on login endpoint", "reason": "WAF-level rate limiting confirmed in infrastructure layer (cloudflare-config.yaml). Defense-in-depth gap, not exploitable vulnerability.", "rejected_by": "validator-agent-3", "original_severity": "MEDIUM" } ], "coverage_notes": "Focused on API layer (./src/api). Database layer (./src/db) deferred to next run.", "prior_runs_reviewed": ["run-1/findings.json"] } ``` ## Attack classes The hunting phase spawns parallel agents for: ### Core attack classes 1. **Injection** — SQL, NoSQL, command, template, XSS, XXE 2. **Access Control** — Broken auth, IDOR, privilege escalation, path traversal 3. **Business Logic** — Race conditions, state manipulation, workflow bypass 4. **Cryptography** — Weak crypto, key management, random number generation 5. **Feature Abuse** — Intended features used maliciously 6. **Chained Attacks** — Multi-step exploitation chains ### Wildcard agent Explores unconventional attack surfaces specific to the codebase's domain. ### Obvious-things sweep Quick pass for common mistakes (hardcoded secrets, debug endpoints, default credentials). ## Configuration The skill reads configuration from: 1. Command-line flags (via Skills CLI) 2. Skill metadata in the repository (`.skills/security-audit.json`) 3. Environment variables ### Environment variables ```bash # Output directory override export SECURITY_AUDIT_OUTPUT_DIR=~/custom-audits # Parallel agent count (default: 7 for hunting phase) export SECURITY_AUDIT_PARALLEL_AGENTS=10 # Skip phases (comma-separated: recon,hunt,validate,report,structured,verify) export SECURITY_AUDIT_SKIP_PHASES=recon # Minimum severity to report (CRITICAL, HIGH, MEDIUM, LOW, INFO) export SECURITY_AUDIT_MIN_SEVERITY=MEDIUM # Read prior runs from custom location export SECURITY_AUDIT_PRIOR_RUNS_DIR=~/audits/myapp ``` ### Per-project configuration Create `.skills/security-audit.json` in your repository: ```json { "exclude_paths": [ "test/**", "node_modules/**", "vendor/**" ], "focus_areas": [ "src/auth", "src/payment" ], "custom_attack_classes": [ { "name": "GraphQL-specific", "description": "Query complexity attacks, introspection abuse, batching vulnerabilities" } ], "severity_overrides": { "info_to_low": ["Missing security headers on non-sensitive endpoints"] } } ``` ## Common patterns ### Pattern: Incremental coverage Run multiple audits with different focus areas: ```bash # Run 1: Authentication security audit ./src/auth, output to ~/audits/myapp/run-1 # Run 2: API layer (reads run-1 findings) security audit ./src/api, output to ~/audits/myapp/run-2 # Run 3: Business logic (reads run-1 and run-2) security audit ./src/services, output to ~/audits/myapp/run-3 ``` ### Pattern: CI/CD integration ```yaml # .github/workflows/security-audit.yml name: Security Audit on: schedule: - cron: '0 0 * * 0' # Weekly workflow_dispatch: jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 - name: Install skill run: npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit - name: Run audit run: | # Your coding agent invocation here # Example with Claude Code (adjust for your agent) echo "security audit this codebase, output to ./audit-results" | your-agent-cli - name: Upload results uses: actions/upload-artifact@v4 with: name: security-audit path: audit-results/ - name: Check for critical findings run: | node -e " const findings = require('./audit-results/findings.json'); const critical = findings.confirmed_findings.filter(f => f.severity === 'CRITICAL'); if (critical.length > 0) { console.error(\`Found \${critical.length} CRITICAL findings\`); process.exit(1); } " ``` ### Pattern: Custom attack class Extend hunting with domain-specific attacks: ```javascript // .skills/custom-attacks/api-gateway-abuse.md # API Gateway Abuse Attack Class ## Objective Find vulnerabilities in API gateway routing, transformation, and authentication delegation. ## Attack vectors 1. **Path manipulation** - Backend routing confusion via path traversal - Host header injection to backend services - HTTP method override bypass 2. **Transformation vulnerabilities** - JSON-to-XML conversion XXE - Query parameter injection via transformation - Header smuggling through gateway rewrites 3. **Auth delegation issues** - JWT validation in gateway but not backend - API key leakage in error messages - Rate limit bypass via different endpoints ## Success criteria - Concrete request/response showing bypass - Backend behavior different from gateway expectations - Actual impact (data access, privilege escalation) ``` Then reference in `.skills/security-audit.json`: ```json { "custom_attack_classes": [ { "name": "API Gateway Abuse", "file": ".skills/custom-attacks/api-gateway-abuse.md" } ] } ``` ## Troubleshooting ### Issue: Too many false positives **Symptom**: Findings include theoretical vulnerabilities without exploitation paths. **Solution**: The validation phase should catch these. If not: 1. Check validation logs in `validation-logs/` for validator agent reasoning 2. Strengthen validation prompt: "Prove this finding is NOT exploitable" 3. Set `SECURITY_AUDIT_MIN_SEVERITY=MEDIUM` to filter noise ### Issue: Missing obvious vulnerabilities **Symptom**: Known vulnerabilities not in findings. **Solution**: 1. Check `coverage_notes` in `findings.json` — may be deferred to another run 2. Review `architecture.md` — recon may have missed the affected component 3. Run additional audits with explicit focus: `audit ./src/vulnerable-module` 4. Check if prior runs marked it as rejected (see `rejected_findings`) ### Issue: Validation phase rejects everything **Symptom**: All findings end up in `rejected_findings`. **Solution**: 1. Review `rejection_reason` — often "no concrete exploitation path" 2. Hunters must provide actual payloads, not descriptions 3. Check if defense-in-depth layers are blocking attacks (this is correct rejection) 4. Ensure findings include `proof_of_concept` with real inputs ### Issue: Schema validation fails **Symptom**: `validate-findings.cjs` reports errors. **Solution**: ```bash # Run validator with verbose output node validate-findings.cjs findings.json --verbose # Common errors: # - Missing required fields (id, title, severity, location, exploit_scenario) # - Invalid severity (must be CRITICAL, HIGH, MEDIUM, LOW, INFO) # - Malformed location (missing file or line_start) # - Empty evidence.vulnerable_code ```