@vigolium/piolium 0.0.1

package/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/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: semgrep-rule-variant-creator
+description: Creates language variants of existing Semgrep rules. Use when porting a Semgrep rule to specified target languages. Takes an existing rule and target languages as input, produces independent rule+test directories for each language.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# Semgrep Rule Variant Creator
+
+Port existing Semgrep rules to new target languages with proper applicability analysis and test-driven validation.
+
+## When to Use
+
+**Ideal scenarios:**
+- Porting an existing Semgrep rule to one or more target languages
+- Creating language-specific variants of a universal vulnerability pattern
+- Expanding rule coverage across a polyglot codebase
+- Translating rules between languages with equivalent constructs
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Creating a new Semgrep rule from scratch (use `semgrep-rule-creator` instead)
+- Running existing rules against code
+- Languages where the vulnerability pattern fundamentally doesn't apply
+- Minor syntax variations within the same language
+
+## Input Specification
+
+This skill requires:
+1. **Existing Semgrep rule** - YAML file path or YAML rule content
+2. **Target languages** - One or more languages to port to (e.g., "Golang and Java")
+
+## Output Specification
+
+For each applicable target language, produces:
+```
+<original-rule-id>-<language>/
+├── <original-rule-id>-<language>.yaml     # Ported Semgrep rule
+└── <original-rule-id>-<language>.<ext>    # Test file with annotations
+```
+
+Example output for porting `sql-injection` to Go and Java:
+```
+sql-injection-golang/
+├── sql-injection-golang.yaml
+└── sql-injection-golang.go
+
+sql-injection-java/
+├── sql-injection-java.yaml
+└── sql-injection-java.java
+```
+
+## Rationalizations to Reject
+
+When porting Semgrep rules, reject these common shortcuts:
+
+| Rationalization | Why It Fails | Correct Approach |
+|-----------------|--------------|------------------|
+| "Pattern structure is identical" | Different ASTs across languages | Always dump AST for target language |
+| "Same vulnerability, same detection" | Data flow differs between languages | Analyze target language idioms |
+| "Rule doesn't need tests since original worked" | Language edge cases differ | Write NEW test cases for target |
+| "Skip applicability - it obviously applies" | Some patterns are language-specific | Complete applicability analysis first |
+| "I'll create all variants then test" | Errors compound, hard to debug | Complete full cycle per language |
+| "Library equivalent is close enough" | Surface similarity hides differences | Verify API semantics match |
+| "Just translate the syntax 1:1" | Languages have different idioms | Research target language patterns |
+
+## Strictness Level
+
+This workflow is **strict** - do not skip steps:
+- **Applicability analysis is mandatory**: Don't assume patterns translate
+- **Each language is independent**: Complete full cycle before moving to next
+- **Test-first for each variant**: Never write a rule without test cases
+- **100% test pass required**: "Most tests pass" is not acceptable
+
+## Overview
+
+This skill guides the creation of language-specific variants of existing Semgrep rules. Each target language goes through an independent 4-phase cycle:
+
+```
+FOR EACH target language:
+  Phase 1: Applicability Analysis → Verdict
+  Phase 2: Test Creation (Test-First)
+  Phase 3: Rule Creation
+  Phase 4: Validation
+  (Complete full cycle before moving to next language)
+```
+
+## Foundational Knowledge
+
+**The `semgrep-rule-creator` skill is the authoritative reference for Semgrep rule creation fundamentals.** While this skill focuses on porting existing rules to new languages, the core principles of writing quality rules remain the same.
+
+Consult `semgrep-rule-creator` for guidance on:
+- **When to use taint mode vs pattern matching** - Choosing the right approach for the vulnerability type
+- **Test-first methodology** - Why tests come before rules and how to write effective test cases
+- **Anti-patterns to avoid** - Common mistakes like overly broad or overly specific patterns
+- **Iterating until tests pass** - The validation loop and debugging techniques
+- **Rule optimization** - Removing redundant patterns after tests pass
+
+When porting a rule, you're applying these same principles in a new language context. If uncertain about rule structure or approach, refer to `semgrep-rule-creator` first.
+
+## Four-Phase Workflow
+
+### Phase 1: Applicability Analysis
+
+Before porting, determine if the pattern applies to the target language.
+
+**Analysis criteria:**
+1. Does the vulnerability class exist in the target language?
+2. Does an equivalent construct exist (function, pattern, library)?
+3. Are the semantics similar enough for meaningful detection?
+
+**Verdict options:**
+- `APPLICABLE` → Proceed with variant creation
+- `APPLICABLE_WITH_ADAPTATION` → Proceed but significant changes needed
+- `NOT_APPLICABLE` → Skip this language, document why
+
+See [applicability-analysis.md]({baseDir}/references/applicability-analysis.md) for detailed guidance.
+
+### Phase 2: Test Creation (Test-First)
+
+**Always write tests before the rule.**
+
+Create test file with target language idioms:
+- Minimum 2 vulnerable cases (`ruleid:`)
+- Minimum 2 safe cases (`ok:`)
+- Include language-specific edge cases
+
+```go
+// ruleid: sql-injection-golang
+db.Query("SELECT * FROM users WHERE id = " + userInput)
+
+// ok: sql-injection-golang
+db.Query("SELECT * FROM users WHERE id = ?", userInput)
+```
+
+### Phase 3: Rule Creation
+
+1. **Analyze AST**: `semgrep --dump-ast -l <lang> test-file`
+2. **Translate patterns** to target language syntax
+3. **Update metadata**: language key, message, rule ID
+4. **Adapt for idioms**: Handle language-specific constructs
+
+See [language-syntax-guide.md]({baseDir}/references/language-syntax-guide.md) for translation guidance.
+
+### Phase 4: Validation
+
+```bash
+# Validate YAML
+semgrep --validate --config rule.yaml
+
+# Run tests
+semgrep --test --config rule.yaml test-file
+```
+
+**Checkpoint**: Output MUST show `All tests passed`.
+
+For taint rule debugging:
+```bash
+semgrep --dataflow-traces -f rule.yaml test-file
+```
+
+See [workflow.md]({baseDir}/references/workflow.md) for detailed workflow and troubleshooting.
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Run tests | `semgrep --test --config rule.yaml test-file` |
+| Validate YAML | `semgrep --validate --config rule.yaml` |
+| Dump AST | `semgrep --dump-ast -l <lang> <file>` |
+| Debug taint flow | `semgrep --dataflow-traces -f rule.yaml file` |
+
+
+## Key Differences from Rule Creation
+
+| Aspect | semgrep-rule-creator | This skill |
+|--------|---------------------|------------|
+| Input | Bug pattern description | Existing rule + target languages |
+| Output | Single rule+test | Multiple rule+test directories |
+| Workflow | Single creation cycle | Independent cycle per language |
+| Phase 1 | Problem analysis | Applicability analysis per language |
+| Library research | Always relevant | Optional (when original uses libraries) |
+
+## Documentation
+
+**REQUIRED**: Before porting rules, read relevant Semgrep documentation:
+
+- [Rule Syntax](https://semgrep.dev/docs/writing-rules/rule-syntax) - YAML structure and operators
+- [Pattern Syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax) - Pattern matching and metavariables
+- [Pattern Examples](https://semgrep.dev/docs/writing-rules/pattern-examples) - Per-language pattern references
+- [Testing Rules](https://semgrep.dev/docs/writing-rules/testing-rules) - Testing annotations
+- [Trail of Bits Testing Handbook](https://appsec.guide/docs/static-analysis/semgrep/advanced/) - Advanced patterns
+
+## Next Steps
+
+- For applicability analysis guidance, see [applicability-analysis.md]({baseDir}/references/applicability-analysis.md)
+- For language translation guidance, see [language-syntax-guide.md]({baseDir}/references/language-syntax-guide.md)
+- For detailed workflow and examples, see [workflow.md]({baseDir}/references/workflow.md)

package/skills/semgrep-rule-variant-creator/references/applicability-analysis.md

@@ -0,0 +1,250 @@
+# 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 buffer overflow detection
+Target: Python
+
+VERDICT: NOT_APPLICABLE
+REASONING: Python handles memory management automatically. Buffer overflows
+in the traditional C sense don't exist. The vulnerability class is not
+present in the target language.
+```
+
+## 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
+```