security-scan

name

security-scan

description

Standalone security review and vulnerability scan that writes a markdown report only. Use when the user asks for a security review, security scan, vulnerability audit, threat-oriented code review, dependency/security hygiene pass, or to inspect auth, injection, secrets, API security, infrastructure, cryptography, data protection, or logging risks without adopting agile-workflow. Discovers the stack, selects relevant security domains, runs read-only domain audits, classifies severity, and writes security-scan-report.md.

Security-Scan

Run a standalone security audit over a repository or scoped path and write a markdown report. This skill never writes .work/ items, gates, backlog files, or commits.

Invocation

• security-scan — scan the whole repo.
• security-scan <path> — scope to a directory, file, or glob.
• security-scan --domains auth,injection,secrets — restrict to named domains.
• security-scan --output <path> — write somewhere other than security-scan-report.md.

Security Domains

Select only domains relevant to the stack and scope:

Domain	What to inspect
Authentication & Authorization	Auth flows, sessions, RBAC/ABAC, tokens, password policies, object-level authorization
Input Validation & Injection	XSS, SQL injection, command injection, path traversal, template injection, SSRF
Secrets & Configuration	Hardcoded secrets, env leakage, insecure defaults, .env in VCS, exposed config
Dependencies & Supply Chain	Known CVEs, lockfile integrity, typosquatting risk, unnecessary or stale deps
Data Protection	PII handling, encryption in transit/at rest, log sanitization, retention/deletion
API Security	Rate limits, CORS, auth on endpoints, mass assignment, response leakage
Infrastructure & Deployment	Dockerfile, CI/CD secrets, exposed ports, IAM, container hardening, network policy
Cryptography	Weak algorithms, RNG, cert validation, hardcoded keys, key management
Error Handling & Logging	Stack traces, verbose production errors, PII in logs, audit trail gaps

Phase 1: Stack Discovery

Read manifests and deployment/config files: package.json, lockfiles, Cargo.toml, go.mod, pyproject.toml, Dockerfiles, compose files, CI configs, infra files, route registration, auth middleware, API schemas, and environment/config loaders.

Summarize:

• languages and frameworks;
• deployment surface;
• auth/session model;
• data stores and external services;
• public entry points;
• dependency and secret-management posture.

Phase 2: Domain Selection

Mark each domain most relevant, relevant, or skip with evidence. If the user did not pass --domains, ask with a structured question tool when available; otherwise default to all domains with real evidence in the stack.

Phase 3: Domain Audits

Spawn read-only sub-agents in parallel, one per selected domain, or run inline if no sub-agent path is available. Use the strongest reviewer setting for auth, crypto, data-loss, broad public API, or large/polyglot scopes.

Each domain auditor gets:

You are a security scanner for the <domain> domain.

Scope - audit ONLY these files:
<file list>

Stack profile:
<summary>

Method:
1. Read the relevant files in scope.
2. Web-search current best practices and common vulnerabilities for this stack/domain when
   version-sensitive.
3. Confirm every finding in code context.
4. Return findings only; do not implement fixes.

For each finding:
- Title
- Severity: Critical | High | Medium | Low
- Domain
- Location: file:line
- Evidence: 1-5 lines
- Attack or exposure path
- Remediation direction

Severity Rubric

Severity	Meaning
Critical	Actively exploitable now, such as secrets in source, missing auth on public endpoints, plaintext credential storage
High	Significant missing control, known exploitable CVE in deployed dependency, strong attacker leverage
Medium	Hardening gap or vulnerability requiring chained conditions
Low	Defense-in-depth, minor information disclosure, stale but not known-vulnerable dependency

Do not return Info entries as findings.

Phase 4: Aggregate And Verify

1. Dedupe by file:line and root cause.
2. Spot-check every Critical/High and a sample of Medium/Low findings.
3. Drop theoretical findings without a concrete exposure path.
4. Group by severity and domain.

Phase 5: Write The Report

Write security-scan-report.md unless the user supplied --output, using references/report-template.md. Include:

• stack/security surface profile;
• audited domains and skipped-domain reasons;
• findings by severity;
• dependency/security hygiene notes;
• remediation directions;
• scanner gaps;
• recommended fix order.

Guardrails

• Findings require file:line evidence and a concrete security impact.
• Avoid generic OWASP checklists without code evidence.
• Do not run exploit payloads against live systems.
• Do not edit source code.
• Do not write .work/, backlog, release, or tracking artifacts.