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: "<tool> 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 |