| name | security-review-spec |
| description | Audit a product or tech spec pull request diff for high-level security concerns (threat surface, authentication and authorization model, trust boundaries, sensitive data handling, secrets and key management, dependency posture, and abuse or misuse cases) and fold findings into the same review.json produced by the base spec review. Use as a supplement to `review-spec` whenever a spec PR is being reviewed. |
Security Review Spec Skill
Audit the current spec pull request for design-level security concerns and fold
any findings into the same review.json produced by review-spec.
Required Contract
Read .agents/contracts/review.md and follow it exactly. This skill is a
supplement to review-spec; it must not create a separate report, change the
review.json schema, loosen diff-line targeting, post to GitHub, perform
code-level review, or regenerate snapshots.
When To Apply
- Apply on spec PRs whenever
review-spec is applied.
- Do not apply on code PRs handled by
review-pr.
- Skip the skill when the changed spec content has no plausible security
surface, such as purely editorial wording, typo fixes, or doc structure
cleanup.
- Do not duplicate findings the base
review-spec pass will already raise.
Security Concerns
Evaluate changed spec content at the design-doc level. Focus on gaps or
ambiguities that would plausibly lead to an insecure implementation.
Threat Surface And Trust Boundaries
- New external inputs, endpoints, webhooks, CLI surfaces, or file formats
without clear reachability and trust assumptions.
- User-supplied or third-party content flowing into automation, prompts,
commands, or storage without a validation or sanitization plan.
- Features that expand what unauthenticated or low-privilege actors can cause
the system to do.
- Agent or LLM-driven flows where untrusted input can be interpreted as
instructions without a mitigation.
Authentication And Authorization
- New actors, roles, automation identities, or triggers without clear
authentication and authorization rules.
- Informal enforcement language such as "only maintainers can trigger this"
without saying how the workflow enforces it.
- Privilege escalation where a less-privileged actor can cause a more-privileged
bot, workflow, or agent to act on their behalf.
Sensitive Data, Secrets, And Privacy
- New data collection, storage, logging, or transmission without sensitivity,
retention, or access-control expectations.
- Private repository contents, personal data, auth tokens, session identifiers,
or customer data routed through logs, prompts, or third-party services without
a redaction plan.
- New credentials, API keys, signing keys, or tokens without storage, access,
rotation, and leak-response expectations.
Abuse, Dependencies, Defaults, And Observability
- Externally triggerable automation without rate limiting, deduplication, retry,
or cost-control expectations.
- Recursive or unbounded work caused by comments, webhooks, scheduled jobs, or
poisoned inputs.
- New third-party services, registries, models, or binaries without trust or
pinning assumptions.
- Unsafe or unspecified defaults where the safe choice is not obvious.
- Security-relevant operations without logging, log protection, or abuse
detection expectations.
Reporting
- Prefix every security finding's comment body with
[SECURITY] after the
severity label, for example ⚠️ [IMPORTANT] [SECURITY] Authentication model for new webhook is unspecified: ....
- Add a
## Security subsection to the top-level review body only when there
are security findings.
- Count security findings toward the same review summary and verdict. A critical
design-level security gap should generally produce
REJECT.
- Tie findings to changed spec lines when possible. Put broad or cross-document
concerns in top-level
body.
Boundaries
- Do not perform code-level review.
- Do not run dynamic scans, fetch remote advisories, or call external security
APIs.
- Do not treat a spec as insecure just because it does not enumerate every
threat; focus on concerns likely to cause a missed mitigation.
