@elizaos/skills 2.0.0-alpha.3

package/skills/static-analysis/skills/sarif-parsing/resources/sarif_helpers.py

@@ -0,0 +1,331 @@
+"""
+SARIF Parsing Helper Functions
+
+Reusable utilities for working with SARIF files.
+No external dependencies beyond standard library.
+"""
+
+import hashlib
+import json
+from collections import defaultdict
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+
+@dataclass
+class Finding:
+    """Structured representation of a SARIF result."""
+
+    rule_id: str
+    level: str
+    message: str
+    file_path: str | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+    start_column: int | None = None
+    end_column: int | None = None
+    fingerprint: str | None = None
+    tool_name: str | None = None
+    rule_name: str | None = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+def load_sarif(path: str | Path) -> dict:
+    """Load and parse a SARIF file."""
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_sarif(sarif: dict, path: str | Path, indent: int = 2) -> None:
+    """Save SARIF data to file."""
+    with open(path, "w") as f:
+        json.dump(sarif, f, indent=indent)
+
+
+def validate_version(sarif: dict) -> bool:
+    """Check if SARIF version is 2.1.0."""
+    return sarif.get("version") == "2.1.0"
+
+
+def normalize_path(uri: str, base_path: str = "") -> str:
+    """Normalize SARIF artifact URI to consistent path."""
+    if not uri:
+        return ""
+
+    # Remove file:// prefix
+    if uri.startswith("file://"):
+        uri = uri[7:]
+
+    # URL decode
+    uri = unquote(uri)
+
+    # Handle relative paths
+    if base_path and not Path(uri).is_absolute():
+        uri = str(Path(base_path) / uri)
+
+    return str(Path(uri))
+
+
+def safe_get(data: dict, *keys, default: Any = None) -> Any:
+    """Safely navigate nested dict structure."""
+    for key in keys:
+        if isinstance(data, dict):
+            data = data.get(key, {})
+        elif isinstance(data, list) and isinstance(key, int):
+            data = data[key] if 0 <= key < len(data) else {}
+        else:
+            return default
+    return data if data != {} else default
+
+
+def extract_location(result: dict) -> tuple[str | None, int | None, int | None]:
+    """Extract file path, start line, and end line from result."""
+    loc = safe_get(result, "locations", 0, default={})
+    phys = loc.get("physicalLocation", {})
+    region = phys.get("region", {})
+
+    file_path = safe_get(phys, "artifactLocation", "uri")
+    start_line = region.get("startLine")
+    end_line = region.get("endLine")
+
+    return file_path, start_line, end_line
+
+
+def iter_results(sarif: dict) -> Iterator[tuple[dict, dict]]:
+    """Iterate over all results with their run context."""
+    for run in sarif.get("runs", []):
+        for result in run.get("results", []):
+            yield result, run
+
+
+def extract_findings(sarif: dict) -> list[Finding]:
+    """Extract all findings as structured objects."""
+    findings = []
+
+    for result, run in iter_results(sarif):
+        tool_name = safe_get(run, "tool", "driver", "name")
+        file_path, start_line, end_line = extract_location(result)
+
+        loc = safe_get(result, "locations", 0, default={})
+        phys = loc.get("physicalLocation", {})
+        region = phys.get("region", {})
+
+        # Get fingerprint
+        fp = None
+        if result.get("partialFingerprints"):
+            fp = next(iter(result["partialFingerprints"].values()), None)
+        elif result.get("fingerprints"):
+            fp = next(iter(result["fingerprints"].values()), None)
+
+        findings.append(
+            Finding(
+                rule_id=result.get("ruleId", "unknown"),
+                level=result.get("level", "warning"),
+                message=safe_get(result, "message", "text", default=""),
+                file_path=file_path,
+                start_line=start_line,
+                end_line=end_line,
+                start_column=region.get("startColumn"),
+                end_column=region.get("endColumn"),
+                fingerprint=fp,
+                tool_name=tool_name,
+                raw=result,
+            )
+        )
+
+    return findings
+
+
+def filter_by_level(findings: list[Finding], *levels: str) -> list[Finding]:
+    """Filter findings by severity level(s)."""
+    return [f for f in findings if f.level in levels]
+
+
+def filter_by_file(findings: list[Finding], pattern: str) -> list[Finding]:
+    """Filter findings by file path pattern (substring match)."""
+    return [f for f in findings if f.file_path and pattern in f.file_path]
+
+
+def filter_by_rule(findings: list[Finding], *rule_ids: str) -> list[Finding]:
+    """Filter findings by rule ID(s)."""
+    return [f for f in findings if f.rule_id in rule_ids]
+
+
+def sort_by_severity(findings: list[Finding], reverse: bool = False) -> list[Finding]:
+    """Sort findings by severity (error > warning > note > none)."""
+    severity_order = {"error": 0, "warning": 1, "note": 2, "none": 3}
+    return sorted(findings, key=lambda f: severity_order.get(f.level, 99), reverse=reverse)
+
+
+def group_by_file(findings: list[Finding]) -> dict[str, list[Finding]]:
+    """Group findings by file path."""
+    grouped = defaultdict(list)
+    for f in findings:
+        key = f.file_path or "unknown"
+        grouped[key].append(f)
+    return dict(grouped)
+
+
+def group_by_rule(findings: list[Finding]) -> dict[str, list[Finding]]:
+    """Group findings by rule ID."""
+    grouped = defaultdict(list)
+    for f in findings:
+        grouped[f.rule_id].append(f)
+    return dict(grouped)
+
+
+def count_by_level(findings: list[Finding]) -> dict[str, int]:
+    """Count findings by severity level."""
+    counts = defaultdict(int)
+    for f in findings:
+        counts[f.level] += 1
+    return dict(counts)
+
+
+def count_by_rule(findings: list[Finding]) -> dict[str, int]:
+    """Count findings by rule ID."""
+    counts = defaultdict(int)
+    for f in findings:
+        counts[f.rule_id] += 1
+    return dict(counts)
+
+
+def compute_fingerprint(result: dict, include_message: bool = True) -> str:
+    """Compute stable fingerprint from result data."""
+    components = [result.get("ruleId", "")]
+
+    file_path, start_line, _ = extract_location(result)
+    if file_path:
+        # Use only filename, not full path (more stable across environments)
+        components.append(Path(file_path).name)
+    if start_line:
+        components.append(str(start_line))
+    if include_message:
+        msg = safe_get(result, "message", "text", default="")
+        # First 50 chars of message for stability
+        components.append(msg[:50])
+
+    return hashlib.sha256("|".join(components).encode()).hexdigest()[:16]
+
+
+def deduplicate(findings: list[Finding]) -> list[Finding]:
+    """Remove duplicate findings based on fingerprints."""
+    seen = set()
+    unique = []
+
+    for f in findings:
+        key = f.fingerprint or compute_fingerprint(f.raw)
+        if key not in seen:
+            seen.add(key)
+            unique.append(f)
+
+    return unique
+
+
+def merge_sarif_files(*paths: str | Path) -> dict:
+    """Merge multiple SARIF files into one."""
+    merged = {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [],
+    }
+
+    for path in paths:
+        sarif = load_sarif(path)
+        merged["runs"].extend(sarif.get("runs", []))
+
+    return merged
+
+
+def diff_findings(
+    baseline: list[Finding], current: list[Finding]
+) -> tuple[list[Finding], list[Finding], list[Finding]]:
+    """
+    Compare two sets of findings.
+
+    Returns:
+        - new: findings in current but not baseline
+        - fixed: findings in baseline but not current
+        - unchanged: findings in both
+    """
+    baseline_fps = {f.fingerprint or compute_fingerprint(f.raw) for f in baseline}
+    current_fps = {f.fingerprint or compute_fingerprint(f.raw) for f in current}
+
+    new = [f for f in current if (f.fingerprint or compute_fingerprint(f.raw)) not in baseline_fps]
+    fixed = [
+        f for f in baseline if (f.fingerprint or compute_fingerprint(f.raw)) not in current_fps
+    ]
+    unchanged = [
+        f for f in current if (f.fingerprint or compute_fingerprint(f.raw)) in baseline_fps
+    ]
+
+    return new, fixed, unchanged
+
+
+def get_rules(sarif: dict) -> dict[str, dict]:
+    """Extract rule definitions from SARIF file."""
+    rules = {}
+    for run in sarif.get("runs", []):
+        for rule in safe_get(run, "tool", "driver", "rules", default=[]):
+            rules[rule.get("id", "")] = rule
+    return rules
+
+
+def to_csv_rows(findings: list[Finding]) -> list[list[str]]:
+    """Convert findings to CSV-ready rows."""
+    rows = [["rule_id", "level", "file", "line", "message"]]
+    for f in findings:
+        rows.append(
+            [
+                f.rule_id,
+                f.level,
+                f.file_path or "",
+                str(f.start_line or ""),
+                f.message.replace("\n", " ")[:200],
+            ]
+        )
+    return rows
+
+
+def summary(findings: list[Finding]) -> dict:
+    """Generate summary statistics for findings."""
+    return {
+        "total": len(findings),
+        "by_level": count_by_level(findings),
+        "by_rule": count_by_rule(findings),
+        "files_affected": len(set(f.file_path for f in findings if f.file_path)),
+        "rules_triggered": len(set(f.rule_id for f in findings)),
+    }
+
+
+# Example usage
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python sarif_helpers.py <sarif_file>")
+        sys.exit(1)
+
+    sarif = load_sarif(sys.argv[1])
+
+    if not validate_version(sarif):
+        print("Warning: SARIF version is not 2.1.0")
+
+    findings = extract_findings(sarif)
+    findings = sort_by_severity(findings)
+
+    print("\nSummary:")
+    stats = summary(findings)
+    print(f"  Total findings: {stats['total']}")
+    print(f"  Files affected: {stats['files_affected']}")
+    print(f"  Rules triggered: {stats['rules_triggered']}")
+    print("\nBy severity:")
+    for level, count in stats["by_level"].items():
+        print(f"  {level}: {count}")
+
+    print("\nTop 5 rules:")
+    for rule, count in sorted(stats["by_rule"].items(), key=lambda x: -x[1])[:5]:
+        print(f"  {rule}: {count}")

package/skills/static-analysis/skills/semgrep/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: semgrep
+description: Run Semgrep static analysis for fast security scanning and pattern matching. Use when asked to scan code with Semgrep, write custom YAML rules, find vulnerabilities quickly, use taint mode, or set up Semgrep in CI/CD pipelines.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Semgrep Static Analysis
+
+## When to Use Semgrep
+
+**Ideal scenarios:**
+- Quick security scans (minutes, not hours)
+- Pattern-based bug detection
+- Enforcing coding standards and best practices
+- Finding known vulnerability patterns
+- Single-file analysis without complex data flow
+- First-pass analysis before deeper tools
+
+**Consider CodeQL instead when:**
+- Need interprocedural taint tracking across files
+- Complex data flow analysis required
+- Analyzing custom proprietary frameworks
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Complex interprocedural data flow analysis (use CodeQL instead)
+- Binary analysis or compiled code without source
+- Custom deep semantic analysis requiring AST/CFG traversal
+- When you need to track taint across many function boundaries
+
+## Installation
+
+```bash
+# pip
+python3 -m pip install semgrep
+
+# Homebrew
+brew install semgrep
+
+# Docker
+docker run --rm -v "${PWD}:/src" returntocorp/semgrep semgrep --config auto /src
+
+# Update
+pip install --upgrade semgrep
+```
+
+## Core Workflow
+
+### 1. Quick Scan
+
+```bash
+semgrep --config auto .                    # Auto-detect rules
+semgrep --config auto --metrics=off .      # Disable telemetry for proprietary code
+```
+
+### 2. Use Rulesets
+
+```bash
+semgrep --config p/<RULESET> .             # Single ruleset
+semgrep --config p/security-audit --config p/trailofbits .  # Multiple
+```
+
+| Ruleset | Description |
+|---------|-------------|
+| `p/default` | General security and code quality |
+| `p/security-audit` | Comprehensive security rules |
+| `p/owasp-top-ten` | OWASP Top 10 vulnerabilities |
+| `p/cwe-top-25` | CWE Top 25 vulnerabilities |
+| `p/r2c-security-audit` | r2c security audit rules |
+| `p/trailofbits` | Trail of Bits security rules |
+| `p/python` | Python-specific |
+| `p/javascript` | JavaScript-specific |
+| `p/golang` | Go-specific |
+
+### 3. Output Formats
+
+```bash
+semgrep --config p/security-audit --sarif -o results.sarif .   # SARIF
+semgrep --config p/security-audit --json -o results.json .     # JSON
+semgrep --config p/security-audit --dataflow-traces .          # Show data flow
+```
+
+### 4. Scan Specific Paths
+
+```bash
+semgrep --config p/python app.py           # Single file
+semgrep --config p/javascript src/         # Directory
+semgrep --config auto --include='**/test/**' .  # Include tests (excluded by default)
+```
+
+## Writing Custom Rules
+
+### Basic Structure
+
+```yaml
+rules:
+  - id: hardcoded-password
+    languages: [python]
+    message: "Hardcoded password detected: $PASSWORD"
+    severity: ERROR
+    pattern: password = "$PASSWORD"
+```
+
+### Pattern Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `...` | Match anything | `func(...)` |
+| `$VAR` | Capture metavariable | `$FUNC($INPUT)` |
+| `<... ...>` | Deep expression match | `<... user_input ...>` |
+
+### Pattern Operators
+
+| Operator | Description |
+|----------|-------------|
+| `pattern` | Match exact pattern |
+| `patterns` | All must match (AND) |
+| `pattern-either` | Any matches (OR) |
+| `pattern-not` | Exclude matches |
+| `pattern-inside` | Match only inside context |
+| `pattern-not-inside` | Match only outside context |
+| `pattern-regex` | Regex matching |
+| `metavariable-regex` | Regex on captured value |
+| `metavariable-comparison` | Compare values |
+
+### Combining Patterns
+
+```yaml
+rules:
+  - id: sql-injection
+    languages: [python]
+    message: "Potential SQL injection"
+    severity: ERROR
+    patterns:
+      - pattern-either:
+          - pattern: cursor.execute($QUERY)
+          - pattern: db.execute($QUERY)
+      - pattern-not:
+          - pattern: cursor.execute("...", (...))
+      - metavariable-regex:
+          metavariable: $QUERY
+          regex: .*\+.*|.*\.format\(.*|.*%.*
+```
+
+### Taint Mode (Data Flow)
+
+Simple pattern matching finds obvious cases:
+
+```python
+# Pattern `os.system($CMD)` catches this:
+os.system(user_input)  # Found
+```
+
+But misses indirect flows:
+
+```python
+# Same pattern misses this:
+cmd = user_input
+processed = cmd.strip()
+os.system(processed)  # Missed - no direct match
+```
+
+Taint mode tracks data through assignments and transformations:
+- **Source**: Where untrusted data enters (`user_input`)
+- **Propagators**: How it flows (`cmd = ...`, `processed = ...`)
+- **Sanitizers**: What makes it safe (`shlex.quote()`)
+- **Sink**: Where it becomes dangerous (`os.system()`)
+
+```yaml
+rules:
+  - id: command-injection
+    languages: [python]
+    message: "User input flows to command execution"
+    severity: ERROR
+    mode: taint
+    pattern-sources:
+      - pattern: request.args.get(...)
+      - pattern: request.form[...]
+      - pattern: request.json
+    pattern-sinks:
+      - pattern: os.system($SINK)
+      - pattern: subprocess.call($SINK, shell=True)
+      - pattern: subprocess.run($SINK, shell=True, ...)
+    pattern-sanitizers:
+      - pattern: shlex.quote(...)
+      - pattern: int(...)
+```
+
+### Full Rule with Metadata
+
+```yaml
+rules:
+  - id: flask-sql-injection
+    languages: [python]
+    message: "SQL injection: user input flows to query without parameterization"
+    severity: ERROR
+    metadata:
+      cwe: "CWE-89: SQL Injection"
+      owasp: "A03:2021 - Injection"
+      confidence: HIGH
+    mode: taint
+    pattern-sources:
+      - pattern: request.args.get(...)
+      - pattern: request.form[...]
+      - pattern: request.json
+    pattern-sinks:
+      - pattern: cursor.execute($QUERY)
+      - pattern: db.execute($QUERY)
+    pattern-sanitizers:
+      - pattern: int(...)
+    fix: cursor.execute($QUERY, (params,))
+```
+
+## Testing Rules
+
+### Test File Format
+
+```python
+# test_rule.py
+def test_vulnerable():
+    user_input = request.args.get("id")
+    # ruleid: flask-sql-injection
+    cursor.execute("SELECT * FROM users WHERE id = " + user_input)
+
+def test_safe():
+    user_input = request.args.get("id")
+    # ok: flask-sql-injection
+    cursor.execute("SELECT * FROM users WHERE id = ?", (user_input,))
+```
+
+```bash
+semgrep --test rules/
+```
+
+## CI/CD Integration (GitHub Actions)
+
+```yaml
+name: Semgrep
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 0 1 * *'  # Monthly
+
+jobs:
+  semgrep:
+    runs-on: ubuntu-latest
+    container:
+      image: returntocorp/semgrep
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for diff-aware scanning
+
+      - name: Run Semgrep
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            semgrep ci --baseline-commit ${{ github.event.pull_request.base.sha }}
+          else
+            semgrep ci
+          fi
+        env:
+          SEMGREP_RULES: >-
+            p/security-audit
+            p/owasp-top-ten
+            p/trailofbits
+```
+
+## Configuration
+
+### .semgrepignore
+
+```
+tests/fixtures/
+**/testdata/
+generated/
+vendor/
+node_modules/
+```
+
+### Suppress False Positives
+
+```python
+password = get_from_vault()  # nosemgrep: hardcoded-password
+dangerous_but_safe()  # nosemgrep
+```
+
+## Performance
+
+```bash
+semgrep --config rules/ --time .    # Check rule performance
+ulimit -n 4096                       # Increase file descriptors for large codebases
+```
+
+### Path Filtering in Rules
+
+```yaml
+rules:
+  - id: my-rule
+    paths:
+      include: [src/]
+      exclude: [src/generated/]
+```
+
+## Third-Party Rules
+
+```bash
+pip install semgrep-rules-manager
+semgrep-rules-manager --dir ~/semgrep-rules download
+semgrep -f ~/semgrep-rules .
+```
+
+## Rationalizations to Reject
+
+| Shortcut | Why It's Wrong |
+|----------|----------------|
+| "Semgrep found nothing, code is clean" | Semgrep is pattern-based; it can't track complex data flow across functions |
+| "I wrote a rule, so we're covered" | Rules need testing with `semgrep --test`; false negatives are silent |
+| "Taint mode catches injection" | Only if you defined all sources, sinks, AND sanitizers correctly |
+| "Pro rules are comprehensive" | Pro rules are good but not exhaustive; supplement with custom rules for your codebase |
+| "Too many findings = noisy tool" | High finding count often means real problems; tune rules, don't disable them |
+
+## Resources
+
+- Registry: https://semgrep.dev/explore
+- Playground: https://semgrep.dev/playground
+- Docs: https://semgrep.dev/docs/
+- Trail of Bits Rules: https://github.com/trailofbits/semgrep-rules
+- Blog: https://semgrep.dev/blog/