@elizaos/skills 2.0.0-alpha.10

package/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](skills/semgrep-rule-creator/references/quick-reference.md).
+- For detailed workflow and examples, you MUST see [workflow.md](skills/semgrep-rule-creator/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/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
+