Claude-Code-Workflow/.codex/skills/security-audit/orchestrator.md

name, description, agents, phases

name	description	agents	phases
security-audit	OWASP Top 10 and STRIDE security auditing with supply chain analysis. Triggers on "security audit", "security scan", "cso".	security-auditor	4

Security Audit

4-phase security audit covering supply chain risks, OWASP Top 10 code review, STRIDE threat modeling, and trend-tracked reporting. Produces structured JSON findings in .workflow/.security/.

Architecture

+----------------------------------------------------------------------+
|  security-audit Orchestrator                                          |
|  -> Mode selection: quick-scan (Phase 1 only) vs comprehensive       |
+-----------------------------------+----------------------------------+
                                    |
              +---------------------+---------------------+
              |                                           |
    [quick-scan mode]                        [comprehensive mode]
              |                                           |
    +---------v---------+                   +------------v-----------+
    |  Phase 1           |                   |  Phase 1               |
    |  Supply Chain Scan |                   |  Supply Chain Scan     |
    |  -> supply-chain-  |                   |  -> supply-chain-      |
    |     report.json    |                   |     report.json        |
    +---------+---------+                   +------------+-----------+
              |                                          |
       [score gate]                          +-----------v-----------+
       score >= 8/10                         |  Phase 2               |
              |                              |  OWASP Review          |
       [DONE or                              |  -> owasp-findings.    |
        DONE_WITH_CONCERNS]                  |     json               |
                                             +-----------+-----------+
                                                         |
                                             +-----------v-----------+
                                             |  Phase 3               |
                                             |  Threat Modeling       |
                                             |  (STRIDE)              |
                                             |  -> threat-model.json  |
                                             +-----------+-----------+
                                                         |
                                             +-----------v-----------+
                                             |  Phase 4               |
                                             |  Report & Tracking     |
                                             |  -> audit-report-      |
                                             |     {date}.json        |
                                             +-----------------------+

---

Agent Registry

Agent	task_name	Role File	Responsibility	Pattern	fork_context
security-auditor	security-auditor	~/.codex/agents/security-auditor.md	Execute all 4 phases: dependency audit, OWASP review, STRIDE modeling, report generation	Deep Interaction (2.3)	false

COMPACT PROTECTION: Agent files are execution documents. When context compression occurs and agent instructions are reduced to summaries, you MUST immediately Read the corresponding agent.md to reload before continuing execution.

---

Fork Context Strategy

Agent	task_name	fork_context	fork_from	Rationale
security-auditor	security-auditor	false	—	Starts fresh; all context provided via assign_task phase messages

Fork Decision Rules:

Condition	fork_context	Reason
security-auditor spawn	false	Self-contained pipeline; phase inputs passed via assign_task

---

Subagent Registry

Utility subagents spawned by security-auditor (not by the orchestrator):

Subagent	Agent File	Callable By	Purpose	Model
inline-owasp-analysis	~/.codex/agents/cli-explore-agent.md	security-auditor (Phase 2)	OWASP Top 10 2021 code-level analysis	haiku

Subagents are spawned by agents within their own execution context (Pattern 2.8), not by the orchestrator.

---

Mode Selection

Determine mode from user request before spawning any agent.

User Intent	Mode	Phases to Execute	Gate
"quick scan", "daily check", "fast audit"	quick-scan	Phase 1 only	score >= 8/10
"full audit", "comprehensive", "security audit", "cso"	comprehensive	Phases 1 → 2 → 3 → 4	no regression (initial: >= 2/10)
Ambiguous	Prompt user: "Quick-scan (Phase 1 only) or comprehensive (all 4 phases)?"	—	—

---

Phase Execution

Phase 1: Supply Chain Scan

Objective: Detect low-hanging security risks in dependencies, secrets, CI/CD pipelines, and LLM integrations.

Input:

Source	Description
Working directory	Project source to be scanned
Mode	quick-scan or comprehensive

Execution:

Spawn the security-auditor agent and assign Phase 1:

spawn_agent({
  task_name: "security-auditor",
  fork_context: false,
  message: `### MANDATORY FIRST STEPS
1. Read: ~/.codex/skills/security-audit/agents/security-auditor.md

## TASK: Phase 1 — Supply Chain Scan

Mode: <quick-scan|comprehensive>
Work directory: .workflow/.security

Execute Phase 1 per: ~/.codex/skills/security-audit/phases/01-supply-chain-scan.md

Deliverables:
- .workflow/.security/supply-chain-report.json
- Structured output summary with finding counts by severity`
})
const phase1Result = wait_agent({ targets: ["security-auditor"], timeout_ms: 300000 })

On timeout:

assign_task({
  target: "security-auditor",
  items: [{ type: "text", text: "Finalize current supply chain scan and output supply-chain-report.json now." }]
})
const phase1Result = wait_agent({ targets: ["security-auditor"], timeout_ms: 120000 })

Output:

Artifact	Description
.workflow/.security/supply-chain-report.json	Dependency, secrets, CI/CD, and LLM findings

---

Quick-Scan Gate (quick-scan mode only)

After Phase 1 completes, evaluate score and close agent.

Condition	Action
score >= 8.0	Status: DONE. No blocking issues.
6.0 <= score < 8.0	Status: DONE_WITH_CONCERNS. Log warning — review before deploy.
score < 6.0	Status: DONE_WITH_CONCERNS. Block deployment. Remediate critical/high findings.

close_agent({ target: "security-auditor" })

If quick-scan mode: Stop here. Output final summary with score and findings count.

---

Phase 2: OWASP Review (comprehensive mode only)

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

Input:

Source	Description
.workflow/.security/supply-chain-report.json	Phase 1 findings for context
Source files	All .ts/.js/.py/.go/.java excluding node_modules, dist, build

Execution:

assign_task({
  target: "security-auditor",
  items: [{ type: "text", text: `## Phase 2 — OWASP Review

Execute Phase 2 per: ~/.codex/skills/security-audit/phases/02-owasp-review.md

Context: supply-chain-report.json already written to .workflow/.security/
Reference: ~/.codex/skills/security-audit/specs/owasp-checklist.md

Deliverables:
- .workflow/.security/owasp-findings.json
- Coverage for all 10 OWASP categories (A01–A10)` }]
})
const phase2Result = wait_agent({ targets: ["security-auditor"], timeout_ms: 360000 })

Output:

Artifact	Description
.workflow/.security/owasp-findings.json	OWASP findings with owasp_id, severity, file:line, evidence, remediation

---

Phase 3: Threat Modeling (comprehensive mode only)

Objective: Apply STRIDE threat model to architecture components; assess attack surface.

Input:

Source	Description
.workflow/.security/supply-chain-report.json	Phase 1 findings
.workflow/.security/owasp-findings.json	Phase 2 findings
Source files	Route handlers, data stores, auth modules, external service clients

Execution:

assign_task({
  target: "security-auditor",
  items: [{ type: "text", text: `## Phase 3 — Threat Modeling (STRIDE)

Execute Phase 3 per: ~/.codex/skills/security-audit/phases/03-threat-modeling.md

Context: supply-chain-report.json and owasp-findings.json available in .workflow/.security/
Cross-reference Phase 1 and Phase 2 findings when mapping STRIDE categories.

Deliverables:
- .workflow/.security/threat-model.json
- All 6 STRIDE categories (S, T, R, I, D, E) evaluated per component
- Trust boundaries and attack surface quantified` }]
})
const phase3Result = wait_agent({ targets: ["security-auditor"], timeout_ms: 360000 })

Output:

Artifact	Description
.workflow/.security/threat-model.json	STRIDE threat model with components, trust boundaries, attack surface

---

Phase 4: Report & Tracking (comprehensive mode only)

Objective: Calculate score, compare with previous audits, generate date-stamped report.

Input:

Source	Description
.workflow/.security/supply-chain-report.json	Phase 1 output
.workflow/.security/owasp-findings.json	Phase 2 output
.workflow/.security/threat-model.json	Phase 3 output
.workflow/.security/audit-report-*.json	Previous audit reports (optional, for trend)

Execution:

assign_task({
  target: "security-auditor",
  items: [{ type: "text", text: `## Phase 4 — Report & Tracking

Execute Phase 4 per: ~/.codex/skills/security-audit/phases/04-report-tracking.md

Scoring reference: ~/.codex/skills/security-audit/specs/scoring-gates.md

Steps:
1. Aggregate all findings from phases 1–3
2. Calculate score using formula: base 10.0 - (weighted_sum / normalization)
3. Check for previous audit: ls -t .workflow/.security/audit-report-*.json | head -1
4. Compute trend (improving/stable/regressing/baseline)
5. Evaluate gate (initial >= 2/10; subsequent >= previous_score)
6. Write .workflow/.security/audit-report-<YYYY-MM-DD>.json

Deliverables:
- .workflow/.security/audit-report-<YYYY-MM-DD>.json
- Updated copies of all phase outputs in .workflow/.security/` }]
})
const phase4Result = wait_agent({ targets: ["security-auditor"], timeout_ms: 300000 })

Output:

Artifact	Description
.workflow/.security/audit-report-<date>.json	Full scored report with trend, top risks, remediation priority

---

Comprehensive Gate (comprehensive mode only)

After Phase 4 completes, evaluate gate and close agent.

Audit Type	Condition	Result	Action
Initial (no prior audit)	score >= 2.0	PASS	DONE. Baseline established. Plan remediation.
Initial	score < 2.0	FAIL	DONE_WITH_CONCERNS. Critical exposure. Immediate triage required.
Subsequent	score >= previous_score	PASS	DONE. No regression.
Subsequent	previous_score - 0.5 <= score < previous_score	WARN	DONE_WITH_CONCERNS. Marginal change. Review new findings.
Subsequent	score < previous_score - 0.5	FAIL	DONE_WITH_CONCERNS. Regression detected. Investigate new findings.

close_agent({ target: "security-auditor" })

---

Lifecycle Management

Timeout Protocol

Phase	Default Timeout	On Timeout
Phase 1: Supply Chain	300000 ms (5 min)	assign_task "Finalize output now", re-wait 120s
Phase 2: OWASP Review	360000 ms (6 min)	assign_task "Output partial findings", re-wait 120s
Phase 3: Threat Modeling	360000 ms (6 min)	assign_task "Output partial threat model", re-wait 120s
Phase 4: Report	300000 ms (5 min)	assign_task "Write report with available data", re-wait 120s

Cleanup Protocol

Agent is closed after the final executed phase (Phase 1 for quick-scan, Phase 4 for comprehensive).

close_agent({ target: "security-auditor" })

---

Error Handling

Scenario	Resolution
Agent timeout (first)	assign_task "Finalize current work and output now" + re-wait 120000 ms
Agent timeout (second)	Log error, close_agent({ target: "security-auditor" }), report partial results
Phase output file missing	assign_task requesting specific file output, re-wait
Audit tool not installed (npm/pip)	Phase 1 logs as INFO finding and continues — not a blocker
No previous audit found	Treat as baseline — apply initial gate (>= 2/10)
User cancellation	close_agent({ target: "security-auditor" }), report current state

---

Output Format

## Summary
- One-sentence completion status with mode and final score

## Score
- Overall: <N>/10 (<Rating>)
- Gate: PASS|FAIL|WARN
- Mode: quick-scan|comprehensive

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

## Artifacts
- File: .workflow/.security/supply-chain-report.json
- File: .workflow/.security/owasp-findings.json (comprehensive only)
- File: .workflow/.security/threat-model.json (comprehensive only)
- File: .workflow/.security/audit-report-<date>.json (comprehensive only)

## Top Risks
1. <Most critical finding with file:line and remediation>
2. <Second finding>

## Next Steps
1. Remediate critical findings (effort: <low|medium|high>)
2. Re-run audit to verify fixes