# Security Audit

> [Code Quality] Use when a workflow step or the user asks for security audits: OWASP, secrets, supply chain, infrastructure, CI/CD and AI-agent risks.

- Skill: `duc01226/security-audit` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add duc01226/security-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/security-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: duc01226 (https://skillmd.com/u/duc01226)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/duc01226/security-audit

---


> Codex compatibility note:
> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.
> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.
## Quick Summary

> **Review modes:** For review/audit work, standalone defaults to `--review-only` (`--report-only` alias); `--fix-loop` enables review → validate → authorized fix → fresh re-review, default cap 3. `--fix-loop --loop-owner=caller` returns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carried `review-policy` contract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.

**Goal:** Review application, secrets, supply-chain, configuration, pipeline and host risks against OWASP Top 10 (2025) and D1–D10, so credible security failures are exposed and resolved with evidence before handoff.

**Summary:**

- **Route:** Scope (`changes`/`full`/`deps`/`vet`/`host`) → Audit selected D1–D10 domains → Report severity, confidence and remediation → Validate Findings with `$why-review --validate-findings` → approved Fix + Full Re-Review with a fresh `security-auditor`. Round 1 clears every severity; Round 2 clears CRITICAL/HIGH/MEDIUM and defers LOW; binary gates always block.
- Cover every selected surface, beyond application code. D2 secrets always runs; D4 vetting precedes the first third-party install/clone/run, including automation.
- Prove findings with `file:line` or exact command+output; trace exploitability or label "potential risk, not confirmed". Save findings to `tmp/reports/security-audit-{YYMMDD}-{HHmm}-{slug}.md`.
- **`--report-only`:** steps 1–4 only; no fix, restart, nested agents, user question or writer beyond the report. The caller owns fixes; see [Report-Only Mode](#report-only-mode---report-only).

> Use `$security-audit`; `/security` and `/arch-security-review` do not resolve.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.
> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: set `in_progress` when step starts, set `completed` when step ends.
> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.
> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

**Workflow:**

1. **Scope** — Resolve scope mode (`changes`/`full`/`deps`/`vet`/`host`) and select security domains
2. **Audit** — Review every selected domain checklist (D1–D10) with file:line / command-output evidence
3. **Report** — Document findings with severity, confidence, and remediation
4. **Validate Findings** — Run `$why-review --validate-findings <report-path>` before any fix
5. **Fix + Full Re-Review** — Fix only validated findings that block the current round, then restart full security review from Scope; Round 2 LOW-only findings end the loop without another cycle. Not run under `--report-only`.

**Key Rules:**

- Analysis Mindset: systematic review, not guesswork — trace, don't assume
- Check backend, frontend, dependency, pipeline, AND host attack surfaces — code being clean does not mean the system is clean
- Trace the project’s actual authentication/authorization owner (for example middleware, policies, decorators or explicit guards) and resource/tenant access where relevant. Read the selected applicable auth/backend reference for application scope; honor absent/N/A surfaces.
- NEVER install or execute unvetted third-party code as part of this review — vet first (Domain D4)
- Findings are not eligible for fix until `$why-review --validate-findings` confirms them; every validated fix that blocks the current round restarts the full security review from the beginning. Round 1 requires zero open findings (LOW deferral); Round 2 requires zero CRITICAL/HIGH/MEDIUM, with LOW deferred and binary gates still blocking.

<scope>$ARGUMENTS</scope>

## Contents

- [Quick Summary](#quick-summary)
- [Report-Only Mode (`--report-only`)](#report-only-mode---report-only)
- [Analysis Mindset (NON-NEGOTIABLE)](#analysis-mindset-non-negotiable)
- [Scope Modes](#scope-modes)
- [Security Domain Checklists](#security-domain-checklists)
- [Severity & Reporting Model](#severity--reporting-model)
- [Sub-Agent Type Override](#sub-agent-type-override)
- [Recursive Quality Loop](#recursive-quality-loop)
- [Graph Intelligence — Security-Specific Queries (optional advice)](#graph-intelligence--security-specific-queries-optional-advice)
- [Phase 1: Why-Review Findings Validation Gate (MANDATORY when findings exist)](#phase-1-why-review-findings-validation-gate-mandatory-when-findings-exist)
- [Phase 2: Validated Fix + Full Security Re-Review Loop (MANDATORY when validated findings remain)](#phase-2-validated-fix--full-security-re-review-loop-mandatory-when-validated-findings-remain)
- [Anti-Patterns to AVOID (quick recall)](#anti-patterns-to-avoid-quick-recall)
- [Next Steps](#next-steps)
- [Prompt-Enhance Closing Anchors](#prompt-enhance-closing-anchors)
- [Closing Reminders](#closing-reminders)

## Report-Only Mode (`--report-only`)

> **Use when** a caller runs this skill as a read-only leaf — e.g. a workflow parallel review barrier over a plan or design, or a review batch — and another step owns every fix. `--report-only` in `$ARGUMENTS` is an execution flag, not a scope mode; review-only is the default; standalone `--fix-loop` alone runs repair/restart phases.
>
> **MANDATORY — when `--report-only` is passed, read `.claude/skills/workflow-review-changes/references/caller-mode.md` § `--report-only` in full FIRST.** It holds the rules every read-only leaf shares (no fix or restart, scope from the caller's brief, no nested fan-out, no user questions, write only the report, return contract); the rules below are this skill's own.
>
> 1. **Run steps 1–4 only.** Step 5, Phase 2, the Recursive Quality Loop restart, the fresh `security-auditor` spawn, the Next Steps question, and the fix-approval prompt do not run: return the validated report; the caller owns fixes and any re-review. — why: two writers of one artifact inside a barrier race each other.
> 2. **Resolve the scope mode from the caller's brief — never ask.** Record the chosen mode and domains in the report. A plan or design target is audited at design altitude: each in-scope domain checks the designed controls and trust boundaries, cites the plan/design section as `file:line`, and labels an unprovable risk "potential risk, not confirmed". D2 still always runs. — why: a leaf cannot reach the user, so an "else ask" branch would stall the barrier.
> 3. **No nested fan-out.** Skip Systematic Review Batching; review sequentially in this context.
>
> For this mode the declared step order ends at step 4; stopping there is the mode's contract, not a skipped step.

## Analysis Mindset (NON-NEGOTIABLE)

Apply skeptical, critical and sequential thinking. Every claim needs traced proof and confidence; >80% to act, verify uncertainty first.

- Read implementations and trace untrusted inputs to prove exploitability; otherwise label "potential risk, not confirmed".
- Cite `file:line` or exact command+output, and state what was verified. Never report "looks secure" without proof.
- Check every input boundary and selected non-code surface (deps, config, pipeline, host). Clean code or secrets kept in `.env` does not establish system security.

Present validated security findings. Review-only and caller-owned passes return the report. Standalone `--fix-loop` authorizes scoped repairs; ask only for genuinely missing operation authority or the shared round-extension decision.

---

## Scope Modes

Resolve mode from `<scope>` arguments. When ambiguous, default to `changes` if diff exists, else ask.

| Mode               | Trigger                                                           | Domains                                                         |
| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
| `changes` (default) | Review uncommitted/branch changes                                 | D1, D2, D6, D7 (+ D3 if any manifest/lockfile changed, + D9 if CI files changed) |
| `full`             | "audit the codebase/system", "full security review"               | ALL domains D1–D10                                              |
| `deps`             | "check dependencies", "scan packages", after `npm install` issues | D3 (+ D2)                                                       |
| `vet <repo/pkg>`   | BEFORE installing/cloning/running any third-party repo or package | D4 (+ D3)                                                       |
| `host`             | "is this server compromised", VPS audit, post-incident            | D5 (+ D2)                                                       |

**D2 (Secrets) is ALWAYS in scope regardless of mode.** Cheap to check, catastrophic to miss.

---

## Security Domain Checklists

### D1 — Application Security: OWASP Top 10 (2025)

Evaluate every category against in-scope code. Categories updated to OWASP Top 10:2025 release.

**A01 Broken Access Control (now includes SSRF)** — #1 risk.

- [ ] Every in-scope endpoint reaches the intended authentication/authorization enforcement owner; public access is deliberate, never anonymous-by-omission. Verify the actual guard/policy rather than require an attribute API.
- [ ] Resource-level check: entity ownership / tenant (`TenantId`) verified, not just role (IDOR)
- [ ] No client-supplied authority (`request.IsAdmin`, role IDs from body)
- [ ] Privilege escalation paths traced (can a user reach admin handlers via bus events, background jobs, or internal endpoints?)
- [ ] SSRF: user-controlled URLs (webhooks, fetch-by-url, file imports) validated against an allowlist of hosts + `https` scheme; no access to internal services/metadata endpoints

**Example (the IDOR pattern applies to any stack — adapt syntax):**

```csharp
// ❌ VULNERABLE - role checked, resource ownership not
[HttpGet("{id}")]
[Authorize(Roles.Manager)]
public async Task<Order> Get(string id) => await repo.GetByIdAsync(id);

// ✅ SECURE - role + tenant/resource scope enforced
[HttpGet("{id}")]
[Authorize(Roles.Manager, Roles.Admin)]
public async Task<Order> Get(string id)
{
    var order = await repo.GetByIdAsync(id);
    if (order.CustomerId != RequestContext.CurrentTenantId())
        throw new UnauthorizedAccessException();
    return order;
}
```

**A02 Security Misconfiguration**

- [ ] No developer exception pages / stack traces in production
- [ ] Swagger/debug/management endpoints not publicly exposed
- [ ] CORS: no `*` origin with credentials; explicit origin allowlist
- [ ] Security headers (HSTS, X-Content-Type-Options, frame-ancestors/CSP)
- [ ] Default credentials changed in every non-dev environment (see D8)

**A03 Software Supply Chain Failures** (NEW 2025 — highest exploit/impact scores) — run Domain **D3** checklist; for new third-party code run **D4**.

**A04 Cryptographic Failures**

- [ ] No plaintext storage of secrets/tokens/PII that needs encryption at rest
- [ ] No weak/homemade crypto (MD5/SHA1 for auth purposes, ECB, hardcoded IVs/keys)
- [ ] Password hashing uses adaptive algorithm (bcrypt/argon2/PBKDF2/Identity defaults) — never reversible encryption or fast hashes
- [ ] TLS enforced for all transport; no `ServerCertificateCustomValidationCallback => true`

**A05 Injection**

- [ ] SQL/NoSQL: parameterized queries / LINQ only — no string-built queries (`$"... {input} ..."`)
- [ ] Mongo: no `$where`/JS evaluation with user input
- [ ] OS command: no shell concatenation with user input (`Process.Start("cmd", $"/c {input}")`)
- [ ] LDAP/XPath/header/log injection (CRLF in logged user input)
- [ ] XSS: output encoding by default; flag every `innerHTML`, `bypassSecurityTrust*`, `[innerHTML]` with traced sanitization proof

**A06 Insecure Design**

- [ ] Rate limiting on login/OTP/password-reset/expensive endpoints
- [ ] No unlimited enumeration (user existence oracles, sequential IDs without authz)
- [ ] Business-logic abuse: negative quantities, replayed requests, race-to-double-spend on non-idempotent handlers
- [ ] Trust boundaries documented: which inputs are untrusted (HTTP, bus messages, file uploads, third-party APIs)

**A07 Authentication Failures**

- [ ] Strong password policy + account lockout/backoff after failed attempts
- [ ] JWT: signature + issuer + audience + expiry validated; no `alg:none`; key not hardcoded
- [ ] Session/refresh tokens rotated on privilege change; logout invalidates
- [ ] MFA/secrets recovery flows can't be bypassed via alternate endpoints

**A08 Software & Data Integrity Failures**

- [ ] External/bus/third-party data validated before persistence (project validation API)
- [ ] No insecure deserialization of untrusted payloads (`BinaryFormatter`, `TypeNameHandling.All`)
- [ ] Update/plugin mechanisms verify signatures or checksums

**A09 Security Logging & Alerting Failures** (renamed 2025 — alerting matters)

- [ ] Auth events, authz denials, and sensitive operations are logged with actor + target
- [ ] NEVER log passwords, tokens, secrets, or full PII
- [ ] Log volume anomalies / repeated failures actually alert someone (not write-only logs)

**A10 Mishandling of Exceptional Conditions** (NEW 2025)

- [ ] No fail-open: `catch { return true; }`, empty catch around authz/validation, fallback-to-allow on timeout
- [ ] Error paths don't leak internals (stack traces, connection strings, internal hosts)
- [ ] Partial-failure states can't leave security checks skipped (e.g., event handler fails after entity saved)

### D2 — Secrets & Credential Hygiene (ALWAYS RUN)

- [ ] Grep scope for hardcoded secrets:

```bash
rg -n -i "(password|passwd|secret|apikey|api_key|token|connectionstring)\s*[:=]" {configured-source-and-config-roots} | rg -v "(example|sample|placeholder|YOUR_|xxx|<.*>)"
rg -n "(sk_live_|ghp_|github_pat_|AKIA[0-9A-Z]{16}|xox[baprs]-|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY)" {configured-source-and-config-roots}
```

- [ ] `.env`, `appsettings.*.json` with real credentials, `*.pfx/*.pem` keys: in `.gitignore` AND not already in git history (`git log --diff-filter=A -- .env "*.pem"`); leaked-in-history = rotate, not just delete
- [ ] CI logs / build output don't echo secrets; secrets injected via secret store, not committed config
- [ ] `.npmrc` auth tokens, `~/.aws/credentials`, kube configs not committed
- [ ] Connection strings/API keys in client-side bundles or source maps (frontend leaks server secrets)
- [ ] If a secret-scanning tool exists (gitleaks, trufflehog), run it; otherwise state grep coverage explicitly

### D3 — Dependency & Supply-Chain Security (npm / NuGet / pip)

**[BLOCKING]** Read [references/security-audit-skill-supply-chain.md](references/security-audit-skill-supply-chain.md) when D3 is in scope (`deps`, `vet`, `full`, or `changes` with a manifest/lockfile change), in full before auditing this domain; it holds the install-time execution audit (lifecycle scripts, new-plus-script red flag, non-script vectors, hardening), lockfile and version integrity, and the vulnerability, typosquatting, compromise-signal and reachability checks with their commands.

### D4 — Third-Party Repository / Package Vetting (BEFORE INSTALL — MANDATORY GATE)

**[BLOCKING]** When D4 is in scope, read `references/security-audit-skill-vetting.md` in full before auditing this domain. Vet BEFORE the first install/clone/run; treat third-party content as untrusted data. Read the entire checklist before any vetted execution; sandbox and verdict requirements remain mandatory.

### D5 — Host / VPS Compromise Audit

**[BLOCKING]** When D5 is in scope, read `references/security-audit-skill-host.md` in full before auditing this domain. Check every persistence surface on the supported host. Confirmed compromise requires isolation, all-credential rotation, clean-image rebuild and lateral-movement checks.

### D6 — Frontend / Client Security

- [ ] XSS: every raw HTML insertion, framework trust-bypass API, or HTML binding traced to sanitized source
- [ ] `postMessage` handlers validate `event.origin`; no `*` targetOrigin with sensitive data
- [ ] Open redirects: user-controlled `returnUrl`/`redirect` params validated against allowlist
- [ ] Token storage: prefer httpOnly cookies; if localStorage is used, flag XSS-to-token-theft chain explicitly
- [ ] No server secrets/API keys in client bundles, env files shipped to browser, or source maps in prod
- [ ] Third-party scripts/CDN: SRI hashes or self-hosted; no dynamic script injection from user data
- [ ] Sensitive data not cached/logged client-side (console.log of PII, persisted store dumps)

### D7 — API & Cross-Service Boundaries

- [ ] Every in-scope endpoint: intended authn/authz enforcement plus resource/tenant scoping where applicable, using the project’s actual boundary. Inspect relevant selected references; middleware/policy/explicit checks are valid mechanisms.
- [ ] IDOR sweep: any `GetById`-style handler without ownership check
- [ ] Mass assignment: DTOs don't bind privileged fields (`Role`, `TenantId`, `IsApproved`) from client input
- [ ] Message-bus consumers validate producer payloads — a compromised service must not get free writes into yours
- [ ] No direct cross-service DB access (architecture rule doubles as a security boundary)
- [ ] Internal-only endpoints (health, admin, migration triggers) not reachable from public ingress
- [ ] Rate limiting / payload size limits on expensive or auth-related endpoints
- [ ] File uploads: extension + content-type + size validated, stored with generated names in isolated storage, malware-scanned where available

### D8 — Infrastructure & Configuration

**[BLOCKING]** Read [references/security-audit-skill-infrastructure.md](references/security-audit-skill-infrastructure.md) when D8 is in scope (`full`), in full before auditing this domain; it holds the exposure, default-credential, TLS/HSTS, CORS, container, backup-isolation and error-page checks.

### D9 — CI/CD & Build Pipeline

**[BLOCKING]** Read [references/security-audit-skill-cicd.md](references/security-audit-skill-cicd.md) when D9 is in scope (`full`, or `changes` with CI/workflow files changed), in full before auditing this domain; it holds the script-injection, elevated-trigger, action pinning, secret scoping, artifact integrity and branch-protection checks.

### D10 — AI / LLM & Agent Workflow Security

**[BLOCKING]** Read [references/security-audit-skill-ai-agent.md](references/security-audit-skill-ai-agent.md) when D10 is in scope (`full` audits only), in full before auditing this domain; it holds the prompt-injection, MCP/tool provenance, least-privilege agent credential, AI-generated-code review, install-vetting and output-to-shell checks plus the AI-surface route to the AI engineering gate, which applies only when the audit target contains a model call, prompt, agent, tool/MCP, retrieval or eval.

---

## Severity & Reporting Model

| Severity | Bar | Examples |
| -------- | --- | -------- |
| **Critical** | Remote compromise / data breach / active infection now | RCE, authz bypass on sensitive data, leaked live secret, confirmed host backdoor, malicious dependency installed |
| **High** | Exploitable with realistic effort | IDOR, stored XSS, SQL injection behind auth, unpinned compromised-prone supply chain in CI, exposed admin panel |
| **Medium** | Exploitable in combination / hardening gap | Missing rate limit, weak headers, verbose errors, unvetted-but-clean-looking dependency with install script |
| **Low** | Defense-in-depth improvement | Logging gaps, missing SRI, doc/process gaps |

Every finding: `[severity] [confidence %] [file:line OR command+output] [finding] [remediation]`. Confirmed vs "potential risk, not confirmed" must be explicit. Findings report: `tmp/reports/security-audit-{YYMMDD}-{HHmm}-{slug}.md`.

> **Spec-Loop Discipline (Dual-Feedback half — tailored).** Security is orthogonal to functional correctness: property/metamorphic generation and MUTATION-SCORE gates apply to functional core logic and are N/A here. Every confirmed finding that changes intended behavior must feed BOTH the **spec** (§4/§5 security-rule or trust-boundary invariant) AND a **negative test** proving the unauthorized/abusive path is rejected. Examples include authz/tenant scope, input validation, fail-closed behavior and rate limits. Undocumented or untested fixes are **INCOMPLETE**.


---

## Sub-Agent Type Override

> **MANDATORY:** When a restarted security review needs a fresh reviewer after validated fixes, spawn `security-auditor`, NOT `code-reviewer`.
> **Rationale:** `security-auditor` has dedicated OWASP protocols, auth flow analysis, injection risk tracing, dependency CVE checking, and microservices boundary security context that `code-reviewer` lacks.

## Recursive Quality Loop

1. **Review pass:** Main agent runs the domain checklists above → draft findings report
2. **Findings exist:** run `$why-review --validate-findings <security-report-path>` before any fix; do not spawn a fresh sub-agent only to re-review the same findings before validation/fix
3. **After validated fixes:** restart the full security review from Scope over the full current security target. If the restarted review needs a fresh reviewer, spawn a NEW `security-auditor` sub-agent (`agent_type: "security-auditor"`) — ZERO memory of prior rounds. Include in prompt: the domain checklist set (D1–D10) selected for the scope mode, OWASP Top 10 2025, auth flows, injection risks, dependency CVEs/supply-chain, microservices boundary security.
4. **Repeat:** if issues remain, validate the new findings before more fixes, then restart the full review after fixes with a brand-new task breakdown
5. **Stop:** A clean review pass ENDS the review once the persisted `minRounds` is met. If the same blocker repeats across 2 full invocations with no progress, escalate via `ask user question tool`.

> Optional: `python .claude/scripts/code_graph query callers_of <function> --json` can hint at entry points into sensitive functions (verify by reading).

## Graph Intelligence — Security-Specific Queries (optional advice)

Read [references/security-audit-skill-graph-queries.md](references/security-audit-skill-graph-queries.md) when the change is high-risk (shared contract, many callers, cross-module/service/public flow) and `.code-graph/graph.db` exists; it holds the security-specific `callers_of` / `callees_of` / batch queries, vulnerable-dependency reachability and the upstream/downstream data-flow traces. Low-risk or local changes skip it; absence never blocks.

---

## Phase 1: Why-Review Findings Validation Gate (MANDATORY when findings exist)

> **Purpose:** Adversarial validation of own findings BEFORE handoff. Catches over-flagged Highs, false positives, and severity inflation at the source rather than letting them propagate downstream.

**Trigger:** Any finding produced (Critical, High, Medium, OR Low). Skip ONLY when the report's verdict is unconditional PASS with literally zero findings. Also skip when called with `--loop-owner=caller`: the caller validates the merged report once (`$start-workflow` → Workflow-step mode).

**Protocol:**

1. Read own finalized report from `tmp/reports/{skill}-{date}-{slug}.md`
2. Invoke `$why-review --validate-findings tmp/reports/{skill}-{date}-{slug}.md`
3. Read the validation verdict path returned by why-review, expected as `tmp/reports/why-review-validate-{date}.md`
4. **If why-review demotes/removes any finding:** UPDATE own finalized report with revised severities, remove false positives, and add a `## Why-Review Validation Notes` section citing what changed and why
5. **If why-review confirms all findings:** Append `## Why-Review Validation` line to own report stating "All N findings re-validated against actual code; no severity changes."
6. **If the report changed after validation:** re-run this validation gate, maximum 3 validation passes, until the report's remaining findings are validated or zero findings remain.

**Skip conditions (record explicit reason if skipping):**

- Verdict is unconditional PASS with zero findings → log "Skipped — no findings to validate"
- Why-review skill itself is the active context (avoid recursion)
- Called with `--loop-owner=caller` → log "Skipped — the caller validates the merged report once"


---

## Phase 2: Validated Fix + Full Security Re-Review Loop (MANDATORY when validated findings remain)

**Trigger:** Phase 1 returns CLEAN/validated and the security report still has one or more findings that must be fixed. Under `--report-only` this phase never runs — the validated report is returned to the caller.

Read [references/security-audit-skill-fix-loop.md](references/security-audit-skill-fix-loop.md) when Phase 1 leaves validated findings that this run must fix (standalone `--fix-loop`); it holds the seven-step protocol (fresh fix-cycle tasks, fix only validated findings through the caller's fix step or `$fix --target=review`, targeted verification, restart the full audit from Scope with brand-new tasks, repeat to the round's exit bar, stop and ask after two no-progress invocations) and the four non-negotiable rules.

---

## Anti-Patterns to AVOID (quick recall)

- ❌ Trusting client input for authority (`var isAdmin = request.IsAdmin;`)
- ❌ Exposing internal errors (`catch (Exception ex) { return BadRequest(ex.ToString()); }`)
- ❌ Hardcoded secrets (`var apiKey = "sk_live_xxxxx";`)
- ❌ Fail-open exception handling around security checks
- ❌ Installing/running third-party code before D4 vetting ("it has 2k stars" is not vetting)
- ❌ Declaring a host clean because the application code is clean
- ❌ No audit trail for sensitive operations (`await DeleteAllUsers();` with no log)

---

## Next Steps

> **Inside a workflow:** when this skill runs as a step of an active workflow, skip the prompts in this section and return the result — the workflow's next step decides what runs (`$start-workflow` → Step Execution Protocol, Workflow-step mode).

**MANDATORY — NO EXCEPTIONS** after completing this skill, you MUST use `ask user question tool` to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

- **"$production-readiness-review (Recommended)"** — Production readiness review
- **"$performance-review"** — Analyze performance next
- **"Skip, continue manually"** — user decides

> **[IMPORTANT]** Use todo tracking to break ALL work into small tasks BEFORE starting. This prevents context loss from long files. Keep task depth proportional to the work.

- `domain-entities-reference.md`, in the project-reference docs root (default `docs/project-reference/`; a `docsRoots.projectReference.path` entry in `docs/project-config.json` overrides the path) — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

> **External Memory:** For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in `tmp/reports/` — prevents context loss and serves as deliverable.

> **Evidence Gate:** MANDATORY — every claim, finding, and recommendation requires `file:line` proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

<!-- PROTOCOL-GUIDES:START -->

> **Protocol guides** — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

- `category-review-thinking` — Derive review concerns per category of changed files from domain knowledge; reviewing a changeset that spans several file categories → .claude/skills/shared/protocols/category-review-thinking.md
- `evidence-based-reasoning` — Ground every material claim in file:line, config or source evidence, with stated confidence; making any claim, finding or recommendation → .claude/skills/shared/protocols/evidence-based-reasoning.md
- `goal-contract-satisfaction-loop` — Save the goal in a file and loop until every saved criterion passes; executing work against a user goal → .claude/skills/shared/protocols/goal-contract-satisfaction-loop.md
- `graph-assisted-investigation` — Optional hint: a code-graph query can add callers and dependents when grep may miss a high-risk blast radius, and it can be stale; a high-risk change where grep and reading alone may miss the blast radius → .claude/skills/shared/protocols/graph-assisted-investigation.md
- `incremental-persistence` — Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.md
- `measured-capacity-engineering` — Model demand, reduce measured work safely and prove capacity before scaling; planning, building, testing or reviewing hot paths, caches or capacity → .claude/skills/shared/protocols/measured-capacity-engineering.md
- `review-decision-autonomy` — Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.md
- `review-policy` — Review-only or a three-round fix loop with explicit extension and fresh post-fix evidence; deciding round eligibility, blocking findings or review state → .claude/skills/shared/protocols/review-policy.md
- `review-principle-awareness` — Classify the change context first, then apply the current principles that fit it; starting any review → .claude/skills/shared/protocols/review-principle-awareness.md
- `severity-rubric` — One consequence-based Critical, High, Medium, Low scale for every finding and gate; classifying a finding or deciding whether a review round passes → .claude/skills/shared/protocols/severity-rubric.md
- `source-test-drift-check` — When source behavior changes, reconcile the affected tests from evidence; code, fix, test or review work changes behavior → .claude/skills/shared/protocols/source-test-drift-check.md
- `sub-agent-selection` — Pick the sub-agent type from the routing guide; choosing which sub-agent to spawn → .claude/skills/shared/protocols/sub-agent-selection.md
- `subagent-return-contract` — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md
- `systematic-review-batching` — Triage all files and plan adaptive review with complete coverage and no fixed size caps; choosing review assignments or handling working-set overflow → .claude/skills/shared/protocols/systematic-review-batching.md
- `task-tracking-external-report` — Task breakdown before the work and report files written incrementally; starting any multi-step skill, plan or review → .claude/skills/shared/protocols/task-tracking-external-report.md
- `trade-off-interrogation-gate` — Three trade-off questions before any verdict, score or recommendation; rendering a verdict or recommending an option → .claude/skills/shared/protocols/trade-off-interrogation-gate.md

<!-- PROTOCOL-GUIDES:END -->

<!-- SYNC:evidence-based-reasoning:reminder -->

**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim; never speculate. Confidence >80% to act, <60% = do NOT recommend; "not enough evidence" is valid output.

<!-- /SYNC:evidence-based-reasoning:reminder -->

<!-- SYNC:graph-assisted-investigation:reminder -->

**Optional advice:** the code graph (`.code-graph/graph.db`) can hint at a high-risk blast radius grep misses; it can be stale, so verify by reading files. Never required.

<!-- /SYNC:graph-assisted-investigation:reminder -->

<!-- SYNC:task-tracking-external-report:reminder -->

- **MANDATORY** Bootstrap task tracking before target work; transition one task at a time.
- **MANDATORY** Persist plan/review findings to `tmp/reports/` incrementally and synthesize from disk.

<!-- /SYNC:task-tracking-external-report:reminder -->


<!-- SYNC:systematic-review-batching:reminder -->

**MUST ATTENTION** Triage all files, write a short review plan and create review/validation/fix/re-review tasks first. Choose inline work or authorized specialists from risk, relationships and context headroom; no fixed file/line/byte caps. Persist coverage, reconcile interactions and validate findings before fixes or PASS.

<!-- /SYNC:systematic-review-batching:reminder -->

<!-- SYNC:severity-rubric:reminder -->

- **MANDATORY** Classify every finding Critical/High/Medium/Low by consequence using the affected asset, shipped impact, exposure, reversibility, evidence location, and confidence; Critical/High/MEDIUM remain actionable under the round bar, while LOW is recorded/deferred from round 2 onward.
- **MANDATORY** A finding names a reachable trigger path (caller, input, state or event that reaches the defect) and a consequence; an unreachable concern is an observation, and unsettled reachability is `NOT VERIFIABLE` only when the concern would be MEDIUM or higher (an observation otherwise) — never a speculative LOW.
- **MANDATORY** Keep binary gates separate from severity: a failed test, security must-fix, required artifact, or parity check blocks at every round and is never relabeled LOW.
- **MANDATORY** Score-based skills (sre 0-2, perf two-axis) map onto the same four tiers — no parallel severity vocabulary.

<!-- /SYNC:severity-rubric:reminder -->


<!-- SYNC:category-review-thinking:reminder -->

- **MANDATORY** Derive review categories from file language + directory semantics + change nature; create a sub-task per category.
- **MANDATORY** Derive each category's concerns from first principles with `file:line` evidence — never a fixed checklist.

<!-- /SYNC:category-review-thinking:reminder -->

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->

## Prompt-Enhance Closing Anchors

**IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval; inside a workflow run, `$start-workflow` → Workflow-step mode bounds this
**IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution
**IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence
**IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->


<!-- SYNC:goal-contract-satisfaction-loop:reminder -->

- **MANDATORY** Resolve the active Goal Contract BEFORE work (active plan `goal.md` → `<plans root>/goals/{YYMMDD-HHmm}-{slug}/goal.md`, plans root default `plans` and overridable via a `docsRoots.plans.path` entry in `docs/project-config.json` → create from current request) and read saved success criteria before editing.
- **MANDATORY** Append iteration evidence after execution; emit a Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before reporting PASS; loop on validated FAIL; escalate repeated no-progress or blockers. NEVER store secrets in goal files.

<!-- /SYNC:goal-contract-satisfaction-loop:reminder -->

<!-- SYNC:trade-off-interrogation-gate:reminder -->

**Review/audit invocations:** follow `SYNC:review-decision-autonomy` for every decision prompt; choose supported recommendations without asking, preserve round-extension approval and actual authority.

- **MANDATORY MUST ATTENTION ALWAYS ASK THE 3 TRADE-OFF QUESTIONS** — on the thing under review AND on every recommendation you make: (1) **what does it SACRIFICE?** name the dimensions checked (change cost · complexity · perf · coupling · reversibility · migration · ops load · blast radius · security · testability · delivery time · UX) — "none"/"pure win" is an unfinished analysis; (2) **is it worth it?** gain (with a metric) vs cost, WHO pays, WHEN → emit **WORTH IT / NOT WORTH IT / UNCLEAR**; NOT WORTH IT → withdraw or replace it; (3) **is it MATERIAL enough to confirm with the user?** irreversible/one-way door · cost shifted onto another team/ops/maintainer/user · one quality attribute traded for another · a tier/service/event/library boundary crossed · auth/money/data-integrity/breaking-change/High-or-Medium-risk path · verdict UNCLEAR → **STOP and confirm via `ask user question tool` BEFORE the verdict**.
- **MANDATORY** A MATERIAL trade-off with no user confirmation can NEVER be PASS; never bury one as a Low-severity note, never decide it silently, and never let delivery or convergence pressure authorize a one-way door — an un-walked-back one-way door is the user's call, not the reviewer's.
- **MANDATORY — a context that cannot ask escalates BY HANDOFF, never by silence.** `ask user question tool` reaches only the main interactive agent, so a sub-agent or a terminal/verdict-only mode cannot ask. There the duty is REDIRECTED, not waived: still name the trade-off, still decide materiality, record `confirmed? = NO — cannot ask from this context`, and **state the unconfirmed MATERIAL trade-off in your RETURNED verdict so the CALLER escalates it** (a note only in an on-disk report is not a handoff); never emit an unqualified PASS. If you CAN ask, you MUST ask.

<!-- /SYNC:trade-off-interrogation-gate:reminder -->



<!-- SYNC:review-principle-awareness:reminder -->

**IMPORTANT MUST ATTENTION** Every review first checks the change context and routes only applicable principles to their detailed protocols: scale-ready foundation, test intent in the project's native format (GWT is one option), AI-agent-as-user access, and UI/component design when relevant. Record evidence-backed apply/adapt/defer/N/A/block/unverified status with owner and next step; do not invent unrelated findings or expand scope.

<!-- /SYNC:review-principle-awareness:reminder -->

<!-- SYNC:measured-capacity-engineering:reminder -->

**MUST ATTENTION** capacity work: model demand/SLO and distinguish sessions from RPS/in-flight work; disclose load model and offered vs achieved demand; reduce measured work at a safe owner; preserve cache authorization/freshness/bounds; prove cold-state, overload recovery and justified headroom before scaling. Static review returns a verification plan, not invented throughput. Retain the hosting skill's scores, gates and authority.

<!-- /SYNC:measured-capacity-engineering:reminder -->

<!-- SYNC:review-decision-autonomy:reminder -->

**MUST ATTENTION** Decide supported review choices and recommendations, record the rationale, and finish without routine u

…(truncated)
