interface:
  display_name: "Semgrep Rule Variant Creator"
  short_description: "Adapt Semgrep rules to additional programming languages"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

# Applicability Analysis

Phase 1 of the variant creation workflow. Before porting a rule, analyze whether the vulnerability pattern applies to the target language.

## Analysis Process

For EACH target language, answer these questions:

### 1. Does the Vulnerability Class Exist?

**Determine if the vulnerability type is possible in the target language.**

Examples:
- Buffer overflow: Applies to C/C++, may apply to Rust (in unsafe blocks), does NOT apply to Python/Java
- SQL injection: Applies to any language with database access
- XSS: Applies to any language generating HTML output
- Memory leak: Relevant in C/C++, less relevant in garbage-collected languages
- Type confusion: Relevant in dynamically typed languages, less relevant in strongly typed

### 2. Does an Equivalent Construct Exist?

**Identify what the original rule detects and find equivalents.**

Parse the original rule to identify:
- **Sinks**: What dangerous functions/methods does it detect?
- **Sources**: Where does tainted data originate?
- **Pattern type**: Is it taint-mode or pattern-matching?

Then research the target language:
- What are the equivalent dangerous functions?
- What are the common source patterns?
- Are there language-specific idioms to consider?

### 3. Are the Semantics Similar Enough?

**Verify the pattern translates meaningfully.**

Consider:
- Does the vulnerability manifest the same way?
- Are there language-specific mitigations that change detection needs?
- Would the ported rule provide actual security value?

## Verdict Format

Document your analysis for each target language:

```
TARGET: <language>
VERDICT: APPLICABLE | APPLICABLE_WITH_ADAPTATION | NOT_APPLICABLE
REASONING: <specific analysis>
ADAPTATIONS_NEEDED: <if APPLICABLE_WITH_ADAPTATION>
EQUIVALENT_CONSTRUCTS:
  - Original: <function/pattern>
  - Target: <equivalent function/pattern>
```

## Verdict Definitions

### APPLICABLE

The pattern translates directly with minor syntax adjustments.

**Criteria:**
- Equivalent constructs exist with same semantics
- Vulnerability manifests identically
- Detection logic remains the same

**Example:**
```
Original: Python os.system(user_input)
Target: Go exec.Command(user_input)

VERDICT: APPLICABLE
REASONING: Both execute shell commands with user input. Vulnerability is
identical (command injection). Detection logic (taint from input to exec)
translates directly.
```

### APPLICABLE_WITH_ADAPTATION

The pattern can be ported but requires significant changes.

**Criteria:**
- Vulnerability class exists but manifests differently
- Equivalent constructs exist but with different APIs
- Additional patterns needed for target language idioms

**Example:**
```
Original: Python pickle.loads(untrusted)
Target: Java ObjectInputStream.readObject()

VERDICT: APPLICABLE_WITH_ADAPTATION
REASONING: Both detect deserialization vulnerabilities but the APIs differ
significantly. Java requires detection of ObjectInputStream creation and
readObject() calls, not a single function call.
ADAPTATIONS_NEEDED:
  - Different sink patterns (readObject vs loads)
  - May need pattern-inside for ObjectInputStream context
  - Consider readUnshared() variant
```

### NOT_APPLICABLE

The pattern should not be ported to this language.

**Criteria:**
- Vulnerability class doesn't exist in target language
- No equivalent construct exists
- Pattern would be meaningless or misleading

**Example:**
```
Original: C strcpy/strncpy detection (CWE-676, use of a dangerous function)
Target: Python

VERDICT: NOT_APPLICABLE
REASONING: The rule detects an unbounded/bounded pair where a safer
replacement exists — strcpy -> strcpy_s, strncpy -> a variant that
NUL-terminates. Python has neither half. str and bytes are immutable and
length-prefixed, bytearray slice assignment resizes or raises, and there is
no NUL-termination contract to omit, so the ported sink would match only
memory-safe code.
```

Note what that reasoning does **not** say. "Python is memory-safe, so buffer
overflows cannot happen" is false, and reaching for it will get a verdict
overturned: `ctypes.memmove(create_string_buffer(8), b"B"*64, 64)` writes 64
bytes into an 8-byte buffer from pure Python and segfaults the interpreter.
The verdict holds on the sink, not on the language's reputation — `memmove` is
the analogue of `memcpy`, there is no `memmove_s` to recommend, and telling a
Python developer to use `strcpy_s` misattributes the finding. A `ctypes` rule
is worth writing; it is a different rule, not this one ported.

Reach for a language's safety reputation and you will overshoot. Check the
specific construct the rule names.

## Can Semgrep Analyze the Target at All?

Separate from the verdict, and answered by running Semgrep rather than from
memory. The three questions above ask whether the *bug* exists in the target.
This one asks whether Semgrep can *see* it, and a "no" stops the port however
applicable the pattern is.

```sh
semgrep show supported-languages          # is there a key for this language?
semgrep --dump-ast -l <key> probe.<ext>   # does the parser actually run?
```

Two ways it fails, both silent:

- **No frontend.** Perl is not a Semgrep language. Command injection is if
  anything worse there than in Python — `system("cmd $x")`, backticks, `qx{}`,
  two-arg piped `open` all reach `/bin/sh` — and CGI.pm, Plack and Mojolicious
  supply genuinely attacker-controlled sources. None of that matters: the only
  ways to touch a `.pl` file are `generic` and `regex`, neither of which has an
  AST or a dataflow engine, so `mode: taint` no-ops and returns zero findings at
  ~100% "parsed".
- **A Pro-only parser.** Elixir left OSS Semgrep in 1.51.0. A rule declaring
  `languages: [elixir]` is *skipped* rather than run: "1 rule(s) were skipped
  because they require Pro". Under `--test` that does **not** surface as a
  failure — the run ends in "All tests passed" over zero graded tests, which is
  why nothing downstream catches it and why this question has to be settled here
  by running semgrep rather than inferred from a green. The tempting fix — an
  older Semgrep that still ships the parser — produces a green nobody can
  reproduce.

Report this as `semgrepCanAnalyze`, and say which of the two questions is
failing. Folding "Semgrep cannot read this language" into `NOT_APPLICABLE`
claims the bug class is absent, which is a different and often false statement.

## Common Applicability Patterns

### Always Translate (Language-Agnostic Vulnerabilities)

These vulnerability classes exist across most languages:
- SQL injection (any language with DB access)
- Command injection (any language with shell execution)
- Path traversal (any language with file operations)
- SSRF (any language with HTTP clients)
- XSS (any language generating HTML)

### Sometimes Translate (Context-Dependent)

These require careful analysis:
- Deserialization: Different mechanisms per language
- Cryptographic weaknesses: Language-specific crypto libraries
- Race conditions: Depends on concurrency model
- Integer overflow: Depends on type system

### Rarely Translate (Language-Specific)

These are often NOT_APPLICABLE for other languages:
- Memory corruption (C/C++ specific)
- Type juggling (PHP specific)
- Prototype pollution (JavaScript specific)
- GIL-related issues (Python specific)

## Library-Specific Rules

When the original rule targets a third-party library:

### Step 1: Identify the Library's Purpose

What functionality does the library provide?
- ORM / Database access
- HTTP client/server
- Serialization
- Templating
- etc.

### Step 2: Research Target Language Ecosystem

For the target language, identify:
- Standard library equivalents
- Popular third-party libraries with same functionality
- Language-specific idioms for this functionality

### Step 3: Decide on Scope

Options:
- **Native constructs only**: Port to standard library equivalents
- **Popular library**: Port to the most common library in target ecosystem
- **Multiple variants**: Create separate rules for multiple libraries

**Recommendation**: Start with standard library or most popular option. Additional library variants can be created separately if needed.

## Analysis Checklist

Before proceeding past Phase 1:

- [ ] Parsed original rule and identified pattern type
- [ ] Identified sinks, sources, and sanitizers (if taint mode)
- [ ] Researched equivalent constructs in target language
- [ ] Documented verdict with specific reasoning
- [ ] If APPLICABLE_WITH_ADAPTATION, listed required changes
- [ ] If NOT_APPLICABLE, documented clear explanation

## Example Analysis

**Original Rule**: Python command injection via subprocess

```yaml
rules:
  - id: python-command-injection
    mode: taint
    languages: [python]
    pattern-sources:
      - pattern: request.args.get(...)
    pattern-sinks:
      - pattern: subprocess.call($CMD, shell=True, ...)
```

**Target**: Go

```
TARGET: Go
VERDICT: APPLICABLE_WITH_ADAPTATION

REASONING:
- Command injection exists in Go (vulnerability class present)
- Go uses exec.Command() and exec.CommandContext() for command execution
- Go doesn't have shell=True equivalent; commands run directly by default
- Shell execution in Go requires explicit bash -c wrapping

EQUIVALENT_CONSTRUCTS:
  - Original sink: subprocess.call(cmd, shell=True)
  - Target sinks:
    - exec.Command("bash", "-c", cmd)
    - exec.Command("sh", "-c", cmd)
    - exec.Command(cmd) when cmd comes from user input

ADAPTATIONS_NEEDED:
1. Different sink patterns for Go's exec package
2. Source patterns need Go HTTP handler equivalents (r.URL.Query(), r.FormValue())
3. Consider both direct exec.Command and shell-wrapped variants
```

**Target**: Java

```
TARGET: Java
VERDICT: APPLICABLE

REASONING:
- Command injection exists in Java (vulnerability class present)
- Java uses Runtime.exec() and ProcessBuilder for command execution
- Direct equivalent functionality available

EQUIVALENT_CONSTRUCTS:
  - Original sink: subprocess.call(cmd, shell=True)
  - Target sinks:
    - Runtime.getRuntime().exec(cmd)
    - new ProcessBuilder(cmd).start()

ADAPTATIONS_NEEDED:
- Source patterns need Java servlet equivalents (request.getParameter())
- Consider both Runtime.exec and ProcessBuilder patterns
```

# Language Syntax Translation Guide

Guidance for translating Semgrep patterns between languages. This is NOT a pre-built mapping—use these principles to research and adapt patterns for your specific case.

## General Translation Principles

### 1. Never Assume Syntax Equivalence

What looks similar may parse differently:

```python
# Python: method call on object
obj.method(arg)

# Go: might be method OR field access + function call
obj.Method(arg)      # Method call
obj.Field(arg)       # Field holding function, then called
```

**Always dump the AST** for your target language to see the actual structure.

### 2. Research Before Translating

For each construct in the original rule:
1. Search target language documentation for equivalent
2. Look for multiple ways the same thing can be written
3. Check if language idioms differ significantly

### 3. Preserve Detection Intent, Not Literal Syntax

The goal is detecting the same vulnerability, not matching identical syntax.

```yaml
# Original (Python) - detects eval of user input
pattern: eval($USER_INPUT)

# Go doesn't have eval() - what's the equivalent danger?
# Research shows: template execution, reflect-based eval, etc.
# Adapt to what actually creates the vulnerability in Go
```

## AST Analysis

### Always Dump the AST

```bash
semgrep --dump-ast -l <target-language> test-file
```

Compare how similar constructs are represented:

```python
# Python
cursor.execute(query)
```

```go
// Go
db.Query(query)
```

The AST structure may differ significantly even for conceptually similar operations.

### Key Differences to Watch

| Aspect | May Differ |
|--------|-----------|
| Method calls | Receiver position, syntax |
| Function arguments | Named vs positional, defaults |
| String handling | Interpolation, concatenation |
| Error handling | Exceptions vs return values |
| Imports | How namespaces work |

## Metavariable Adaptation

### Metavariables Work Cross-Language

Semgrep metavariables (`$X`, `$FUNC`, etc.) work in all languages:

```yaml
# Works in Python
pattern: $OBJ.execute($QUERY)

# Works in Java
pattern: $OBJ.executeQuery($QUERY)

# Works in Go
pattern: $DB.Query($QUERY, ...)
```

### Ellipsis Behavior

`...` matches language-appropriate constructs:
- In Python: matches arguments, statements
- In Go: matches arguments, statements (handles multi-return)
- In Java: matches arguments, statements, annotations

## Common Translation Categories

### Database Queries

**Research for your target language:**
- Standard library database package
- Popular ORM frameworks
- Raw query execution methods

Common patterns to look for:
- Query execution methods
- Prepared statement patterns
- String interpolation into queries

### Command Execution

**Research for your target language:**
- Standard library process/exec package
- Shell execution vs direct execution
- Argument passing (array vs string)

### File Operations

**Research for your target language:**
- File open/read/write APIs
- Path construction methods
- Directory traversal patterns

### HTTP Handling

**Research for your target language:**
- Request parameter access
- Header access
- Body parsing

## Researching Equivalents

### Step 1: Identify What the Original Detects

Parse the original rule:
- What function/method is the sink?
- What's the vulnerability being detected?
- What makes it dangerous?

### Step 2: Search Target Language Docs

Search for:
- `"<target language> <functionality>"` (e.g., "golang exec command")
- `"<target language> <vulnerability>"` (e.g., "java sql injection")
- Standard library documentation
- [Semgrep Pattern Examples](https://semgrep.dev/docs/writing-rules/pattern-examples) - Per-language pattern references

### Step 3: Find All Variants

A single Python function may have multiple equivalents:

```python
# Python has one main way
os.system(cmd)
```

```java
// Java has multiple
Runtime.getRuntime().exec(cmd);
new ProcessBuilder(cmd).start();
ProcessBuilder.command(cmd).start();
```

Include all common variants in your rule.

### Step 4: Check for Idioms

Languages have preferred patterns:

```python
# Python: often inline
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
```

```go
// Go: typically uses placeholders
db.Query("SELECT * FROM users WHERE id = ?", userID)
// Vulnerability is when they DON'T use placeholders
db.Query("SELECT * FROM users WHERE id = " + userID)
```

## Source Pattern Translation

### Web Framework Sources

Original rule sources need framework-specific translation:

```yaml
# Python Flask
pattern: request.args.get(...)

# Java Servlet
pattern: $REQUEST.getParameter(...)

# Go net/http
pattern: $R.URL.Query().Get(...)
pattern: $R.FormValue(...)

# Node.js Express
pattern: $REQ.query.$PARAM
pattern: $REQ.body.$PARAM
```

### User Input Sources

Research common input sources for target language, for example:
- HTTP request parameters
- Command line arguments
- Environment variables
- File reads
- Standard input

## Sanitizer Translation

### Research Sanitization Patterns

Each language has different sanitization approaches:

```python
# Python
shlex.quote(cmd)  # Shell escaping
html.escape(s)    # HTML escaping
```

```go
// Go
template.HTMLEscapeString(s)
// Prepared statements (implicit sanitization)
db.Query("SELECT ... WHERE id = ?", id)
```

```java
// Java
StringEscapeUtils.escapeHtml4(s)
PreparedStatement (implicit sanitization)
```

## Import/Namespace Considerations

### Pattern May Need Context

Some languages require matching imports:

```yaml
# Python - function in global namespace after import
pattern: pickle.loads(...)

# Java - may need full path or import context
pattern: java.io.ObjectInputStream
pattern: ObjectInputStream
```

### When to Use Full Paths

- When function name is common/ambiguous
- When you want to match specific library
- When namespace matters for security

## Testing Your Translation

### Verify with AST Dump

After writing test cases, verify patterns match:

```bash
# Dump AST of test file
semgrep --dump-ast -l <lang> test-file

# Compare with your pattern
# Adjust pattern to match AST structure
```

### Test Edge Cases

Each language has unique edge cases:
- Different string types (Go: string vs []byte)
- Different call syntaxes (method chaining)
- Different argument patterns

## Example: Translating SQL Injection Rule

**Original (Python):**
```yaml
pattern-sinks:
  - pattern: $CURSOR.execute($QUERY, ...)
```

**Research for Go:**
1. Standard database package: `database/sql`
2. Query methods: `Query`, `QueryRow`, `Exec`, `QueryContext`, etc.
3. ORM equivalents: GORM, sqlx, etc.

**Translated (Go - standard library):**
```yaml
pattern-sinks:
  - pattern: $DB.Query($QUERY, ...)
  - pattern: $DB.QueryRow($QUERY, ...)
  - pattern: $DB.Exec($QUERY, ...)
  - pattern: $DB.QueryContext($CTX, $QUERY, ...)
```

**Research for Java:**
1. JDBC: `Statement`, `PreparedStatement`
2. Query methods: `executeQuery`, `executeUpdate`, `execute`

**Translated (Java):**
```yaml
pattern-sinks:
  - pattern: (Statement $S).executeQuery($QUERY)
  - pattern: (Statement $S).executeUpdate($QUERY)
  - pattern: (Statement $S).execute($QUERY)
```

## Checklist Before Writing Rule

- [ ] Dumped AST for target language test file
- [ ] Researched equivalent functions/methods
- [ ] Identified all common variants
- [ ] Checked for language-specific idioms
- [ ] Identified appropriate source patterns
- [ ] Identified appropriate sanitizer patterns
- [ ] Verified patterns match AST structure

# Variant Creation Mechanics and Troubleshooting

The orchestration lives in `workflows/port-rule-to-languages.js` at the plugin root, which
runs as `/semgrep-rule-variant-creator:port-rule-to-languages`. It owns the phase order,
the recheck of a `NOT_APPLICABLE` verdict, and the validation retry. This file holds what
the script cannot encode: the mechanics inside a phase, and what to do when a pattern will
not match or taint will not flow.

## Core Principle: Independent Cycles

The ordering constraint is per language, not global. Within a language the phases are
strictly sequential — applicability decides whether there is anything to do, the tests
specify the rule, and validation is what finishes it — and no phase may start before the
one before it is done.

What must not happen is batching a phase across languages: writing every test file, then
every rule, then validating everything. Errors compound that way and the failure is hard
to attribute. Separate languages are otherwise independent, so one may reach translation
while another is still being assessed, which is how the workflow runs them.

A language whose tests do not pass is unfinished, not "mostly done".

## Annotation Placement

The annotation comment must be on the line immediately before the code it grades. This is
the single most common way a port fails for a reason that has nothing to do with the rule:

```go
// ruleid: my-rule
vulnerableCode()  // this line gets flagged

// ok: my-rule
safeCode()  // this line must NOT be flagged
```

An annotation followed by a blank line, or by another annotation, grades the wrong line.
Semgrep reports that as a missed or incorrect line, which reads exactly like a pattern bug
and sends you looking in the wrong place.

## Reading a Test Failure

`semgrep --test` reports one of three things.

Passing:

```
1/1: ✓ All tests passed
```

Missed lines — the rule did not match where it should have, so the pattern is narrower
than the vulnerability:

```
✗ python-command-injection-go
  missed lines: [15, 22]
```

Check for a pattern that is too specific, a missing pattern variant, or an AST structure
that does not look the way the pattern assumes.

Incorrect lines — the rule matched where it should not have, so the pattern is broader
than the vulnerability:

```
✗ python-command-injection-go
  incorrect lines: [30, 35]
```

Check for a pattern that is too broad, a missing `pattern-not` exclusion, or a sanitizer
the rule does not know about.

## Troubleshooting

### Pattern Not Matching

1. **Dump the AST**: `semgrep --dump-ast -l <lang> file`
2. **Compare structure**: your pattern against the actual AST, not against the source text
3. **Check metavariables**: is each one binding what you think it binds?
4. **Start broader**: match too much on purpose, then narrow until the safe cases pass

### Taint Not Propagating

Run `semgrep --dataflow-traces -f rule.yaml file`. It shows where taint originates, how it
propagates, where it reaches a sink, and where it stops — which is usually the answer.

1. **Check sanitizers**: one that is too broad silently kills the flow
2. **Verify sources**: is the source pattern matching at all? Test it as a plain pattern
3. **Check `focus-metavariable`**: is it on the part of the sink that receives the input?

### Too Many False Positives

1. **Add `pattern-not`**: exclude the shapes that are actually safe
2. **Add sanitizers**: the language's own validation and quoting functions
3. **Use `pattern-inside`**: limit the rule to the context where the risk exists
4. **Re-read the safe cases**: are they actually safe, or is the rule right and the test wrong?

### YAML Syntax Errors

1. **Run `--validate`**: it names the problem
2. **Check indentation**: YAML is whitespace-sensitive and Semgrep's nesting is deep
3. **Quote strings**: anything containing `:`, `#`, `{`, or a leading `*` needs quoting
4. **Use a block scalar**: `|` or `>-` for patterns that span lines