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.

Bridging the Gap: Navigating Nuance for Non-Native Speakers

The core of effective communication within a development team, particularly when dealing with tools like Semgrep, relies heavily on precise English. It’s not just about conveying what you observe – it’s about articulating why and suggesting how to fix it. For developers whose first language isn’t English, this can feel incredibly daunting. The subtle differences in phrasing, the implicit assumptions baked into common requests, and even the level of detail expected can create significant barriers. Don’t be discouraged; mastering professional English is a journey, and focusing on practical application within your workflow will yield far better results than simply memorizing lists of words. One crucial element often overlooked is understanding the tone of communication – a suggestion framed as a request is vastly different from one presented as an imperative.

Let’s consider a common scenario: you’ve spotted a potential vulnerability flagged by Semgrep in a pull request. You might initially draft a comment like, “This rule matches this code.” While technically correct, it lacks context and could easily be misinterpreted. A more effective approach would be, “I’ve identified a possible issue related to [specific function name] that’s being matched by the no-eval rule. This is because the code uses an inline JavaScript expression which is generally discouraged for security reasons. Could you review this section and consider refactoring it to use a safer alternative?” Notice the added explanation, the specific rule referenced, and the polite phrasing (“Could you review…”). This demonstrates not just that you’ve identified something but that you’re offering assistance and explaining why the finding is important. Similarly, when writing PR descriptions, avoid vague statements like “Fixed bug.” Instead, detail the problem, the solution, and the reasoning behind it: “Resolved a potential XSS vulnerability in the user input handling logic by sanitizing all data before rendering to the DOM.”

Another frequent challenge arises during code reviews – particularly when dealing with findings that might seem overly sensitive or require further investigation. A developer might respond defensively with, “This is perfectly fine; Semgrep is just being noisy.” This response shuts down discussion and doesn’t address the underlying concern. A better approach would be: “I understand your hesitation, but the no-eval rule is triggered here due to the potential for arbitrary code execution if untrusted input is processed directly within JavaScript. While this specific case appears benign, it highlights a broader security consideration that warrants attention.” Remember, the goal isn’t to prove Semgrep wrong, but to collaboratively assess and mitigate risk.

Finally, don’t be afraid to ask for clarification. If you don’t understand a comment or request, politely seek explanation: “Could you elaborate on what you mean by ‘reduce false positives’? I want to ensure I’m addressing the root cause effectively.” Most developers appreciate the effort and will gladly provide context. Building confidence comes from actively engaging in discussions and demonstrating a willingness to learn.

# Example Semgrep rule for detecting inline JavaScript
rule inline_javascript {
  patterns = [
    "eval\\((.+?)\\)",
    "new Function\\((.+?)\\)"
  ]
  severity = "High"
  description = "Detects potentially dangerous inline JavaScript execution."
}