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, maintaining a custom regex-based CWE-22 detector created false positives (seven suppression annotations were added 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 flag it to the owner. Do not add a regex-based CWE-22 check to this scanner.
Triggers
| Trigger Phrase | Operation |
|---|---|
scan for vulnerabilities |
scan_vulnerabilities.py on staged/specified files (CWE-78 only) |
check for command injection |
scan_vulnerabilities.py with CWE-78 focus |
check for path traversal |
NOT handled by this scanner. CWE-22 detection is delegated to CodeQL (see the CodeQL Analysis workflow, which runs python-security-extended.qls). |
pre-PR security scan |
scan_vulnerabilities.py on staged files |
run security scan |
scan_vulnerabilities.py with full scan |
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
| Input | Output | Performance |
|---|---|---|
| Staged files | JSON findings + console summary | 2-5s |
| Specific files | JSON findings + console summary | 1-3s |
| Directory scan | JSON findings + console summary | 5-15s |
Scripts
| Script | Purpose | Exit codes |
|---|---|---|
scripts/scan_vulnerabilities.py |
CWE-78 (command injection) regex scanner over staged, specified, or --directory files; supports --format json. CWE-22 is delegated to CodeQL; see Scope. |
0 no vulnerabilities, or nothing assessed (files_scanned: 0); 1 scan error (file not found, etc.); 2 invalid arguments; 3 git enumeration failure; 10 vulnerabilities detected. |
scan_constants.py, scan_patterns.py, scan_bash_lexer.py, scan_bash_heredoc.py, and scan_format.py are helper modules imported by the scanner, not standalone CLIs.
Usage
Basic Scan (Staged Files)
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/security-scan/scripts/scan_vulnerabilities.py" --git-staged
Scan Specific Files
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/security-scan/scripts/scan_vulnerabilities.py" path/to/file.py another/script.ps1
Scan Directory
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/security-scan/scripts/scan_vulnerabilities.py" --directory src/
JSON Output (CI Integration)
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/security-scan/scripts/scan_vulnerabilities.py" --git-staged --format json
Specific CWE Focus
# Command injection only (the only CWE this scanner detects)
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/security-scan/scripts/scan_vulnerabilities.py" --cwe 78 --git-staged
--cwe 22 is accepted for backward compatibility but produces no findings. In console mode, the scanner emits a stderr warning pointing at CodeQL when invoked with --cwe 22. In JSON mode, summary.delegated_cwes carries that fact and stderr stays empty. 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.
files_scanned: 0 means the scanner assessed nothing: nothing was staged, or no staged or named file was a supported language. It is zero coverage, not a clean result, even though the exit code is 0. A --directory scan that finds no supported files, or a call with no target, is a usage error: exit 1, with the message in errors.
With --format json, stdout carries exactly one JSON envelope on every exit, and stderr stays empty. This covers argument errors, failed path checks, git failures, unexpected exceptions, and --help, which adds a help field. The envelope's exit_code always matches the process exit code. --output writes the same envelope to a file and stdout still prints it. A rejected --output path is never written.
Exit Codes
| Code | Meaning | CI Behavior |
|---|---|---|
| 0 | No vulnerabilities found, or nothing assessed (files_scanned: 0 in JSON) |
Pass; check files_scanned to tell the two apart |
| 1 | Scan error (file not found, etc.) | Fail |
| 2 | Invalid command-line arguments | Fail |
| 3 | Git could not enumerate staged files | Fail |
| 10 | Vulnerabilities detected | Fail |
Detected Patterns
CWE-78: Command Injection
| Language | Pattern | Risk |
|---|---|---|
| Python | Subprocess with string formatting and user data | CRITICAL |
| Python | Shell command execution with concatenated input | CRITICAL |
| Python | Subprocess with shell=True and user data | HIGH |
| PowerShell | Invoke-Expression with variable interpolation | CRITICAL |
| PowerShell | Dynamic command execution with unvalidated input | HIGH |
| PowerShell | Start-Process with unvalidated arguments | HIGH |
| Bash | eval with user input | CRITICAL |
| Bash | Command substitution with user data | CRITICAL |
| Bash | Unquoted variables in commands | MEDIUM |
| C# | Process.Start with dynamic command | HIGH |
| C# | String interpolation in process arguments | HIGH |
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
Bash Here-Documents: Quote the Delimiter
An unquoted delimiter (<<EOF) makes the shell expand the body, so the scanner flags each $var there as an unquoted expansion. This includes plain help text such as Usage: $0 --dest $target. Quote the delimiter (<<'EOF', <<"EOF", or <<\EOF) and the body is not expanded. The scanner then blanks it only when every command that reads the body is a known print or filter command such as cat, echo, printf, tee, read, grep, sed, awk, or jq. Any other reader (a shell, ssh, sudo, psql, or a pipe into one, as in cat <<'EOF' | sh) may run the body, so it is still scanned.
cat <<'EOF'
Usage: $prog --dest <dir>
EOF
If the body must expand, quote each expansion ("$target") or add a justified suppression.
This is a deliberate limit, not a pending fix (owner decisions D17 and D23). A per-line scanner cannot prove an unquoted body is never fed to a shell or a file that later runs. Four review rounds on a narrowing that cleared "print-only" bodies kept finding bypasses: a body read into a variable that is later run (read, mapfile -C eval), >&1word file redirects, a } argument closing a group early, a line continuation into the opener, a quoted or split exec >file, case, #, or ${ inside a body $( ), array subscripts (${a[$i]}), and a redefined cat.
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:
- security-detection: Identify if security-relevant files changed
- security-scan: Scan code content for CWE patterns (THIS SKILL)
- codeql-scan: Full SAST analysis (if security-scan finds issues or high-risk files)
- 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
| Avoid | Why | Instead |
|---|---|---|
| Skipping scan before PR | Vulnerabilities caught in review waste cycles | Run scan before every PR submission |
| Ignoring MEDIUM severity | Can escalate to exploitable | Review all findings, document accepted risks |
| Only scanning changed files | Misses vulnerabilities in dependencies | Periodic full directory scans |
| Suppressing without documentation | Loses context for future audits | Document suppressions in code comments |
| Using this instead of codeql-scan for SAST | Pattern matching misses data flow issues | Use both: this for quick feedback, CodeQL for deep analysis |
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
| Skill | Relationship |
|---|---|
security-detection |
Detects which files need review (path-based routing) |
codeql-scan |
Full SAST analysis (heavyweight, CI-focused) |
threat-modeling |
Design-level STRIDE analysis |
analyze |
General code analysis with security focus option |
Reference Files
Load a file only when its condition holds. The scanner runs without any of them.
| File | Read when |
|---|---|
references/vulnerability-patterns.md |
A finding needs remediation detail or a false-positive call for CWE-78, or you review CWE-22 by hand in PowerShell, Bash, or C# (CodeQL does not cover those) |
references/powershell-security-checklist.md |
The diff adds or changes a .ps1 or .psm1 file and you review it beyond the scanner's CWE-78 patterns |
references/agent-guardrails-template.md |
The diff adds or changes an agent prompt, a SKILL.md or its scripts, or a lifecycle hook |
references/agent-memory-inference-leakage.md |
The diff touches a memory write path: a call that saves agent memory, a reflection script, or a prompt that lets an agent record observations |
references/autonomous-execution-guardrails.md |
You work unsupervised and are about to merge, or you are about to dismiss a security review comment as "won't fix" |
references/dependency-risk-scoring.md |
The diff adds an external package or changes its version |
references/security-cwe-catalog.md |
For the security agent: you scan for CWEs and need a name or description |
references/security-impact-analysis.md |
For the security agent: milestone-planner asks for a security impact analysis |
references/security-piv-ci-checks.md |
For the security agent: you write the CI check request in Post-Implementation Verification |
references/threat-model-template.md is the short template the security agent uses
for its TM-NNN reports; the scanner does not read it. For a full STRIDE workflow use
the template the threat-modeling skill ships under templates/.
References
- CWE-78: OS Command Injection
- CWE-22: Path Traversal (delegated to CodeQL; see Scope above)
- OWASP Command Injection
- Path Traversal Research (2025)
- Analysis:
.project-toolkit/analysis/closed-pr-reviewer-patterns-2026-02-08.md
Extension Points
| Extension | How to Add |
|---|---|
| New CWE-78 patterns | Add to CWE78_PATTERNS dict in scan_vulnerabilities.py |
| New CWE class detection | Do NOT add to this scanner. Configure CodeQL queries in .github/codeql/codeql-config.yml instead. The buy-vs-build analysis established that CWE detection beyond CWE-78's narrow regex shapes belongs in CodeQL. |
| New language support | Add language detection and patterns |
| Custom severity rules | Modify severity calculation logic |
| Integration with other tools | Add output format adapters |