Security Audits
Trace what an adversary can make the exact version under review do, from every attacker-controlled source to the sink it reaches. Never copy a prior finding, scanner summary, or comment as a verdict.
When to use
- The version under review changes a trust boundary, or changes how untrusted actors reach data, operations, dependencies, runtime resources, or deployment.
- Skip only after inspecting what the change makes reachable and confirming that no security surface changed. “Small diff” and “internal refactor” are not evidence.
Step 1: Freeze and model
- Stop the writers this task started; report any other writer to its owner and keep review pending until it stops.
- Take as input the review-candidate descriptor a caller passed, with the
identities of the version under review and of its review inputs already
frozen. If a caller is waiting and passed none, the audit is pending: ask
it for one. If no caller is waiting, fill
requesting-code-review's descriptor template yourself, as a review-only request whose one role issecurity. Never obtain a descriptor by invoking a review skill; that dispatches a second review and routes this audit back here. - REQUIRED SUB-SKILL: invoke
verification-before-completionfor the checks on this exact state that apply. Join its state identity byte for byte. - Inventory the threat model: protected assets, trusted and untrusted actors, entry points, trust boundaries, privileges, assumptions, abuse cases. Give each a stable ID and the hash of the source it was taken against.
- For each assumption record: supporting evidence, how it is validated, its owner, its expiry, and what happens if it is false.
Step 2: Trace
- Widen the scope to everything reachable from the changed code: newly reachable old code, callers, shared serializers and guards, generated sources, data stores, dependencies, build and CI, configuration, deployment. Record why each expansion is relevant.
- Note pre-existing unrelated issues separately. Keep them out of this verdict.
- Read
references/audit-checklists.mdbefore tracing, and work every category checklist in it. - Mark each category covered, or obtain an omission for it through Step 4.
- Run the security checks the assurance matrix names for every relevant platform, build mode, and environment cell, inside the effect boundary the descriptor's terminal contract sets. Never exploit shared or production state without exact, direct authority.
- If a check is missing or stale, or that boundary forbids running it, record a blocker and go to Step 4. Do not work around it.
- Write each traced finding in three parts (attacker-controlled source,
propagation, the sink or effect it actually reaches) to a working note at
.sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/security-notes.md, never into the report template. Fix means the smallest change that closes the path. Sensitive evidence means a redacted location or hash, never the value.
Step 3: Verdict
- Dispatch the independent auditor, following
dispatching-parallel-agentsStep 2. The dispatch carries the descriptor, the Step 2.3 checklists, the Step 2.1 scope, andassets/security-report.mdbefore anyone fills it; never your working note or a filled copy. Only the auditor fills the report,Verdictincluded. Never self-certify: a labelled self-audit never issuessecurity clear. - Only the auditor's completed result counts; a running, failed, or
cancelled audit leaves the verdict pending. Read the completed report
before acting on any finding in it. Match
CandidateandReview inputsbyte for byte to the descriptor,State readtoCandidate,Roletosecurity, andVerdictto Step 3.5's three. Compare its Coverage and Findings with your working note and the Step 2.4 category marks. If a field is missing, unreadable, conflicting, or mismatched, or the report leaves a path you traced or a category you marked unaccounted for, the verdict isinconclusive. - REQUIRED SUB-SKILL: invoke
receiving-code-reviewfor every finding that comes back. - After a fix, or any later edit, there is a new version under review:
rerun the affected checks and obtain a focused independent re-audit of
that edit and what it reaches, never a new audit of the whole version.
Its
security clearbinds to the new version. Never certify your own correction. - Issue one verdict:
security clear,security blocked, orinconclusive, bound to the identities of the version under review and of the review inputs.security clearrequires the independent auditor. - Return the report or its location to the requesting review, or to the
user when none is waiting. Leave releasability to
release-readiness. Any later edit voids the verdict until Step 3.4 rebinds it.
Step 4: When a category cannot be covered
This is the case when no check exists, the probe needs shared or production state you cannot touch, or the descriptor's effect boundary forbids the run. Do not approve the omission yourself.
- State the version under review, the blocked category and the reason, and the exposure.
- Ask one question offering these choices: authorize the exact probe, with its effects and blast radius; accept the omission, with an owner, an expiry, and compensation; or keep the version under review security-blocked.
- Recommend, in one sentence, the safest answer the evidence supports. Stop.
- If there is no answer, or the reply is silence or urgency, the verdict
stays
inconclusive. - An accepted omission is bound to this exact version under review and is voided, with the verdict, by any later edit; the Step 3.4 re-audit rebinds both, or records the omission as a blocker again.
- A lack of auditor independence is not on this menu; Step 3 settles it.
Gotchas
- An audit of the changed lines misses old code the change newly exposes. What is reachable from the change sets the scope, not the diff.
- A scanner summary is not a traced path. A finding stands only with its source, propagation, and sink written out, and a summary names none of them.