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.