Reference — generated from the toolkit

Source of truth: toolkit/skills/security-review/spec.md. Edit it there; this page is regenerated on build.

Skill: security-review

• Owner: AI + Security
• Version: 0.1.0
• Lifecycle: draft
• Phase: refinement

Trigger

The Refinement security pass — the ASVS spot-check in the security gates run as a skill rather than an ad-hoc prompt. Point it at a diff or module whenever a security-sensitive change needs a structured second look before the Refinement Exit gate.

Inputs → outputs

• Inputs: a diff or module (read-only), the per-stack OWASP ASVS L2 checklist, and the scaffold's secure-by-default rules.
• Outputs: a findings report with a verdict per applicable control — pass (citing file/line of the satisfying code), fail (location + proposed remediation), or not verifiable (what's missing to judge). Fails feed the Refinement backlog; anything consciously not fixed exits only via a risk-acceptance record.

Procedure

1. Scope: determine which ASVS L2 controls apply to the change (authentication, session, input validation, output encoding, access control, data protection, logging).
2. For each applicable control, locate the code that satisfies or violates it.
3. Verdict per control with evidence-pointing required — a pass must cite the satisfying code by file and line. "Looks fine" is not a verdict.
4. Any control it cannot find evidence for is not verifiable — an explicit result for a human to chase, never a silent pass.
5. Cross-check the secure-by-default posture: authenticated-by-default routes, parameterised queries, context-correct output encoding, no secrets in code.
6. Emit the report ranked by severity for the human security pass to disposition.

Guardrails & permissions

• Read-only on the target code; proposes remediations, never applies them.
• A skill pass is advisory — it does not satisfy the security gates on its own; the Refinement spot-check is signed by a human, and security-critical findings are never waivable.
• Findings touching personal data (UK GDPR — policyholder, claims and medical data) are always escalated, never downgraded by the skill.
• Standard agent guardrails; no production access.

Failure modes

• False confidence — passing a control on plausible-looking but wrong code (mitigated: evidence-pointing means every pass is spot-checkable; reviewers sample citations).
• Checklist myopia — design-level flaws outside the ASVS mapping (mitigated: this is a code-level check; design risk is the threat-modelling playbook's job).
• Stale checklist — controls drifting from the stack (mitigated: the ASVS mapping is versioned with the scaffold).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Seeded-vulnerability diff	fixture diff with N known ASVS violations	all N failed with locations + remediations	recall on seeded findings
Clean module	fixture module satisfying its controls	passes citing the satisfying code	every citation resolves to real satisfying code
Unverifiable control	module whose auth lives outside the fixture	control marked not verifiable	no silent pass