Skip to content

Latest commit

 

History

History
154 lines (114 loc) · 6.98 KB

usage.md

File metadata and controls

154 lines (114 loc) · 6.98 KB

Usage Guide

Security Review provides prompt-driven security workflows across multi-agent AI coding assistants (Antigravity, Claude Code, Cursor, OpenCode, Codex, Gemini, Goose, Windsurf).


1. Primary Slash Commands

Execute the canonical slash commands directly in your AI coding session:

Slash Command Skill / ID Description
/sr-audit sr-audit Full repository security audit against OWASP Top 10, CWEs, and trust boundaries
/sr-staged sr-staged Fast pre-commit audit of staged git changes (git add)
/sr-branch sr-branch PR and feature branch diff audit against base branch (main)
/sr-plan sr-plan Architecture & technical plan review before coding starts
/sr-tasks sr-tasks Implementation tasks review for security checkpoints & ordering
/sr-followup sr-followup Convert security findings into backlog tasks & technical debt
/sr-apply sr-apply Apply approved security tasks into tasks.md and plan.md
/sr-export sr-export Synthesize executive & technical pentest assessment report
/sr-verify sr-verify Re-verify findings, test exploitability, and generate PoCs
/sr-init sr-init Initialize or update the adapter-resolved security constitution

Note

Standalone names are installed by security-review init. Spec-Kit extension installation instead registers speckit.security-review.* command IDs (for example speckit.security-review.audit). OpenSpec uses the standalone installation, not extension.yml. See Spec-Kit Extension Guide.


2. Basic Workflows

When .security-review/security-review.yml or a legacy root security-review.yml exists, review commands use its scope, focus, severity, and output settings as agent guidance and recheck historical false positives against current evidence. security-review diff and scan do not silently enforce those settings; report any exclusion as a coverage limitation.

Full-Repository Audit

/sr-audit

Triggers a comprehensive security audit of the repository, evaluating authentication, authorization, input validation, encryption, secret exposure, and infrastructure security.

Natural-Language Scoping

Pass natural language arguments to focus the audit:

/sr-audit focus on authentication and session management
/sr-audit review only the src/api and src/auth directories
/sr-audit prioritize OWASP A01:Broken Access Control and A05:Injection

Pre-Commit Staged Review

/sr-staged

Reviews only staged files in git. This is the fastest way to catch vulnerabilities before committing.

Branch / PR Review

/sr-branch feature/oauth-login main

Compares feature/oauth-login against main and reviews the changed code paths for security regressions.


3. Plan & Task Governance

Integrate security into the architecture planning lifecycle:

  1. Plan Review: After creating a technical plan or design document:
    /sr-plan
    
  2. Tasks Review: After generating implementation tasks:
    /sr-tasks
    
  3. Follow-Up & Remediation: After reviewing code or receiving findings:
    /sr-followup
    /sr-apply
    

4. Finding Verification & Proof of Concept (PoC)

Re-verify candidate findings, filter false positives, and generate non-destructive reproduction PoCs:

/sr-verify docs/security-report.md
/sr-verify TASK-SEC-001
/sr-verify verify SQL injection in user search endpoint

Produces:

  • Exploitability Classification: CONFIRMED, FALSE_POSITIVE, FIX_SUGGESTION, MITIGATED, or ACCEPTED_RISK.
  • Proof of Concept (PoC): Automated unit/integration test cases, Playwright E2E specs, and curl/HTTP reproductions, run only inside an OS-enforced sandbox (no external network, empty allow-listed environment, read-only target and toolchain, scratch-only writes, resource limits, no host paths beyond the target, toolchain, and scratch directory). Network traffic goes only to a local instance started inside the sandbox or to a test URL you explicitly confirm as authorized and isolated. Specs are written to the sandbox scratch directory and offered as proposed files for tests/security/.
  • Suppression Config: Automatic YAML snippet for security-review.yml for verified false positives.

When the host cannot provide every sandbox control, /sr-verify does not execute: it keeps the finding at reduced confidence, names the missing control, marks coverage incomplete, and writes a validation plan. Each finding is verified in a fresh context; otherwise the report states that verification was not independent.


5. Formal Pentest Report Export

Synthesize findings into an executive and technical whitebox security assessment:

/sr-export

Generates a formal Markdown report including:

  • Executive Summary: High-level risk score and strategic impact.
  • Technical Findings: Detailed descriptions, exploit scenarios, explicitly versioned CVSS scores (prefer 4.0 for new scoring), and code remediation snippets. Every finding carries its Confidence (high, medium, or low with a rationale), Counterevidence, and Severity Change Conditions; findings produced before these fields existed show not recorded.
  • Coverage: What was reviewed and how each surface closed (reported, ruled_out, no_issue_found, not_applicable, needs_follow_up), followed by a completeness line. coverage_complete: false in the frontmatter lists the caveats, so a clean area is never mistaken for an unvisited one.
  • Architectural Drift: Systemic boundary failures and long-term hardening roadmap.

6. Token-Budgeted CLI Acceleration

Use the CLI companion for instant diff extraction and entrypoint discovery:

# Token-budgeted staged diff extraction (default 8k tokens)
security-review diff --staged

# JSON formatted diff for subagents
security-review diff --branch feature/payment --json --budget 4000

# Discover security entrypoints
security-review scan

7. Hybrid Mode (Agent Reasoning + CLI Generation)

Save tokens by having the agent output machine-readable JSON findings and using the CLI to generate reports and tasks:

# 1. Agent emits findings to findings.json
# 2. Compile full Markdown report deterministically:
security-review report --input findings.json --output docs/security-report.md

# 3. Create or append TASK-SEC-NNN items to tasks.md:
security-review tasks --input findings.json --target tasks.md --append

8. SDD Bridge (OpenSpec & Spec-Kit Integration)

Inspect SDD state before selecting the exact artifact. The legacy sdd propose CLI generates draft files but does not validate the resulting change against the active SDD schema; review and validate drafts before use.

# Check detected SDD framework and active changes
security-review sdd status

# Select the exact task artifact before writing to an OpenSpec or Spec-Kit change
security-review tasks --input findings.json --target path/to/tasks.md --append