@elizaos/skills 2.0.0-alpha.3

package/skills/semgrep-rule-creator/commands/semgrep-rule.md

@@ -0,0 +1,26 @@
+---
+name: trailofbits:semgrep-rule
+description: Creates Semgrep rules with test-first methodology
+argument-hint: "(uses conversation context for detection pattern)"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# Create Semgrep Rule
+
+**Arguments:** $ARGUMENTS
+
+This command is context-driven. Use conversation context to understand:
+1. The vulnerability or pattern to detect
+2. The target language
+3. Whether taint mode is appropriate
+
+If context is unclear, ask for a description of the pattern to detect.
+
+Invoke the `semgrep-rule-creator` skill for the full workflow.

package/skills/semgrep-rule-creator/skills/semgrep-rule-creator/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: semgrep-rule-creator
+description: Creates custom Semgrep rules for detecting security vulnerabilities, bug patterns, and code patterns. Use when writing Semgrep rules or building custom static analysis detections.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# Semgrep Rule Creator
+
+Create production-quality Semgrep rules with proper testing and validation.
+
+## When to Use
+
+**Ideal scenarios:**
+- Writing Semgrep rules for specific bug patterns
+- Writing rules to detect security vulnerabilities in your codebase
+- Writing taint mode rules for data flow vulnerabilities
+- Writing rules to enforce coding standards
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Running existing Semgrep rulesets
+- General static analysis without custom rules (use `static-analysis` skill)
+
+## Rationalizations to Reject
+
+When writing Semgrep rules, reject these common shortcuts:
+
+- **"The pattern looks complete"** → Still run `semgrep --test --config <rule-id>.yaml <rule-id>.<ext>` to verify. Untested rules have hidden false positives/negatives.
+- **"It matches the vulnerable case"** → Matching vulnerabilities is half the job. Verify safe cases don't match (false positives break trust).
+- **"Taint mode is overkill for this"** → If data flows from user input to a dangerous sink, taint mode gives better precision than pattern matching.
+- **"One test is enough"** → Include edge cases: different coding styles, sanitized inputs, safe alternatives, and boundary conditions.
+- **"I'll optimize the patterns first"** → Write correct patterns first, optimize after all tests pass. Premature optimization causes regressions.
+- **"The AST dump is too complex"** → The AST reveals exactly how Semgrep sees code. Skipping it leads to patterns that miss syntactic variations.
+
+## Anti-Patterns
+
+**Too broad** - matches everything, useless for detection:
+```yaml
+# BAD: Matches any function call
+pattern: $FUNC(...)
+
+# GOOD: Specific dangerous function
+pattern: eval(...)
+```
+
+**Missing safe cases in tests** - leads to undetected false positives:
+```python
+# BAD: Only tests vulnerable case
+# ruleid: my-rule
+dangerous(user_input)
+
+# GOOD: Include safe cases to verify no false positives
+# ruleid: my-rule
+dangerous(user_input)
+
+# ok: my-rule
+dangerous(sanitize(user_input))
+
+# ok: my-rule
+dangerous("hardcoded_safe_value")
+```
+
+**Overly specific patterns** - misses variations:
+```yaml
+# BAD: Only matches exact format
+pattern: os.system("rm " + $VAR)
+
+# GOOD: Matches all os.system calls with taint tracking
+mode: taint
+pattern-sinks:
+  - pattern: os.system(...)
+```
+
+## Strictness Level
+
+This workflow is **strict** - do not skip steps:
+- **Read documentation first**: See [Documentation](#documentation) before writing Semgrep rules
+- **Test-first is mandatory**: Never write a rule without tests
+- **100% test pass is required**: "Most tests pass" is not acceptable
+- **Optimization comes last**: Only simplify patterns after all tests pass
+- **Avoid generic patterns**: Rules must be specific, not match broad patterns
+- **Prioritize taint mode**: For data flow vulnerabilities
+- **One YAML file - one Semgrep rule**: Each YAML file must contain only one Semgrep rule; don't combine multiple rules in a single file
+- **No generic rules**: When targeting a specific language for Semgrep rules - avoid generic pattern matching (`languages: generic`)
+- **Forbidden `todook` and `todoruleid` test annotations**: `todoruleid: <rule-id>` and `todook: <rule-id>` annotations in tests files for future rule improvements are forbidden
+
+## Overview
+
+This skill guides creation of Semgrep rules that detect security vulnerabilities and code patterns. Rules are created iteratively: analyze the problem, write tests first, analyze AST structure, write the rule, iterate until all tests pass, optimize the rule.
+
+**Approach selection:**
+- **Taint mode** (prioritize): Data flow issues where untrusted input reaches dangerous sinks
+- **Pattern matching**: Simple syntactic patterns without data flow requirements
+
+**Why prioritize taint mode?** Pattern matching finds syntax but misses context. A pattern `eval($X)` matches both `eval(user_input)` (vulnerable) and `eval("safe_literal")` (safe). Taint mode tracks data flow, so it only alerts when untrusted data actually reaches the sink—dramatically reducing false positives for injection vulnerabilities.
+
+**Iterating between approaches:** It's okay to experiment. If you start with taint mode and it's not working well (e.g., taint doesn't propagate as expected, too many false positives/negatives), switch to pattern matching. Conversely, if pattern matching produces too many false positives on safe cases, try taint mode instead. The goal is a working rule—not rigid adherence to one approach.
+
+**Output structure** - exactly 2 files in a directory named after the rule-id:
+```
+<rule-id>/
+├── <rule-id>.yaml     # Semgrep rule
+└── <rule-id>.<ext>    # Test file with ruleid/ok annotations
+```
+
+## Quick Start
+
+```yaml
+rules:
+  - id: insecure-eval
+    languages: [python]
+    severity: HIGH
+    message: User input passed to eval() allows code execution
+    mode: taint
+    pattern-sources:
+      - pattern: request.args.get(...)
+    pattern-sinks:
+      - pattern: eval(...)
+```
+
+Test file (`insecure-eval.py`):
+```python
+# ruleid: insecure-eval
+eval(request.args.get('code'))
+
+# ok: insecure-eval
+eval("print('safe')")
+```
+
+Run tests (from rule directory): `semgrep --test --config <rule-id>.yaml <rule-id>.<ext>`
+
+## Quick Reference
+
+- For commands, pattern operators, and taint mode syntax, see [quick-reference.md]({baseDir}/references/quick-reference.md).
+- For detailed workflow and examples, you MUST see [workflow.md]({baseDir}/references/workflow.md)
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Semgrep Rule Progress:
+- [ ] Step 1: Analyze the Problem
+- [ ] Step 2: Write Tests First
+- [ ] Step 3: Analyze AST structure
+- [ ] Step 4: Write the rule
+- [ ] Step 5: Iterate until all tests pass (semgrep --test)
+- [ ] Step 6: Optimize the rule (remove redundancies, re-test)
+- [ ] Step 7: Final Run
+```
+
+## Documentation
+
+**REQUIRED**: Before writing any rule, use WebFetch to read **all** of these 4 links with Semgrep documentation:
+
+1. [Rule Syntax](https://semgrep.dev/docs/writing-rules/rule-syntax)
+2. [Pattern Syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax)
+3. [ToB Testing Handbook - Semgrep](https://appsec.guide/docs/static-analysis/semgrep/advanced/)
+4. [Constant propagation](https://semgrep.dev/docs/writing-rules/data-flow/constant-propagation)
+5. [Writing Rules Index](https://github.com/semgrep/semgrep-docs/tree/main/docs/writing-rules/)

package/skills/semgrep-rule-creator/skills/semgrep-rule-creator/references/quick-reference.md

@@ -0,0 +1,203 @@
+# Semgrep Rule Quick Reference
+
+## Required Rule Fields
+
+```yaml
+rules:
+  - id: rule-id          # Unique identifier (lowercase, hyphens)
+    languages:                 # Target language(s)
+      - python
+    severity: HIGH            # LOW, MEDIUM, HIGH, CRITICAL (ERROR/WARNING/INFO are legacy)
+    message: Description      # Shown when rule matches
+    pattern: code(...)        # OR use patterns/pattern-either/mode:taint
+```
+
+## Pattern Operators
+
+### Basic Matching
+```yaml
+pattern: foo(...)              # Match function call
+patterns:                      # AND - all must match
+  - pattern: $X
+  - pattern-not: safe($X)
+pattern-either:                # OR - any can match
+  - pattern: foo(...)
+  - pattern: bar(...)
+pattern-regex: ^foo.*bar$      # PCRE2 regex matching (multiline mode)
+```
+
+### Metavariables
+- `$VAR` - Match any single expression
+  - **Must be uppercase**: `$X`, `$FUNC`, `$VAR_1` (NOT `$x`, `$var`)
+- `$_` - Anonymous metavariable (matches but doesn't bind)
+- `$...VAR` - Match zero or more arguments (ellipsis metavariable)
+- `...` - Ellipsis, match anything in between
+
+### Typed Metavariables
+
+Constrain metavariables to specific types (reduces false positives):
+
+```yaml
+# C/C++ - match only int16_t parameters
+pattern: (int16_t $X)
+
+# C/C++ - match function with typed parameter
+pattern: some_func((int $ARG))
+
+# Java - match Logger type
+pattern: (java.util.logging.Logger $LOGGER).log(...)
+
+# Go - match pointer type (uses colon syntax)
+pattern: ($READER : *zip.Reader).Open($INPUT)
+
+# TypeScript - match specific type
+pattern: ($X: DomSanitizer).sanitize(...)
+
+Use in taint mode to track only specific types as sources:
+pattern-sources:
+  - pattern: (int $X)        # Only int parameters are taint sources
+  - pattern: (int16_t $X)    # Only int16_t parameters
+  - pattern: int $X = $INIT; # Local variable declarations
+
+
+### Deep Expression Matching
+```yaml
+<... $EXPR ...>               # Recursively match pattern in nested expressions
+```
+
+### Scope Operators
+```yaml
+pattern-inside: |              # Must be inside this pattern
+  def $FUNC(...):
+    ...
+pattern-not-inside: |          # Must NOT be inside this pattern
+  with $CTX:
+    ...
+```
+
+### Negation
+```yaml
+pattern-not: safe(...)         # Exclude this pattern
+pattern-not-regex: ^test_      # Exclude by regex
+```
+
+### Metavariable Filters
+```yaml
+metavariable-regex:
+  metavariable: $FUNC
+  regex: (unsafe|dangerous).*
+
+metavariable-pattern:
+  metavariable: $ARG
+  pattern: request.$X
+
+metavariable-comparison:
+  metavariable: $NUM
+  comparison: $NUM > 1024
+```
+
+### Focus
+```yaml
+focus-metavariable: $TARGET    # Report finding on this metavariable only
+```
+
+## Taint Mode
+
+```yaml
+rules:
+  - id: taint-rule
+    mode: taint
+    languages: [python]
+    severity: HIGH
+    message: Tainted data reaches sink
+    pattern-sources:
+      - pattern: user_input()
+      - pattern: request.args.get(...)
+    pattern-sinks:
+      - pattern: eval(...)
+      - pattern: os.system(...)
+    pattern-sanitizers:           # Optional
+      - pattern: sanitize(...)
+      - pattern: escape(...)
+```
+
+### Taint Options
+```yaml
+pattern-sources:
+  - pattern: source(...)
+    exact: true                   # Only exact match is source (default: false)
+    by-side-effect: true          # Taints variable by side effect
+
+pattern-sanitizers:
+  - pattern: sanitize($X)
+    exact: true                   # Only exact match (default: false)
+    by-side-effect: true          # Sanitizes by side effect
+
+pattern-sinks:
+  - pattern: sink(...)
+    exact: false                  # Subexpressions also sinks (default: true)
+```
+
+## Test File Annotations
+
+Only allowed annotations are `ok: rule-id` and `ok: rule-id`.
+
+```python
+# ruleid: rule-id
+vulnerable_code()              # This line MUST match
+
+# ok: rule-id
+safe_code()                    # This line MUST NOT match
+```
+
+DO NOT use multi-line comments for test annotations, for example:
+/* ruleid: ... */
+
+## Debugging Commands
+
+```bash
+# Test rules
+semgrep --test --config <rule-id>.yaml <rule-id>.<ext>
+
+# Validate YAML syntax
+semgrep --validate --config <rule-id>.yaml
+
+# Run with dataflow traces (for taint mode rules)
+semgrep --dataflow-traces -f <rule-id>.yaml <rule-id>.<ext>
+
+# Dump AST to understand code structure
+semgrep --dump-ast -l <language> <rule-id>.<ext>
+
+# Run single rule
+semgrep -f <rule-id>.yaml <rule-id>.<ext>
+```
+
+## Troubleshooting
+
+### Common Pitfalls
+
+1. **Wrong annotation line**: `ruleid:` must be on the line IMMEDIATELY BEFORE the finding. No other text or code
+2. **Too generic patterns**: Avoid `pattern: $X` without constraints
+3. **YAML syntax errors**: Validate with `semgrep --validate`
+
+### Pattern Not Matching
+
+1. Check AST structure: `semgrep --dump-ast -l <language> <rule-id>.<ext>`
+2. Verify metavariable binding
+3. Check for whitespace/formatting differences
+4. Try more general pattern first, then narrow down
+
+### Taint Not Propagating
+
+1. Use `--dataflow-traces` to see flow
+2. Check if sanitizer is too broad
+3. Verify source pattern matches
+4. Check sink focus-metavariable
+
+### Too Many False Positives
+
+1. Add `pattern-not` for safe cases
+2. Add sanitizers for validation functions
+3. Use `pattern-inside` to limit scope
+4. Use `metavariable-regex` to filter
+

package/skills/semgrep-rule-creator/skills/semgrep-rule-creator/references/workflow.md

@@ -0,0 +1,240 @@
+# Semgrep Rule Creation Workflow
+
+Detailed workflow for creating production-quality Semgrep rules.
+
+## Step 1: Analyze the Problem
+
+Before writing any code:
+
+1. **Fetch external documentation**: See [Documentation](../SKILL.md#documentation) for required reading
+2. **Understand the exact bug pattern and explain the bug for a junior developer**: What vulnerability, issue or pattern should be detected?
+3. **Identify the target language**: What is specific about the bug and that language?
+4. **Determine the approach**:
+   - **Pattern matching**: Syntactic patterns without data flow
+   - **Taint mode**: Data flows from untrusted source to dangerous sink
+
+### When to Use Taint Mode
+
+Taint mode is a powerful feature in Semgrep that can track the flow of data from one location to another. By using taint mode, you can:
+
+- **Track data flow across multiple variables**: Trace how data moves across different variables, functions, components, and identify insecure flow paths (e.g., situations where a specific sanitizer is not used).
+- **Find injection vulnerabilities**: Identify injection vulnerabilities such as SQL injection, command injection, and XSS attacks.
+- **Write simple and resilient Semgrep rules**: Simplify rules that are resilient to code patterns nested in if statements, loops, and other structures.
+
+## Step 2: Write Tests First
+
+**Why test-first?** Writing tests before the rule forces you to think about both vulnerable AND safe cases. Rules written without tests often have hidden false positives (matching safe cases) or false negatives (missing vulnerable variants). Tests make these visible immediately.
+
+Create directory and test file with annotations (`# ruleid:`, `# ok:` only). See [quick-reference.md]({baseDir}/references/quick-reference.md#test-file-annotations) for full syntax.
+
+### Directory Structure
+
+```
+<rule-id>/
+├── <rule-id>.yaml     # Semgrep rule
+└── <rule-id>.<ext>    # Test file with ruleid/ok annotations
+```
+
+**CRITICAL**:
+1. The comment (`# ruleid:` or `# ok:` ) must be on the line IMMEDIATELY BEFORE the code. Semgrep reports findings on the line after the annotation.
+2. The comment must contain ONLY the comment marker and annotation (e.g., `# ruleid: my-rule`). No other text, comments, or code on the same line.
+
+### Test Case Design
+
+You must include test cases for:
+- Clear vulnerable cases (must match)
+- Clear safe cases (must not match)
+- Edge cases and variations
+- Different coding styles
+- Sanitized/validated input (must not match)
+- Unrelated code (must not match) - normal code with no relation to the rule's target pattern
+- Nested structures (e.g., inside if statements, loops, try/catch blocks, callbacks)
+
+## Step 3: Analyze AST Structure
+
+**Why analyze AST?** Semgrep matches against the AST, not raw text. Code that looks similar may parse differently (e.g., `foo.bar()` vs `foo().bar`). The AST dump shows exactly what Semgrep sees, preventing patterns that fail due to unexpected tree structure. Understanding how exactly Semgrep parses code is crucial for writing precise patterns.
+
+```bash
+semgrep --dump-ast -l <language> <rule-id>.<ext>
+```
+
+Example output helps understand:
+- How function calls are represented
+- How variables are bound
+- How control flow is structured
+
+## Step 4: Write the Rule
+
+Choose the appropriate pattern operators and write the rule.
+
+For pattern operator syntax (basic matching, scope operators, metavariable filters, focus), see [quick-reference.md](quick-reference.md).
+
+### Validate and Test
+
+#### Validate YAML Syntax
+
+```bash
+semgrep --validate --config <rule-id>.yaml
+```
+
+#### Run Tests
+
+```bash
+cd <rule-directory>
+semgrep --test --config <rule-id>.yaml <rule-id>.<ext>
+```
+
+#### Expected Output
+
+```
+1/1: ✓ All tests passed
+```
+
+#### Debug Failures
+
+If tests fail, check:
+1. **Missed lines**: Rule didn't match when it should
+   - Pattern too specific
+   - Missing pattern variant
+2. **Incorrect lines**: Rule matched when it shouldn't
+   - Pattern too broad
+   - Need `pattern-not` exclusion
+
+#### Debug Taint Mode Rules
+
+```bash
+semgrep --dataflow-traces -f <rule-id>.yaml <rule-id>.<ext>
+```
+
+Shows:
+- Source locations
+- Sink locations
+- Data flow path
+- Why taint didn't propagate (if applicable)
+
+## Step 5: Iterate Until Tests Pass
+Work on writing Semgrep rule (patterns) iteratively to ensure the Semgrep rule works correctly.
+
+Each time when you introduce any changes, test Semgrep rule:
+
+```bash
+semgrep --test --config <rule-id>.yaml <rule-id>.<ext>
+```
+
+For debugging taint mode rules:
+```bash
+semgrep --dataflow-traces -f <rule-id>.yaml <rule-id>.<ext>
+```
+
+**Verification checkpoint**: Output MUST show "All tests passed". **Only proceed when validation passes**.
+
+
+**Verification checkpoint**: Proceed to Step 6: Optimize the Rule when:
+- "All tests passed"
+- No "missed lines" (false negatives)
+- No "incorrect lines" (false positives)
+
+### Common Fixes
+
+| Problem | Solution |
+|---------|----------|
+| Too many matches | Add `pattern-not` exclusions |
+| Missing matches | Add `pattern-either` variants |
+| Wrong line matched | Adjust `focus-metavariable` |
+| Taint not flowing | Check sanitizers aren't too broad |
+| Taint false positive | Add sanitizer pattern |
+
+## Step 6: Optimize the Rule
+
+After all tests pass, remove redundant patterns (quote variants, ellipsis subsets, redundant patterns).
+
+### Semgrep Pattern Equivalences
+
+Semgrep treats certain patterns as equivalent:
+
+| Written | Also Matches | Reason |
+|---------|--------------|--------|
+| `"string"` | `'string'` | Quote style normalized (in languages where both are equivalent) |
+| `func(...)` | `func()`, `func(a)`, `func(a,b)` | Ellipsis matches zero or more |
+| `func($X, ...)` | `func($X)`, `func($X, a, b)` | Trailing ellipsis is optional |
+
+### Common Redundancies to Remove
+
+**1. Quote Variants** (depends on the language)
+
+Before:
+```yaml
+pattern-either:
+  - pattern: hashlib.new("md5", ...)
+  - pattern: hashlib.new('md5', ...)
+```
+
+After:
+```yaml
+pattern-either:
+  - pattern: hashlib.new("md5", ...)
+```
+
+**2. Ellipsis Subsets**
+
+Before:
+```yaml
+pattern-either:
+  - pattern: dangerous($X, ...)
+  - pattern: dangerous($X)
+  - pattern: dangerous($X, $Y)
+```
+
+After:
+```yaml
+pattern: dangerous($X, ...)
+```
+
+**3. Consolidate with Metavariables**
+
+Before:
+```yaml
+pattern-either:
+  - pattern: md5($X)
+  - pattern: sha1($X)
+  - pattern: sha256($X)
+```
+
+After:
+```yaml
+patterns:
+  - pattern: $FUNC($X)
+  - metavariable-regex:
+      metavariable: $FUNC
+      regex: ^(md5|sha1|sha256)$
+```
+
+### Optimization Checklist
+
+1. Remove patterns differing only in quote style
+2. Remove patterns that are subsets of `...` patterns
+3. Consolidate similar patterns using metavariable-regex
+4. Remove duplicate patterns in pattern-either
+5. Simplify nested pattern-either when possible
+6. Replace complex regex patterns with metavariable-comparison
+7. **Re-run tests after each optimization**
+
+### Verify After Optimization
+
+```bash
+semgrep --test --config <rule-id>.yaml <rule-id>.<ext>
+```
+
+**CRITICAL**: Always re-run tests after optimization. Some "redundant" patterns may actually be necessary due to AST structure differences. If any test fails, revert the optimization that caused it.
+
+**Task complete ONLY when**: All tests pass after optimization.
+
+
+## Step 7: Final Run
+Run the Semgrep rule you created using: `semgrep --config <rule-id>.yaml <rule-id>.<ext>`.
+
+Ensure that message:
+ 1. Contains a short and concise explanation of the matched pattern
+ 2. Has no uninterpolated metavariables (e.g., $OP, $VAR). All metavariables referenced in the message must be captured by the pattern so they interpolate to actual code. 
+
+Fix any message issues and re-run that Semgrep rule after each fix.

package/skills/semgrep-rule-variant-creator/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "semgrep-rule-variant-creator",
+  "version": "1.0.0",
+  "description": "Creates language variants of existing Semgrep rules with proper applicability analysis and test-driven validation",
+  "author": {
+    "name": "Maciej Domanski",
+    "email": "opensource@trailofbits.com"
+  }
+}