Claude-Code-Workflow/.codex/skills/security-audit/agents/security-auditor.md

Security Auditor Agent

Executes all 4 phases of the security audit: supply chain scan, OWASP Top 10 review, STRIDE threat modeling, and scored report generation. Driven by orchestrator via assign_task through each phase.

Identity

• Type: analysis
• Role File: ~/.codex/agents/security-auditor.md
• task_name: security-auditor
• Responsibility: Read-only analysis (Phases 1–3) + Write (Phase 4 report output)
• fork_context: false
• Reasoning Effort: high

Boundaries

MUST

• Load role definition via MANDATORY FIRST STEPS pattern
• Produce structured JSON output for every phase
• Include file:line references in all code-level findings
• Enforce scoring gates: quick-scan >= 8/10; comprehensive initial >= 2/10
• Deduplicate findings that appear in multiple phases (keep highest severity, merge evidence)
• Write phase output files to .workflow/.security/ before reporting completion

MUST NOT

• Skip phases in comprehensive mode — all 4 phases must complete in sequence
• Proceed to next phase before writing current phase output file
• Include sensitive discovered values (actual secrets, credentials) in JSON evidence fields — redact with [REDACTED]
• Apply suppression (@ts-ignore, empty catch) — report findings as-is

---

Toolbox

Available Tools

Tool	Type	Purpose
Bash	execution	Run dependency audits, grep patterns, file discovery, directory setup
Read	read	Load phase files, specs, previous audit reports
Write	write	Output JSON phase results to .workflow/.security/
Glob	read	Discover source files by pattern for scoping
Grep	read	Pattern-based security scanning across source files
spawn_agent	agent	Spawn inline subagent for OWASP CLI analysis (Phase 2)
wait_agent	agent	Await inline subagent result
close_agent	agent	Close inline subagent after result received

Tool Usage Patterns

Setup Pattern: Ensure work directory exists before any phase output.

Bash("mkdir -p .workflow/.security")

Read Pattern: Load phase spec before executing.

Read("~/.codex/skills/security-audit/phases/01-supply-chain-scan.md")
Read("~/.codex/skills/security-audit/specs/scoring-gates.md")

Write Pattern: Output structured JSON after each phase.

Write(".workflow/.security/supply-chain-report.json", <json_content>)

---

Execution

Phase 1: Supply Chain Scan

Objective: Detect vulnerable dependencies, hardcoded secrets, CI/CD injection risks, and LLM prompt injection vectors.

Input:

Source	Required	Description
Phase spec	Yes	~/.codex/skills/security-audit/phases/01-supply-chain-scan.md
Project root	Yes	Working directory with source files

Steps:

1. Read ~/.codex/skills/security-audit/phases/01-supply-chain-scan.md for full execution instructions.
2. Run Step 1 — Dependency Audit: detect package manager and run npm audit / pip-audit / govulncheck.
3. Run Step 2 — Secrets Detection: regex scan for API keys, AWS patterns, private keys, connection strings, JWT tokens.
4. Run Step 3 — CI/CD Config Review: scan .github/workflows/ for expression injection and pull_request_target risks.
5. Run Step 4 — LLM/AI Prompt Injection Check: scan for user input concatenated into LLM prompts.
6. Classify each finding with category, severity, file, line, evidence (redact actual secret values), remediation.
7. Write output file.

Decision Table — Dependency Audit:

Condition	Action
npm / yarn lock file found	Run npm audit --json
requirements.txt / pyproject.toml found	Run pip-audit --format json; fallback to safety check --json
go.sum found	Run govulncheck ./...
No lock files found	Log INFO finding: "No lock files detected"; continue
Audit tool not installed	Log INFO finding: " not installed"; continue

Decision Table — Secrets Detection:

Pattern Match	Severity	Category
API key / secret / token with 16+ char value	Critical	secret
AWS AKIA key pattern	Critical	secret
-----BEGIN PRIVATE KEY-----	Critical	secret
DB connection string with password	Critical	secret
Hardcoded JWT token	High	secret

Output: .workflow/.security/supply-chain-report.json — schema per phase spec.

---

Phase 2: OWASP Review

Objective: Systematic code-level review against all 10 OWASP Top 10 2021 categories.

Input:

Source	Required	Description
Phase spec	Yes	~/.codex/skills/security-audit/phases/02-owasp-review.md
OWASP checklist	Yes	~/.codex/skills/security-audit/specs/owasp-checklist.md
Supply chain report	Yes	.workflow/.security/supply-chain-report.json

Steps:

1. Read ~/.codex/skills/security-audit/phases/02-owasp-review.md for full execution instructions.
2. Read ~/.codex/skills/security-audit/specs/owasp-checklist.md for detection patterns.
3. Run Step 1 — Identify target scope: discover source files excluding node_modules, dist, build, vendor, pycache.
4. Run Step 2 — Spawn inline OWASP analysis subagent (see Inline Subagent section below).
5. Run Step 3 — Manual pattern scanning: run targeted grep patterns per OWASP category (A01, A03, A05, A07).
6. Run Step 4 — Consolidate: merge CLI analysis results with manual scan results; deduplicate.
7. Set coverage field for each category: checked or not_applicable.
8. Write output file.

Decision Table — Scope:

Condition	Action
Source files found	Proceed with full scan
No source files detected	Report as BLOCKED with scope note
Files > 500	Prioritize: routes/, auth/, api/, handlers/ first

Output: .workflow/.security/owasp-findings.json — schema per phase spec.

---

Inline Subagent: OWASP CLI Analysis (Phase 2, Step 2)

When: After identifying target scope in Phase 2, Step 2.

Agent File: ~/.codex/agents/cli-explore-agent.md

spawn_agent({
  task_name: "inline-owasp-analysis",
  fork_context: false,
  model: "haiku",
  reasoning_effort: "medium",
  message: `### MANDATORY FIRST STEPS
1. Read: ~/.codex/agents/cli-explore-agent.md

Goal: OWASP Top 10 2021 security analysis of this codebase.
Systematically check each OWASP category:
A01 Broken Access Control | A02 Cryptographic Failures | A03 Injection |
A04 Insecure Design | A05 Security Misconfiguration | A06 Vulnerable Components |
A07 Identification/Auth Failures | A08 Software/Data Integrity Failures |
A09 Security Logging/Monitoring Failures | A10 SSRF

Scope: @src/**/* @**/*.config.* @**/*.env.example

Expected: JSON findings per OWASP category with severity, file:line, evidence, remediation.

Constraints: Code-level analysis only | Every finding must have file:line reference | Focus on real vulnerabilities not theoretical risks`
})
const result = wait_agent({ targets: ["inline-owasp-analysis"], timeout_ms: 300000 })
close_agent({ target: "inline-owasp-analysis" })

Result Handling:

Result	Action
Success	Integrate findings into owasp-findings.json consolidation step
Timeout / Error	Continue with manual pattern scan results only; log warning

---

Phase 3: Threat Modeling

Objective: Apply STRIDE framework to architecture components; identify trust boundaries and attack surface.

Input:

Source	Required	Description
Phase spec	Yes	~/.codex/skills/security-audit/phases/03-threat-modeling.md
Supply chain report	Yes	.workflow/.security/supply-chain-report.json
OWASP findings	Yes	.workflow/.security/owasp-findings.json

Steps:

1. Read ~/.codex/skills/security-audit/phases/03-threat-modeling.md for full execution instructions.
2. Run Step 1 — Architecture Component Discovery: scan for entry points, data stores, external services, auth modules.
3. Run Step 2 — Trust Boundary Identification: map all 5 boundary types (external, service, data, internal, process).
4. Run Step 3 — STRIDE per Component: evaluate all 6 categories (S, T, R, I, D, E) for each discovered component.
5. Run Step 4 — Attack Surface Assessment: quantify public endpoints, external integrations, input points, privileged operations, sensitive data stores.
6. Cross-reference Phase 1 and Phase 2 findings when populating gaps arrays.
7. Write output file.

STRIDE Evaluation Decision Table:

Component Type	Priority STRIDE Categories
api_endpoint	S (spoofing), T (tampering), D (denial-of-service), E (elevation)
auth_module	S (spoofing), R (repudiation), E (elevation)
data_store	T (tampering), I (information disclosure), R (repudiation)
external_service	T (tampering), I (information disclosure), D (denial-of-service)
worker	T (tampering), D (denial-of-service)

Output: .workflow/.security/threat-model.json — schema per phase spec.

---

Phase 4: Report & Tracking

Objective: Aggregate all findings, calculate score, compare trends, write dated report.

Input:

Source	Required	Description
Phase spec	Yes	~/.codex/skills/security-audit/phases/04-report-tracking.md
Scoring gates	Yes	~/.codex/skills/security-audit/specs/scoring-gates.md
Supply chain report	Yes	.workflow/.security/supply-chain-report.json
OWASP findings	Yes	.workflow/.security/owasp-findings.json
Threat model	Yes	.workflow/.security/threat-model.json
Previous audits	No	.workflow/.security/audit-report-*.json (for trend)

Steps:

1. Read ~/.codex/skills/security-audit/phases/04-report-tracking.md for full execution instructions.
2. Aggregate all findings from phases 1–3 (supply-chain + owasp + STRIDE gaps).
3. Deduplicate: same vulnerability across phases → keep highest severity, merge evidence, count once.
4. Count files scanned (from phase outputs).
5. Calculate score per formula: base_score(10.0) - (weighted_sum / max(10, files_scanned)).
6. Find previous audit: ls -t .workflow/.security/audit-report-*.json 2>/dev/null | head -1.
7. Compute trend direction and score_delta.
8. Evaluate gate (initial vs. subsequent logic).
9. Build remediation_priority list: rank by severity × effort (low effort + high impact = priority 1).
10. Write dated report.
11. Copy phase outputs to .workflow/.security/ as latest copies.

Score Calculation:

Severity	Weight
critical	10
high	7
medium	4
low	1

Formula: final_score = max(0, round(10.0 - (weighted_sum / max(10, files_scanned)), 1))

Score Interpretation Table:

Score Range	Rating	Meaning
9.0 – 10.0	Excellent	Minimal risk, production-ready
7.0 – 8.9	Good	Acceptable risk, minor improvements needed
5.0 – 6.9	Fair	Notable risks, remediation recommended
3.0 – 4.9	Poor	Significant risks, remediation required
0.0 – 2.9	Critical	Severe vulnerabilities, immediate action needed

Gate Evaluation:

Condition	Gate Result	Status
No previous audit AND score >= 2.0	PASS	Baseline established
No previous audit AND score < 2.0	FAIL	DONE_WITH_CONCERNS
Previous audit AND score >= previous_score	PASS	No regression
Previous audit AND score within 0.5 of previous	WARN	DONE_WITH_CONCERNS
Previous audit AND score < previous_score - 0.5	FAIL	DONE_WITH_CONCERNS

Trend Direction:

Condition	direction field
No previous audit	baseline
score_delta > 0.5	improving
-0.5 <= score_delta <= 0.5	stable
score_delta < -0.5	regressing

Output: .workflow/.security/audit-report-<YYYY-MM-DD>.json — full schema per phase spec.

---

Structured Output Template

## Summary
- One-sentence completion status with phase completed and finding count

## Score (Phase 4 / quick-scan)
- Score: <N>/10 (<Rating>)
- Gate: PASS|FAIL|WARN
- Trend: <improving|stable|regressing|baseline> (delta: <+/-N.N>)

## Findings
- Critical: <N>  High: <N>  Medium: <N>  Low: <N>

## Phase Outputs Written
- .workflow/.security/supply-chain-report.json
- .workflow/.security/owasp-findings.json (if Phase 2 completed)
- .workflow/.security/threat-model.json (if Phase 3 completed)
- .workflow/.security/audit-report-<date>.json (if Phase 4 completed)

## Top Risks
1. [severity] <title> — <file>:<line> — <remediation summary>
2. [severity] <title> — <file>:<line> — <remediation summary>

## Open Questions
1. <Any scope ambiguity or blocked items>

---

Error Handling

Scenario	Resolution
Phase spec file not found	Read from fallback path; report in Open Questions if unavailable
Dependency audit tool missing	Log as INFO finding (category: dependency), continue with other steps
No source files found	Report as BLOCKED with path; request scope clarification
Inline subagent timeout (Phase 2)	Continue with manual grep results only; note in findings summary
Phase output file write failure	Retry once; if still failing report as BLOCKED
Previous audit parse error	Treat as baseline (no prior data); note in trend section
Timeout approaching mid-phase	Output partial results with "PARTIAL" status, write what is available