Semgrep Security Scan

Run a Semgrep scan with automatic language detection, parallel execution via subagents when the host supports delegation (otherwise scan sequentially), and merged SARIF output.

Essential Principles

1. Always use --metrics=off — Semgrep sends telemetry by default; --config auto also phones home. Every semgrep command must include --metrics=off to prevent data leakage during security audits.
2. User must approve the scan plan (Step 3 is a hard gate) — The original "scan this codebase" request is NOT approval. Present exact rulesets, target, engine, and mode; wait for explicit "yes"/"proceed" before spawning scanners.
3. Third-party rulesets are required, not optional — Trail of Bits, 0xdea, and Decurity rules catch vulnerabilities absent from the official registry. Include them whenever the detected language matches.
4. Launch all scans concurrently when the host supports subagent delegation — parallel execution per language/category is the core performance advantage. If the host has no subagent/parallel-task mechanism, run the scans sequentially instead of one Task at a time.
5. Always check for Semgrep Pro before scanning — Pro enables cross-file taint tracking and catches ~250% more true positives. Skipping the check means silently missing critical inter-file vulnerabilities.

When to Use

• Security audit of a codebase
• Finding vulnerabilities before code review
• Scanning for known bug patterns
• First-pass static analysis

When NOT to Use

• Binary analysis → Use binary analysis tools
• Already have Semgrep CI configured → Use existing pipeline
• Need cross-file analysis but no Pro license → Consider CodeQL as alternative
• Creating custom Semgrep rules → Use semgrep-rule-creator skill
• Porting existing rules to other languages → Use semgrep-rule-variant-creator skill

Output Directory

All scan results, SARIF files, and temporary data are stored in a single output directory.

• If the user specifies an output directory in their prompt, use it as OUTPUT_DIR.
• If not specified, default to ./static_analysis_semgrep_1. If that already exists, increment to _2, _3, etc.

In both cases, always create the directory with mkdir -p before writing any files.

# Resolve output directory
if [ -n "$USER_SPECIFIED_DIR" ]; then
  OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
  BASE="static_analysis_semgrep"
  N=1
  while [ -e "${BASE}_${N}" ]; do
    N=$((N + 1))
  done
  OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR/raw" "$OUTPUT_DIR/results"

The output directory is resolved once at the start of Step 1 and used throughout all subsequent steps.

$OUTPUT_DIR/
├── rulesets.txt                 # Approved rulesets (logged after Step 3)
├── raw/                         # Per-scan raw output (unfiltered)
│   ├── python-python.json
│   ├── python-python.sarif
│   ├── python-django.json
│   ├── python-django.sarif
│   └── ...
└── results/                     # Final merged output
    └── results.sarif

Prerequisites

Required: Semgrep CLI (semgrep --version). If not installed, see Semgrep installation docs.

Optional: Semgrep Pro — enables cross-file taint tracking, inter-procedural analysis, and additional languages (Apex, C#, Elixir). Check with:

semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro available" || echo "OSS only"

Limitations: OSS mode cannot track data flow across files. Pro mode uses -j 1 for cross-file analysis (slower per ruleset, but parallel rulesets compensate).

Scan Modes

Select mode in Step 2 of the workflow. Mode affects both scanner flags and post-processing.

Important only applies two filter layers:

1. Pre-filter: --severity MEDIUM --severity HIGH --severity CRITICAL (CLI flag)
2. Post-filter: JSON metadata — keeps only category=security, confidence∈{MEDIUM,HIGH}, impact∈{MEDIUM,HIGH}

See scan-modes.md for metadata criteria and jq filter commands.

Orchestration Architecture

┌──────────────────────────────────────────────────────────────────┐
│ MAIN AGENT (this skill)                                          │
│ Step 1: Detect languages + check Pro availability                │
│ Step 2: Select scan mode + rulesets (ref: rulesets.md)           │
│ Step 3: Present plan + rulesets, get approval [⛔ HARD GATE]     │
│ Step 4: Run one scan per language/category (parallel if the      │
│         host supports subagent delegation, else sequential)      │
│ Step 5: Merge results and report                                 │
└──────────────────────────────────────────────────────────────────┘
         │ Step 4
         ▼
┌─────────────────┐
│ Per-language    │
│ scan            │
├─────────────────┤
│ Python scanner  │
│ JS/TS scanner   │
│ Go scanner      │
│ Docker scanner  │
└─────────────────┘

Workflow

Follow the detailed workflow in scan-workflow.md. Summary:

Enforcement: Track the 5 steps as a dependency chain (each blocks the next), using the host's task-tracking tool if one is available. Step 3 is a HARD GATE — do not proceed to Step 4 until the user has explicitly approved the plan.

Merge command (Step 5):

uv run scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif

Rationalizations to Reject

Reference Index

Success Criteria

• Output directory resolved (user-specified or auto-incremented default)
• All generated files stored inside $OUTPUT_DIR
• Languages detected with file counts; Pro status checked
• Scan mode selected by user (run all / important only)
• Rulesets include third-party rules for all detected languages
• User explicitly approved the scan plan (Step 3 gate passed)
• All per-language scans launched concurrently (or sequentially if the host has no delegation) and completed
• Every semgrep command used --metrics=off
• Approved rulesets logged to $OUTPUT_DIR/rulesets.txt
• Raw per-scan outputs stored in $OUTPUT_DIR/raw/
• results.sarif exists in $OUTPUT_DIR/results/ and is valid JSON
• Important-only mode: post-filter applied before merge; unfiltered results preserved in raw/
• Results summary reported with severity and category breakdown
• Cloned repos (if any) cleaned up from $OUTPUT_DIR/repos/