security-audit

name	security-audit
description	Generative vulnerability-discovery harness for an entire codebase, driven by parallel sub-agents and adversarial validation. Unlike the deterministic CI gates (repo_security_scan, regex_safety_audit, prompt_injection_scan) which prevent KNOWN bad patterns from recurring, this skill DISCOVERS unknown, exploitable vulnerabilities through a six-phase pipeline: recon, multi-angle hunting, adversarial validation, reporting, structured findings, and independent verification. Use this skill when asked to run a deep security audit, hunt for exploitable vulnerabilities, perform the quarterly threat-model discovery exercise, or find security bugs that pattern matching misses. Outputs findings.json conforming to report-schema.json and hands confirmed findings into the threat-model staging layer. Trigger on 'security audit', 'vulnerability hunt', 'quarterly threat model exercise', 'find exploitable bugs', or /security-audit.
license	MIT — adapted from cloudflare/security-audit-skill. See NOTICE.
metadata	{"version":"0.1.0","adapted_from":"https://github.com/cloudflare/security-audit-skill","upstream_license":"MIT (Copyright (c) 2025-2026 Cloudflare, Inc.)"}

Security Audit (generative vulnerability discovery)

When this skill starts, display this banner before doing anything else:

Security Audit v0.1.0 — adapted from cloudflare/security-audit-skill (MIT)
https://github.com/cloudflare/security-audit-skill

This skill is council-forge's discovery engine. It complements — does not replace — the deterministic, fail-closed CI gates:

Layer	Job	Tool
Prevent recurrence (known bad patterns)	CI gates, fail-closed	repo_security_scan.py, regex_safety_audit.py, prompt_injection_scan.py, sca/sbom/sast/security_txt
Discover the unknown (novel exploitable bugs)	this skill	parallel sub-agents + adversarial validation
Track over time	threat model	threat-model-*/threat-inventory.json + artifacts/governance/threat-findings-pending-update.*.json

It is the automated realization of docs/red_team_runbook.md's discovery half: where the runbook drives static workflow-integrity cases (run_red_team_suite.py), this skill drives generative product/code vulnerability hunting.

Core principles (from the upstream methodology)

1. Only report what you can exploit. A deviation from best practice is not a finding unless you can describe a concrete attacker, payload, and observable result.
2. Severity is likelihood × impact, not checklist conformance. Score impact by what an attacker actually gains.
3. Discovery and validation are different agents. The agent that finds a bug must not be the agent that confirms it — separate, adversarial review kills false positives.
4. Verify every factual claim against source. A finding's trace (file:line) must be re-checked by a fresh agent reading the actual code, not the finding text.
5. Iterate. Each independent run finds materially more; run ≥2 rounds for a real audit.

Inputs

• Target: a repo path (default: repo root). For council-forge itself, also include artifacts/scripts/ (the guard/gate control plane) as a high-value target.
• Output dir: artifacts/red_team/audit/run-<N>/ (kept out of the prompt-injection scan scope; see prompt_injection_scan.py SCAN_EXCLUDE_PREFIXES).

Pipeline

Phase 1 — Recon

Spawn parallel Explore sub-agents to map architecture, entrypoints, trust boundaries, auth model, external I/O, and the control plane (guards/gates). Write architecture.md. One agent per subsystem; each returns a structured map, not file dumps.

Phase 2 — Hunt

Spawn one sub-agent per attack class, each blind to the others, each told to produce concrete exploit traces (entrypoint → propagation → sink). Attack classes:

1. Injection — command/SQL/template/path/argument injection; deserialization.
2. Access control — authn/authz bypass, IDOR, privilege escalation, missing checks.
3. Cryptography — weak primitives, predictable randomness, secret handling.
4. Business logic — state-machine abuse, race conditions, TOCTOU, invariant breaks.
5. Feature abuse — using a feature as intended for unintended damage (quota, cost, DoS).
6. Chained — low-severity primitives composed into a high-severity exploit.
7. Wildcard — anything unconventional the other lenses would miss.

For council-forge specifically, add a workflow-integrity lens: can crafted artifact content subvert a guard/gate, launder scope drift, poison authority, or DoS a validator (ReDoS)? (Cross-check against existing findings FIND-18/23/24/35 — do not re-report mitigated ones.)

Phase 3 — Validate (adversarial)

For each candidate finding, spawn a different sub-agent whose job is to refute it: prove the code path doesn't exist, a mitigation prevents it, or the trace is wrong. Default to rejected under uncertainty. Survivors only proceed.

Phase 4 — Report

Write REPORT.md (human triage: ranked by severity, one paragraph each) and FINDINGS-DETAIL.md (full trace + reproduction per finding).

Phase 5 — Structured output

Write findings.json — an array of objects each conforming to report-schema.json (output_schema.oneOf: a confirmed object with the full required fields, or a rejected object with a reason). Then validate it:

python .github/skills/security-audit/scripts/validate_findings.py \
  --findings artifacts/red_team/audit/run-<N>/findings.json

The validator is fail-closed (exit 1 on any schema violation): trace must start with an entrypoint and end with a sink; enums and required fields are enforced from the schema.

Phase 6 — Independent verification

Spawn fresh sub-agents that re-read the cited source for each confirmed finding and confirm every trace step and execution.payload. Downgrade or reject anything that doesn't hold.

Phase 7 — Governance handoff (council-forge integration)

Confirmed findings are staged into the threat model — they do not edit the frozen inventory snapshot. For each confirmed finding, append an entry to artifacts/governance/threat-findings-pending-update.<plan>.json (entries[]) using this mapping; finalization into a new inventory snapshot is the quarterly exercise's job:

pending-update field	from findings.json
finding_id	AUDIT-<run>-NN (canonical FIND-NN assigned at the next snapshot)
title	title
proposed_status	"Open" (newly discovered)
severity	severity.overall_severity
evidence_refs	the findings.json path + each trace[].file:line
rationale	root_cause + intended_behavior + execution.expected_result
source_task_id	the audit run id (e.g. security-audit-run-<N>)
red_team_execution_ref	<findings.json path>#<title>
residual_risk	remediation.strategy (the fix that would close it)

Rejected findings are retained in findings.json for audit-trail completeness but are not staged.

Requirements

• A coding agent with tool use and parallel sub-agents (Claude Code: Agent / Workflow).
• Python 3 (stdlib only) for validate_findings.py. No Node dependency (the upstream validate-findings.cjs was reimplemented in stdlib Python to match the repo's CLI-first, dependency-light convention).

Attribution

Methodology, phase structure, and report-schema.json are adapted from cloudflare/security-audit-skill (MIT). See NOTICE for the full license and copyright.