Security Agent Efficiency — Full Audit Orchestration

Orchestrate a deterministic 9-phase security audit of an arbitrary source code repository using specialized subagents and skills.

When to Apply

• Full security audit of a repository
• Advisory regression check combined with static analysis
• Deep vulnerability research on a specific codebase
• "Run the security agents" / "audit for vulnerabilities" / "is this secure?"

Pre-Audit Setup

Before starting any phase:

1. Checkout audit branch: git checkout -b audit (or git checkout audit if it exists)
2. Create audit output directory: mkdir -p <repo-root>/audit/
3. Check for existing outputs: if reports already exist in audit/ and the codebase has not changed since they were produced, reuse them rather than rerunning. Check git log to verify.
4. Add audit dir to .gitignore if not already present (the static-analyzer subagent handles this for SAST artifacts; do it for the audit dir itself too).

9-Phase Workflow

flowchart TD
    Start["Audit Request: Target Repo"] --> Setup["Setup: checkout audit branch, create audit/ dir"]
    Setup --> C{"Reuse existing outputs?"}
    C -->|Yes| Reuse["Reuse reports and skip completed phases"]
    C -->|No| P1

    subgraph phase1 [Phase 1: Intelligence Gathering]
        P1["advisory-hunter subagent"] --> P1a{"Advisories found?"}
        P1a -->|Yes| P1b["Locate patch commits / PRs / versions"]
        P1a -->|None| P1skip["Skip Phase 2"]
        P1b --> P1c["Produce advisory-hunter-report.md"]
    end

    subgraph phase2 [Phase 2: Patch Bypass Analysis]
        P1c --> P2["patch-bypass-checker subagent per patch"]
        P2 --> P2a["Fetch full context via search, fetch, gh CLI"]
        P2a --> P2b["Check patch soundness + version migration"]
        P2b --> P2c["Produce bypass-analysis-report.md"]
    end

    P1skip --> P3
    P2c --> P3

    subgraph phase3 [Phase 3: Knowledge Base]
        P3["knowledge-base-builder subagent"] --> P3a["Classify project type"]
        P3a --> P3b["Build threat model + attack surface"]
        P3b --> P3c["Detect specs / RFCs implemented"]
        P3c --> P3d["Produce threat-model-report.md + attack-surface-report.md + knowledge-base-report.md"]
    end

    subgraph phase4 [Phase 4: Static Analysis]
        P3d --> P4["static-analyzer subagent"]
        P4 --> P4a["Concurrency check: max 1-2 SAST processes"]
        P4a --> P4b["CodeQL per language + Semgrep Pro"]
        P4b --> P4c["Merge SARIF via sarif-parsing skill"]
        P4c --> P4d["Cleanup: delete codeql-db, semgrep cache"]
        P4d --> P4e["Produce static-analysis-report.md"]
        P3d --> P4f{"Has .github/workflows/?"}
        P4f -->|Yes| P4g["agentic-actions-auditor skill"]
        P4g --> P4h["Produce actions-audit-report.md"]
        P4f -->|No| P4i["Skip"]
    end

    subgraph phase5 [Phase 5: Enrichment]
        P4e --> P5["Enrich threat model with SAST findings"]
        P5 --> P5a["Context-aware FP filtering against threat model"]
        P5a --> P5b["Update knowledge-base-report.md"]
    end

    subgraph phase6 [Phase 6: Spec Gap Analysis]
        P5b --> P6{"Specs / RFCs in knowledge base?"}
        P6 -->|Yes| P6a["Fetch spec resources via search / fetch / MCP"]
        P6a --> P6b["spec-to-code-compliance skill"]
        P6b --> P6c["Focus: parsing, normalization, sanitization gaps"]
        P6c --> P6d["Filter to medium-to-critical severity"]
        P6d --> P6e["Produce spec-gaps-report.md"]
        P6 -->|No| P6skip["Skip"]
        P6skip --> P7
    end

    subgraph phase7 [Phase 7: Deep Bug Hunting]
        P6e --> P7["deep-auditor subagent"]
        P7 --> P7a["Threat-model-driven deep dive"]
        P7a --> P7b["Bypass all security measures"]
        P7b --> P7c["Identify concretely exploitable mis-implementations"]
        P7c --> P7d["Project-type-specific attack patterns"]
    end

    subgraph phase8 [Phase 8: FP Elimination]
        P7d --> P8["fp-check skill on all findings"]
        P8 --> P8a["Filter: low-to-critical, bug-bounty context"]
        P8a --> P8b["Exclude: by-design, informational, no exploit path"]
        P8b --> P8c["Produce final-findings-report.md"]
    end

    subgraph phase9 [Phase 9: Variant Analysis]
        P8c --> P9["variant-analysis skill per confirmed bug"]
        P9 --> P9a["Search codebase for similar patterns"]
        P9a --> P9b["Append variants to final-findings-report.md"]
    end

    Reuse --> FinalOut
    P9b --> FinalOut["All reports committed to audit branch"]

Phase Details

Phase 1 — Intelligence Gathering (advisory-hunter subagent)

Invoke the advisory-hunter subagent. It will:

• Search GHSA, CVE/NVD, and project-hosted advisory pages using web search, fetch, or gh CLI
• Locate exact patch commits for each advisory
• Produce audit/advisory-hunter-report.md

If no advisories are found, skip Phase 2 and proceed to Phase 3.

Phase 2 — Patch Bypass Analysis (patch-bypass-checker subagent)

For each patch commit in advisory-hunter-report.md, invoke the patch-bypass-checker subagent in isolation. Each instance receives only the patch diff and advisory metadata — no prior conclusions.

The subagent will:

• Expand context by fetching callers, related files, and external resources
• Test bypass hypotheses (encoding, alternative entry points, config-gated exceptions, default-state bypasses)
• Check whether the patch has been relocated in the latest version
• Produce audit/bypass-analysis-report.md

Phase 3 — Knowledge Base (knowledge-base-builder subagent)

Invoke the knowledge-base-builder subagent. It will:

• Classify the project type (webapp, library, CLI, plugin, protocol, etc.)
• Build threat model and attack surface from actual source code
• Detect which specs/RFCs are implemented and record them for Phase 6
• Produce audit/threat-model-report.md, audit/attack-surface-report.md, audit/knowledge-base-report.md

See references/knowledge-base-template.md for the expected report structure.

Phase 4 — Static Analysis (static-analyzer subagent + agentic-actions-auditor skill)

Invoke the static-analyzer subagent. Before invoking:

# Verify concurrency limit
ps aux | grep -E 'codeql|semgrep' | grep -v grep | wc -l
# Proceed only if count < 2

The subagent will:

• Build CodeQL databases for all supported languages in the repo
• Run Semgrep Pro with --pro flag
• Merge SARIF outputs (use sarif-parsing skill if needed)
• Delete CodeQL databases and semgrep cache after the report is written
• Produce audit/static-analysis-report.md

CodeQL database building is mandatory. Only skip if resources are severely limited (disk/RAM) or the language is unsupported — document the reason.

GitHub Actions audit (run in parallel with static analysis if .github/workflows/ exists):

Invoke the agentic-actions-auditor skill (~/.agents/skills/agentic-actions-auditor/) to analyze all workflow files for AI agent security vulnerabilities. This covers prompt injection via env var intermediary, direct expression injection, dangerous sandbox configurations, wildcard allowlists, and PR target + checkout attack vectors. Produce audit/actions-audit-report.md.

Phase 5 — Enrichment and FP Elimination

After static analysis, perform bidirectional enrichment:

1. SAST → threat model: add newly discovered attack surfaces or vulnerability classes from SAST findings to knowledge-base-report.md.
2. Threat model → SAST FP filter: re-evaluate SAST findings against the project's threat model. A CLI tool has more relaxed command execution constraints than a web app. A library's dangerous API may be intentional. Mark findings that are out of scope for the project's threat model as false positives.

Update knowledge-base-report.md with the enriched context.

Phase 6 — Spec Gap Analysis (spec-to-code-compliance skill)

If knowledge-base-report.md lists implemented specs/RFCs:

1. Fetch the relevant spec documents using web search, fetch, or MCP tools.
2. Invoke the spec-to-code-compliance skill (~/.agents/skills/spec-to-code-compliance/) with the spec documents and codebase.
3. Focus analysis on: parsing behavior, input normalization, sanitization, canonicalization, and state machine compliance.
4. Filter findings to medium-to-critical severity — exclude theoretical gaps with no exploit path.
5. Produce audit/spec-gaps-report.md.

Historical high-value gap categories: URL parsing discrepancies, header injection via spec-non-compliant parsing, OAuth state/nonce omission, JWT algorithm confusion, XML namespace handling, multipart boundary confusion. See references/deep-analysis.md for more patterns.

Phase 7 — Deep Bug Hunting (deep-auditor subagent)

Invoke the deep-auditor subagent with all knowledge base reports as input. It will:

• Work from threat scenarios outward, not from grep results inward
• Attempt to bypass every security measure in the codebase
• Identify concretely exploitable mis-implementations (wrong field, incomplete guard coverage, state/flow errors)
• Apply project-type-specific attack patterns
• Append findings to audit/final-findings-report.md

See references/deep-analysis.md for deep analysis methodology.

Phase 8 — FP Elimination (fp-check skill)

Apply the fp-check skill (~/.agents/skills/fp-check/) to all findings in final-findings-report.md.

Filter criteria:

• Retain: low-to-critical impact bugs that are concretely exploitable in a bug bounty context
• Exclude: by-design behavior, informational findings, defense-in-depth gaps with no direct exploit path, issues requiring full system compromise as a prerequisite

Update audit/final-findings-report.md with verdicts.

Phase 9 — Variant Analysis (variant-analysis skill)

For each confirmed finding, apply the variant-analysis skill (~/.agents/skills/variant-analysis/) to search for similar patterns elsewhere in the codebase.

Append variant findings to audit/final-findings-report.md.

Output Directory

All reports live in <repo-root>/audit/ on the audit branch:

File	Produced by	Phase
advisory-hunter-report.md	advisory-hunter	1
bypass-analysis-report.md	patch-bypass-checker	2
threat-model-report.md	knowledge-base-builder	3
attack-surface-report.md	knowledge-base-builder	3
knowledge-base-report.md	knowledge-base-builder	3
static-analysis-report.md	static-analyzer	4
actions-audit-report.md	agentic-actions-auditor	4 (if .github/workflows/ present)
spec-gaps-report.md	spec-to-code-compliance	6
final-findings-report.md	deep-auditor + fp-check + variant-analysis	7–9

Output Reuse

Before running any phase, check if the corresponding report already exists in audit/ and the codebase has not changed since it was produced:

git log --oneline -5 audit/  # check when reports were last updated
git log --oneline -5 HEAD    # check when codebase last changed

If the report is current, skip that phase and reuse the output.

For static-analyzer: reuse SARIF files when the codebase is unchanged. Do not reuse CodeQL databases (they are deleted after each run).

Fast-Fail Checks

Phase	Agent/Skill	Check	Fallback
1	advisory-hunter	gh CLI or web search available	Use web fetch only
4	static-analyzer	codeql available	Document reason; run Semgrep only
4	static-analyzer	semgrep with --pro available	Run without Pro; note in report
4	static-analyzer	Disk/RAM sufficient for CodeQL DB	Skip CodeQL; document reason
4	agentic-actions-auditor	.github/workflows/ exists	Skip; no GitHub Actions to audit
6	spec-to-code-compliance	Spec documents fetchable	Note which specs could not be retrieved

Deduplication and Report Synthesis

When merging findings across phases:

• Same vulnerability class + file + sink → one consolidated entry; use strongest evidence
• Advisory regression + static finding at same location → elevate confidence; single entry with both sources cited
• Bypass confirmed + static finding → mark as confirmed; include bypass PoC

Confidence levels:

• High: advisory + static + bypass analysis all agree
• Medium: advisory + static, or static + manual analysis
• Low: single source only

Verdict taxonomy:

• VALID — Exploitable within the threat model, in scope
• FALSE POSITIVE — Taint source not attacker-controlled; include reasoning
• BY DESIGN — Intentional, permission-gated, accepted risk
• OUT OF SCOPE — Excluded by bug bounty rules or irrelevant to threat model

Shared Rules

• Attack vector filter: apply the project's threat model dynamically. CLI tools, desktop apps, and embedded systems may have local/adjacent vectors in scope.
• No fix recommendations by default: describe risk and evidence; leave remediation to the dev team unless asked.
• Evidence over volume: a complete source → sink chain with attacker prerequisites is required for every finding.

Post-Audit: Prompt and Skill Optimization

After completing an audit, use the prompt-related skills to improve the quality of any skills, subagents, or prompts that were used or created during the audit:

• prompt-optimizer (~/.agents/skills/prompt-optimizer/) — convert vague or inconsistent instructions in subagent prompts into precise, testable EARS-format specifications. Use when a subagent produced inconsistent or low-quality output during the audit.
• prompt-builder (~/.agents/skills/prompt-builder/) — structure and improve prompts for specific audit tasks. Use when crafting targeted analysis prompts for a specific project type or vulnerability class.
• skill-creator (~/.agents/skills/skill-creator/) — create new skills or improve existing ones based on patterns observed during the audit. Use when a recurring analysis pattern emerges that would benefit from a dedicated skill.

Additional Resources

• references/deep-analysis.md — deep analysis methodology, RFC gap workflow, parsing discrepancy patterns
• references/audit-workflow.md — per-phase detailed instructions, resource management, project-type attack patterns
• references/knowledge-base-template.md — knowledge-base-report.md template
• references/triage-and-prereqs.md — severity guidelines and prerequisite frameworks
• references/report-templates.md — consistent finding formats

Utility Scripts

rg-hotspots.sh: Quick hotspot discovery for common sinks. Use as a starting point for Phase 7, not as final analysis.

./scripts/rg-hotspots.sh [path]