security-scanner

Security Scanner

Proactive pre-deployment security assessment. SAST pattern matching, secrets detection, dependency scanning, OWASP/CWE mapping, and compliance heuristics.

Scope: Pre-deployment security audit only. NOT for code review (use honest-review), penetration testing, runtime security monitoring, or supply chain deep analysis.

Canonical Vocabulary

Term	Definition
finding	A discrete security issue with severity, CWE mapping, confidence, and remediation
severity	CRITICAL / HIGH / MEDIUM / LOW / INFO classification per CVSS-aligned heuristics
confidence	Score 0.0-1.0 per finding; >=0.7 report, 0.3-0.7 flag as potential, <0.3 discard
CWE	Common Weakness Enumeration identifier mapping the finding to a known weakness class
OWASP	Open Web Application Security Project Top 10 category mapping
SAST	Static Application Security Testing — pattern-based source code analysis
secret	Hardcoded credential, API key, token, or private key detected in source
lockfile	Dependency manifest with pinned versions (package-lock.json, uv.lock, etc.)
compliance	Lightweight heuristic scoring against SOC2/GDPR/HIPAA controls
triage	Risk-stratify files by security relevance before deep scanning
remediation	Specific fix guidance with code examples when applicable
SARIF	Static Analysis Results Interchange Format for CI integration
false positive	Detection matching a pattern but not an actual vulnerability

Dispatch

$ARGUMENTS	Mode	Action
Empty	scan	Full codebase security scan with triage/sampling
scan [path]	scan	Full security scan of path (default: cwd)
check <file/dir>	check	Targeted security check on specific files
deps [path]	deps	Dependency lockfile analysis
secrets [path]	secrets	Secrets-only regex scan
compliance <standard>	compliance	SOC2/GDPR/HIPAA heuristic checklist
report	report	Dashboard visualization of findings
Unrecognized input	—	Ask for clarification

Mode: scan

Full codebase security assessment with triage and sampling for large codebases.

Step 1: Triage

1. Enumerate files: find or Glob to build file inventory
2. Risk-stratify files into HIGH/MEDIUM/LOW security relevance:
   • HIGH: auth, crypto, payments, user input handling, API endpoints, config with secrets
   • MEDIUM: data models, middleware, utilities touching external I/O
   • LOW: static assets, tests, documentation, pure computation
3. For 100+ files: sample — all HIGH, 50% MEDIUM, 10% LOW
4. Build dependency graph of HIGH-risk files

Step 2: SAST Pattern Scan

Read HIGH and sampled MEDIUM/LOW files. Match against patterns from references/owasp-patterns.md:

• Injection flaws (SQL, command, path traversal, template, LDAP)
• Authentication/session weaknesses
• Sensitive data exposure (logging PII, plaintext storage)
• XXE, SSRF, deserialization
• Security misconfiguration
• XSS (reflected, stored, DOM)
• Insecure direct object references
• Missing access controls
• CSRF vulnerabilities
• Using components with known vulnerabilities

Step 3: Secrets Scan

Run: uv run python skills/security-scanner/scripts/secrets-detector.py <path> Parse JSON output. Cross-reference findings with .gitignore coverage.

Step 4: Dependency Check

If lockfiles exist, run: uv run python skills/security-scanner/scripts/dependency-checker.py <path> Parse JSON output. Flag outdated or unmaintained dependencies.

Step 5: CWE/OWASP Mapping

Map each finding to CWE IDs and OWASP Top 10 categories using references/cwe-patterns.md. Assign severity (CRITICAL/HIGH/MEDIUM/LOW/INFO) and confidence (0.0-1.0).

Step 6: Remediation

For each finding with confidence >= 0.7, provide:

• CWE reference link
• Specific remediation guidance
• Code example when applicable

Step 7: Report

Present findings grouped by severity. Include:

• Executive summary with finding counts by severity
• Detailed findings with CWE, OWASP, evidence, remediation
• Dependency health summary (if lockfiles scanned)
• Secrets summary (count by type, no values exposed)

Mode: check

Targeted security check on specific files or directories.

1. Read the specified file(s)
2. Apply full SAST pattern matching (no triage/sampling — scan everything)
3. Run secrets detection on the path
4. Map findings to CWE/OWASP
5. Present findings with remediation

Mode: deps

Dependency lockfile analysis.

1. Detect lockfiles: package-lock.json, yarn.lock, pnpm-lock.yaml, requirements.txt, uv.lock, Cargo.lock, go.sum, Gemfile.lock, composer.lock
2. Run: uv run python skills/security-scanner/scripts/dependency-checker.py <path>
3. Parse output: dependency names, versions, ecosystem
4. Flag: outdated packages, packages with known CVE patterns, unusual version pinning
5. Present dependency health report

Mode: secrets

Secrets-only scan using regex patterns.

1. Run: uv run python skills/security-scanner/scripts/secrets-detector.py <path>
2. Parse JSON findings
3. Cross-reference with .gitignore — flag secrets in tracked files as CRITICAL
4. Check git history for previously committed secrets: git log --diff-filter=D -p -- <file>
5. Present findings grouped by secret type, never exposing actual values

Mode: compliance

Lightweight compliance heuristic scoring.

1. Validate <standard> is one of: soc2, gdpr, hipaa
2. Run: uv run python skills/security-scanner/scripts/compliance-scorer.py <path> --standard <standard>
3. Read reference checklist from references/compliance-checklists.md
4. Score each control as PASS/FAIL/PARTIAL with evidence
5. Present compliance scorecard with overall percentage and failing controls

Mode: report

Generate visual security dashboard.

1. Collect all findings from the current session (or re-run scan if none exist)
2. Format findings as JSON matching the dashboard schema
3. Convert to SARIF if requested: uv run python skills/security-scanner/scripts/sarif-formatter.py
4. Inject JSON into templates/dashboard.html
5. Copy to a temporary file, open in browser

Scaling Strategy

Scope	Strategy
1-10 files	Direct scan, no triage
11-100 files	Triage + prioritized scan
100-500 files	Triage + sampling (all HIGH, 50% MEDIUM, 10% LOW)
500+ files	Triage + sampling + parallel subagents by risk tier

Reference Files

Load ONE reference at a time. Do not preload all references into context.

File	Content	Read When
references/owasp-patterns.md	OWASP Top 10 with code patterns and detection heuristics	During SAST scan (Step 2)
references/cwe-patterns.md	Top 50 CWEs with detection patterns and remediation	During CWE mapping (Step 5)
references/secrets-guide.md	Secret patterns, false positive hints, triage guidance	During secrets scan
references/dependency-audit.md	Dependency audit protocol and CVE lookup workflow	During deps mode
references/compliance-checklists.md	SOC2/GDPR/HIPAA control checklists with scoring	During compliance mode
references/triage-protocol.md	Risk stratification methodology for security files	During triage (Step 1)
references/scope-boundary.md	Boundary with honest-review, pen testing, runtime monitoring	When scope is unclear

Script	When to Run
scripts/secrets-detector.py	Secrets scan — regex-based detection
scripts/dependency-checker.py	Dependency analysis — lockfile parsing
scripts/sarif-formatter.py	SARIF conversion — CI integration output
scripts/compliance-scorer.py	Compliance scoring — heuristic checklist

Template	When to Render
templates/dashboard.html	After scan — inject findings JSON into data tag

Critical Rules

1. Never expose actual secret values in output — show type, file, line only
2. Every finding must map to at least one CWE ID
3. Confidence < 0.3 = discard; 0.3-0.7 = flag as potential; >= 0.7 = report
4. Run secrets-detector.py before reporting — regex patterns catch what LLM scanning misses
5. Do not report phantom vulnerabilities requiring impossible conditions
6. For 100+ files, always triage before scanning — never brute-force the full codebase
7. Dependency findings require version evidence — never flag without checking the actual version
8. Compliance mode is heuristic only — state this explicitly in output, never claim certification
9. Present findings before suggesting fixes — always use an approval gate
10. Cross-reference with .gitignore — secrets in untracked files are INFO, in tracked files are CRITICAL
11. Load ONE reference file at a time — do not preload all references into context
12. This skill is for pre-deployment audit only — redirect to honest-review for code review, refuse pen testing requests
13. SARIF output must conform to SARIF v2.1 schema — validate with sarif-formatter.py
14. Never modify source files — this skill is read-only analysis