English for Semgrep Developers

Semgrep lets teams write pattern-based static analysis rules that look like the code they’re matching, which lowers the barrier to writing custom checks but introduces its own vocabulary — “rule,” “pattern,” “metavariable,” “finding,” “suppress” — that a security-minded conversation depends on getting right. A team that conflates “false positive” with “suppressed” ends up either drowning in noise or silently hiding real issues. This guide covers the English used when discussing Semgrep with a team.

Key Vocabulary

Rule — a single Semgrep check defined by a pattern and metadata (severity, message, language), the basic unit that either matches code or doesn’t. “This rule is too broad — it’s matching every call to exec, even the ones with a hardcoded, safe argument. Let’s narrow the pattern.”

Metavariable — a placeholder (like $X or $FUNC) in a Semgrep pattern that captures any matching code fragment, letting one rule match many concrete variations of the same shape. “Use a metavariable for the function name here — $FUNC(...) will catch this pattern regardless of which specific function is being called.”

Finding — a single match Semgrep reports for a rule against a piece of code, which still needs human triage before being treated as a confirmed issue. “We have forty findings from this new rule, but most look like the same pattern repeated — let’s group them before triaging one by one.”

False positive (vs. suppression) — a finding that isn’t actually a security or quality problem despite matching the rule, distinct from a suppression, which is a deliberate, tracked decision to ignore a real (or accepted) finding. “Don’t just add a suppression comment and move on — first confirm whether this is genuinely a false positive or a real issue we’re consciously accepting.”

Rule tuning (reducing noise) — refining a rule’s pattern or adding exclusions so it stops firing on cases the team has decided aren’t worth flagging, without weakening its ability to catch real issues. “Instead of suppressing every individual finding from this rule, let’s tune the rule itself to exclude test files — that fixes the noise at the source.”

Common Phrases

• “Is this a genuine false positive, or is it a real finding we’re choosing to suppress?”
• “Can we narrow this pattern with a metavariable instead of writing three near-duplicate rules?”
• “Should we tune the rule to reduce noise, or suppress individual findings one at a time?”
• “How many findings is this rule generating, and are they mostly the same underlying pattern?”
• “Is this suppression tracked somewhere, or is it just a silent comment nobody will revisit?”

Example Sentences

Reviewing a pull request: “This adds a suppression comment without an explanation — add a short note on why it’s safe here, so the next person doesn’t have to re-investigate from scratch.”

Explaining a design decision: “We wrote a custom rule with a metavariable for the internal ORM’s query method, since the generic SQL-injection rule wasn’t matching our specific wrapper function.”

Describing an incident: “The vulnerable pattern shipped because the relevant rule had been over-tuned to exclude an entire directory, which also happened to include the file where the real issue was introduced.”

Professional Tips

• Say “finding” rather than “error” or “bug” when discussing Semgrep output — a finding needs triage, and calling it a bug prematurely skips that step.
• Distinguish “false positive” from “suppression” explicitly in every triage conversation — conflating them either hides real issues or floods the team with unnecessary noise.
• Use “metavariable” correctly when discussing rule patterns — it signals you understand how to generalize a rule instead of writing near-duplicates for every variation.
• Propose “tuning the rule” as an alternative to mass-suppressing findings — it fixes noise at the source rather than scattering exceptions across the codebase.

Practice Exercise

1. Explain in two sentences the difference between a false positive and a suppression.
2. Write a one-sentence code review comment asking for justification on an unexplained suppression.
3. Describe, in your own words, how a metavariable lets one rule match multiple code variations.