semgrep

intent

scan a codebase for security vulnerabilities using semgrep's parallel static analysis engine. use this skill when you need to audit code before review, find known bug patterns, or run first-pass security analysis. the skill auto-detects languages, spawns parallel scanners for each, and merges results into a single SARIF file. it includes third-party rulesets from trail of bits, 0xdea, and decurity alongside official semgrep rules to catch vulnerabilities missing from the default registry. supports two modes: "run all" for complete coverage or "important only" for high-confidence findings filtered by severity. requires explicit user approval of the scan plan before execution.

inputs

semgrep installation: semgrep cli binary must be available in PATH. install via pip install semgrep or download from https://semgrep.dev/install

semgrep pro license (optional): set SEMGREP_APP_TOKEN environment variable to enable cross-file taint tracking and pro rules. without it, scanning falls back to oss mode with per-file analysis. pro mode catches roughly 2.5x more true positives via inter-file data flow.

target directory: filesystem path to the codebase to scan. must be readable by the current user.

scan mode selection: user chooses "run all" (complete ruleset, slower, comprehensive) or "important only" (filtered high-confidence vulnerabilities, faster).

ruleset approval: user must explicitly approve the exact rulesets, target directory, detected languages, and engine mode before scanning begins.

procedure

1. gather codebase metadata

   • input: target directory path
   • walk the directory tree and identify all file extensions present
   • output: list of detected file types (e.g., .py, .js, .go, .java)

2. map languages to semgrep rulesets

   • input: detected file types from step 1
   • for each language, enumerate official semgrep rules plus third-party rules (trail of bits, 0xdea, decurity)
   • output: map of language -> available rulesets with source (official, trail of bits, etc.)

3. present scan plan for user approval

   • input: target directory, detected languages, available rulesets, scan mode choice
   • format: "i will scan [TARGET] with [LANGUAGE] rules from [RULESETS] in [MODE] mode. approve to proceed."
   • output: explicit user approval (yes/proceed) or rejection
   • this step is a hard gate; do not proceed without explicit approval

4. check for semgrep pro availability

   • input: SEMGREP_APP_TOKEN environment variable (if set)
   • attempt login: semgrep login --token $SEMGREP_APP_TOKEN --metrics=off (optional, only if token present)
   • output: pro mode enabled (true/false), taint tracking capability (true/false)

5. spawn parallel scan tasks

   • input: approved scan plan from step 3, pro availability from step 4, target directory, rulesets
   • for each detected language, emit one task that runs: semgrep scan [TARGET] --config=[RULESET_CONFIG] --json --metrics=off [--pro-enabled flag if pro available]
   • emit all scan tasks in a single message (do not spawn sequentially)
   • output: task handles for all parallel scanners

6. collect and merge SARIF results

   • input: json output from all parallel scan tasks
   • convert each json result to sarif format (semgrep supports --sarif output flag)
   • merge all sarif files into a single output file: merged_semgrep_results.sarif
   • output: merged sarif file at project root, severity counts, category breakdown

7. generate summary report

   • input: merged sarif file from step 6
   • count findings by severity (critical, high, medium, low, info)
   • count findings by category (injection, xss, sql-injection, hardcoded-secret, etc.)
   • output: plaintext summary: "found X critical, Y high, Z medium findings across N rules"

decision points

if semgrep pro token is set: enable pro mode in step 4, pass --pro-enabled flag to all scan commands in step 5, and use cross-file taint tracking rulesets for applicable languages (python, javascript, java, go). this catches inter-file data flow vulnerabilities.

else (no pro token): scan in oss mode, use per-file analysis only, skip cross-file taint rules. results will be less comprehensive but still valuable for first-pass audits.

if user rejects scan plan in step 3: stop. do not spawn any scanners. ask user to clarify target, language filter, or ruleset preference and re-present a revised plan.

if detected languages are empty or no files found: report to user and exit. do not spawn scanners or generate empty results.

if scan mode is "run all": include all available rulesets for each language (official + third-party).

if scan mode is "important only": filter rulesets to high-confidence rules only. exclude informational-level checks and low-impact patterns.

if a parallel scan task fails or times out (>600 seconds): log the failure, continue processing other tasks, and include a warning in the final report. do not fail the entire skill for a single language's timeout.

if semgrep cli is not installed: return error: "semgrep not found. install via 'pip install semgrep' or https://semgrep.dev/install". do not attempt to install automatically.

if the target directory does not exist or is not readable: return error with the specific path and permission issue. do not proceed to scanning.

if sarif merge encounters conflicting rule ids across rulesets: deduplicate by rule id + source + severity. include all instances if they differ.

output contract

merged sarif file: merged_semgrep_results.sarif in the current working directory. valid json, conforms to sarif 2.1 spec. includes all findings from all languages and rulesets, annotated with severity, rule id, source (official/trail of bits/0xdea/decurity), and file/line/column locations.

summary report: plaintext output listing finding counts by severity and top categories. example: "scan complete. found 3 critical, 12 high, 41 medium, 89 low findings across 127 rules from 4 rulesets (official, trail of bits, 0xdea, decurity) in 45 seconds."

task logs: all parallel scan task output (semgrep json per language) available for inspection. failures logged with language name and error message.

no data leakage: all semgrep commands include --metrics=off to disable telemetry. no data sent to semgrep cloud or third parties without explicit pro token auth.

outcome signal

user receives the merged sarif file and can open it in compatible tools (github code scanning, vs code semgrep extension, defect dojo, etc.). summary report displays finding counts by severity and the top vulnerable patterns detected. if "run all" mode was used, report includes all rulesets applied and execution time for each language. if pro mode was enabled, report explicitly states "cross-file taint tracking enabled" and lists pro-only rules that contributed findings. user can inspect the sarif file directly to see rule names, severity, and code locations. if no findings were detected, report states "no vulnerabilities found" and lists the rulesets that were applied (confirming coverage, not a missed scan).

---