Security Scan

Security Scan

Proactive vulnerability detection for command injection (CWE-78) before PR submission.

Scope

This skill detects CWE-78 (command injection) patterns only. The regex patterns target unambiguous shapes (subprocess.run(..., shell=True), eval(user_input), backtick command substitution, etc.) that produce reliable signal without taint analysis.

CWE-22 (path traversal) is delegated to CodeQL. The CodeQL workflow runs python-security-extended.qls and actions-security-extended.qls on every PR, authoritatively detecting CWE-22 across Python and GitHub Actions code (the two languages CodeQL supports for this repo per codeql-config.yml). PowerShell, Bash, and C# are NOT covered by CodeQL; for those languages, CWE-22 detection relies on code review and any future static analyzer adoption. Per the buy-vs-build framework analysis (issue #1843), maintaining a custom regex-based CWE-22 detector created false positives (PR #1841 added seven suppression annotations to silence them) without comparable coverage of real CWE-22 vectors that CodeQL catches in CI. Path-traversal checking is Context (table stakes security, not a competitive differentiator); CodeQL is the right tool for the languages it supports.

If a CWE-22 finding surfaces in CI from CodeQL, fix the underlying code or open an issue to triage. Do not add a regex-based CWE-22 check to this scanner.

Triggers

When to Use

Use this skill when:

• Preparing code for PR submission (catch issues before review)
• Working with file path handling (user input to file operations)
• Building shell commands dynamically
• Integrating pre-commit security gates

Use security-detection instead when:

• Determining if a file needs security review (path-based routing)
• Triggering security agent involvement based on file types

Use codeql-scan instead when:

• Running comprehensive SAST analysis (30-60s full scan)
• Need deep data flow analysis beyond pattern matching
• CI pipeline integration requiring SARIF output

Use threat-modeling instead when:

• Performing design-level security analysis
• Creating STRIDE threat matrices
• Strategic security architecture review

Quick Reference

Scripts

scan_constants.py, scan_patterns.py, and scan_format.py are helper modules imported by the scanner, not standalone CLIs.

Usage

Basic Scan (Staged Files)

python .claude/skills/security-scan/scripts/scan_vulnerabilities.py --git-staged

Scan Specific Files

python .claude/skills/security-scan/scripts/scan_vulnerabilities.py path/to/file.py another/script.ps1

Scan Directory

python .claude/skills/security-scan/scripts/scan_vulnerabilities.py --directory src/

JSON Output (CI Integration)

python .claude/skills/security-scan/scripts/scan_vulnerabilities.py --git-staged --format json

Specific CWE Focus

# Command injection only (the only CWE this scanner detects)
python .claude/skills/security-scan/scripts/scan_vulnerabilities.py --cwe 78 --git-staged

--cwe 22 is accepted for backward compatibility but produces no findings. The scanner emits a stderr warning pointing at CodeQL when invoked with --cwe 22. To check for path traversal, rely on the CodeQL workflow at .github/workflows/codeql-analysis.yml.

Output

Console Output (Default)

When vulnerabilities are detected, the scanner outputs findings with file location, pattern matched, and severity. Each finding includes the specific code line and a recommendation for remediation.

JSON Output (CI Mode)

Machine-readable JSON format including scan timestamp, files scanned, vulnerability details (CWE, file, line, code, severity, recommendation), and summary statistics.

Exit Codes

Detected Patterns

CWE-78: Command Injection

Detection Heuristics:

• String interpolation/concatenation in command construction
• shell=True in subprocess calls
• Unquoted variable expansion in shell scripts
• Dynamic command building from external input

Integration

Pre-commit Hook

Add a named validator job to lefthook.yml to run the security scan before commits in blocking mode.

CI Integration

Add a workflow step to run the scanner with JSON output and upload results as artifacts.

Workflow Integration

Recommended workflow order:

1. security-detection: Identify if security-relevant files changed
2. security-scan: Scan code content for CWE patterns (THIS SKILL)
3. codeql-scan: Full SAST analysis (if security-scan finds issues or high-risk files)
4. security agent: Deep review of flagged vulnerabilities

Process

                        Security Scan Workflow
                        ======================

     ┌─────────────────┐
     │  Collect Files  │ <- --git-staged, --directory, or explicit paths
     └────────┬────────┘
              │
              ▼
     ┌─────────────────┐
     │ Detect Language │ <- .py, .ps1, .sh, .cs, .bash
     └────────┬────────┘
              │
              ▼
     ┌─────────────────┐
     │ Apply CWE-78    │ <- Command injection patterns by language
     │ Patterns        │
     └────────┬────────┘
              │
              ▼
     ┌─────────────────┐
     │ Aggregate       │ <- Deduplicate, sort by severity
     │ Findings        │
     └────────┬────────┘
              │
              ▼
     ┌─────────────────┐
     │ Output Results  │ <- Console or JSON format
     └─────────────────┘

Anti-Patterns

Suppression

To suppress false positives, add inline comments with justification:

# security-scan: ignore CWE-78 - command validated by allow_list at line N

Suppressions are tracked in scan output for audit purposes. The mechanism only applies to CWE classes this scanner detects (CWE-78). For CWE-22, suppress at the CodeQL level using lgtm or codeql[suppress] comments (see CodeQL docs).

Verification

After running security scan:

• All HIGH/CRITICAL CWE-78 findings addressed or documented
• No command injection patterns with dynamic input
• Variables quoted in shell scripts
• Input validation present before command operations
• Suppressions documented with justification
• CWE-22 path-traversal coverage verified separately via CodeQL CI run

Related Skills

References

• CWE-78: OS Command Injection
• CWE-22: Path Traversal (delegated to CodeQL; see Scope above)
• OWASP Command Injection
• Path Traversal Research (2025)
• Analysis: .agents/analysis/closed-pr-reviewer-patterns-2026-02-08.md

Extension Points