AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

semgrep

Runs a Semgrep security scan over a codebase: detects languages, selects rulesets, presents the plan for explicit approval, then runs every approved ruleset through scripts/run-scans.sh, which batches the semgrep processes and writes scans.json, and merges the output to SARIF. Supports two scan modes, "run all" for full ruleset coverage and "important only" for security findings at medium-to-high confidence and impact. Uses Semgrep Pro for cross-file taint analysis when it is available. Use when asked to scan code for vulnerabilities, run a security audit with Semgrep, find bugs, or perform static analysis. For the same scan without the approval gate, use the /static-analysis:semgrep-scan workflow.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--semgrep at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/scan-modes.md

Scan Modes Reference

Mode: Run All

Full scan with all rulesets and severity levels. Current default behavior. No filtering applied — all findings are reported and triaged.

Mode: Important Only

Focused on high-confidence security vulnerabilities. Excludes code quality, best practices, and low-confidence audit findings.

Pre-Filter: CLI Severity Flag

Add these flags to every semgrep command:

--severity WARNING --severity ERROR

This excludes INFO findings at scan time, reducing output volume before post-filtering.

--severity takes INFO, WARNING, or ERROR, and nothing else. Anything else exits 2 before scanning, with no output written. The LOW/MEDIUM/HIGH/CRITICAL scale in the table below belongs to the rule metadata, which the post-filter reads. The two are not interchangeable.

The two scales do not nest. A registry rule can carry CLI severity INFO and metadata impact: HIGH, and this flag drops it at scan time before the post-filter sees it. The volume reduction is why the pre-filter runs at scan time, but it makes important-only "WARNING and above, then filtered on metadata" rather than "everything the metadata filter would keep". Check a missing finding against a run-all scan before concluding the rule did not fire.

Post-Filter: Metadata Criteria

After scanning, filter each JSON result file to keep only findings matching ALL of:

| Metadata Field | Accepted Values | Rationale | |---|---|---| | extra.metadata.category | "security" | Excludes correctness, best-practice, maintainability, performance | | extra.metadata.confidence | "MEDIUM", "HIGH" | Excludes low-precision rules (high false positive rate) | | extra.metadata.impact | "MEDIUM", "HIGH" | Excludes low-impact informational findings |

Third-party rules (Trail of Bits, 0xdea, Decurity, etc.) may not have confidence/impact/category metadata. Findings without these metadata fields are kept by the post-filter — we cannot filter what is not annotated, and third-party rules are typically security-focused.

This exemption applies only to findings that reach the post-filter. The pre-filter above runs first and on every command, including the cross-language unit that carries the cloned third-party repos, so an unannotated rule with CLI severity: INFO is dropped at scan time and never becomes a finding the exemption can keep. A third-party rule is exempt from the metadata filter, not from --severity.

Semgrep Metadata Background

Semgrep security rules have these metadata fields (required for category: security in the official registry):

| Field | Purpose | Metadata values (never CLI --severity values) | |---|---|---| | severity (top-level) | Overall rule severity, derived from likelihood × impact | LOW, MEDIUM, HIGH, CRITICAL | | category | Rule category | security, correctness, best-practice, maintainability, performance | | confidence | True positive rate of the rule (precision) | LOW, MEDIUM, HIGH | | impact | Potential damage if vulnerability is exploited | LOW, MEDIUM, HIGH | | likelihood | How likely the vulnerability is exploitable | LOW, MEDIUM, HIGH | | subcategory | Finding type | vuln, audit, secure default |

Key relationship: severity = f(likelihood, impact) while confidence is independent (describes rule quality, not vulnerability severity).

Post-Filter jq Command

Apply to each JSON result file after scanning:

# Filter a single result file
jq '{
  results: [.results[] |
    ((.extra.metadata.category // "security") | ascii_downcase) as $cat |
    ((.extra.metadata.confidence // "HIGH") | ascii_upcase) as $conf |
    ((.extra.metadata.impact // "HIGH") | ascii_upcase) as $imp |
    select(
      ($cat == "security") and
      ($conf == "MEDIUM" or $conf == "HIGH") and
      ($imp == "MEDIUM" or $imp == "HIGH")
    )
  ],
  errors: .errors,
  paths: .paths
}' "$f" > "${f%.json}-important.json"

Default values (// "security", // "HIGH") handle third-party rules without metadata — they pass all filters by default.

Filter All Result Files in a Directory

Raw scan output lives in $OUTPUT_DIR/raw/. The filter creates *-important.json files alongside the originals — the raw files are preserved unmodified.

# Apply important-only filter to all scan result JSON files in raw/
filter_failed=0
for f in "$OUTPUT_DIR/raw"/*-*.json; do
  [[ "$f" == *-triage.json || "$f" == *-important.json ]] && continue
  out="${f%.json}-important.json"
  # The redirect creates $out before jq runs, so a jq failure leaves a zero-byte file sitting
  # there. merge_sarif.py --important reads that as a corrupt filter and aborts the whole
  # merge, losing every other scan's findings to one bad file. Delete it and name the file.
  if ! jq '{
    results: [.results[] |
      ((.extra.metadata.category // "security") | ascii_downcase) as $cat |
      ((.extra.metadata.confidence // "HIGH") | ascii_upcase) as $conf |
      ((.extra.metadata.impact // "HIGH") | ascii_upcase) as $imp |
      select(
        ($cat == "security") and
        ($conf == "MEDIUM" or $conf == "HIGH") and
        ($imp == "MEDIUM" or $imp == "HIGH")
      )
    ],
    errors: .errors,
    paths: .paths
  }' "$f" >"$out"; then
    rm -f "$out"
    filter_failed=$((filter_failed + 1))
    echo "post-filter failed on $f" >&2
    continue
  fi
  BEFORE=$(jq '.results | length' "$f")
  AFTER=$(jq '.results | length' "$out")
  echo "$f: $BEFORE → $AFTER findings (filtered $(( BEFORE - AFTER )))"
done
[ "$filter_failed" -eq 0 ] ||
  echo "$filter_failed file(s) failed to filter; fix them before merging" >&2

The Filter Does Not Apply to SARIF

Both filters above are written for semgrep's JSON shape and cannot be pointed at a .sarif file. SARIF has no top-level .results and no extra.metadata — category, confidence and impact are simply not in the format — so the filter exits with Cannot iterate over null, and redirecting it over its own input truncates the file first.

The merged SARIF is filtered by scripts/merge_sarif.py --important instead, which keeps the findings these filters kept by matching (check_id, path, start.line) against SARIF's (ruleId, uri, region.startLine). Run the JSON filter over every file in raw/ first: the merge fails rather than filtering if any scan has no *-important.json beside it, since a partial key set would drop real findings from the primary deliverable with nothing downstream to notice.

Scanner Command Modifications

scripts/run-scans.sh puts these on every command it generates; they are not yours to add.

  • Run all: no severity flags
  • Important only: --severity WARNING --severity ERROR
  • Both: --max-target-bytes 20000000 (see below)

That pre-filter is applied by semgrep at scan time, before the metadata post-filter above. A rule shipping with CLI severity INFO is dropped by the flag and never reaches the filter that would have kept it.

File Size Limit

semgrep skips any file larger than --max-target-bytes and says nothing about it in --json output: no paths.skipped entry, no error, and the file is absent from paths.scanned. A 1 MB bundle therefore reports findings: 0 exactly as a file that was opened and found clean does. The reason is only reachable through --verbose, which the scanner does not use.

run-scans.sh sets the limit explicitly at 20,000,000 bytes rather than leaning on semgrep's 1,000,000-byte default, which generated sources, single-file bundles and legacy monoliths pass routinely. Override it with --max-target-bytes N when a target holds larger sources, or with --max-target-bytes 0 to lift the limit entirely, which is what semgrep does with a zero. The effective value is recorded as maxTargetBytes in scans.json. Bytes only: semgrep also accepts 1.5MB, and the scanner refuses that form rather than parsing the size a second way to build the report below.

Files an --include glob selected that are still over the limit are listed as oversized in scans.json, and they belong in the report: a scan that did not open a file has not cleared it. Report them as a coverage gap, not as a clean result. Raising the limit re-scans them at the cost of memory and time, so a deliberate decision to leave one out is fine as long as it is written down.

Cross-language rulesets (p/security-audit, p/secrets, third-party repos) take no --include, and semgrep alone decides which files it can parse, so oversized cannot enumerate their share of the gap. maxTargetBytes is in the report so that part can be checked by hand.