/semgrep

name: semgrep
description: "Run Semgrep static analysis across a codebase, optionally using Semgrep Pro for cross-file taint analysis. Use when Semgrep or a static-analysis scan is requested; use security-review for a manual audit."
license: MIT (modified; see UPSTREAMS.json)

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](https://semgrep.dev/docs/getting-started/).

**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.

| Mode | Coverage | Findings Reported | |------|----------|-------------------| | **Run all** | All rulesets, all severity levels | Everything | | **Important only** | All rulesets, pre- and post-filtered | Security vulns only, medium-high confidence/impact |

**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](references/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](workflows/scan-workflow.md).** Summary:

| Step | Action | Gate | Key Reference | |------|--------|------|---------------| | 1 | Resolve output dir, detect languages + Pro availability | — | Use Glob, not Bash | | 2 | Select scan mode + rulesets | — | [rulesets.md](references/rulesets.md) | | 3 | Present plan, get explicit approval | ⛔ HARD | Ask the user directly, or via the host's structured question tool if it has one