opengrep

What this skill does

# Opengrep - Open Source Code Security Engine

## What is Opengrep?

Opengrep is a fork of Semgrep CE (Community Edition), launched in early 2025 by a consortium including JIT, Aikido Security, Endor Labs, and other companies. It was created in response to Semgrep's licensing changes that restricted community-contributed rules from being used in commercial products.

**Key Differences from Semgrep:**

- Fully open-source rules (no license restrictions)
- Community-driven governance
- No proprietary feature lock-in
- Compatible with Semgrep CE syntax and rules
- Focused on keeping critical features open
- Commercial integration friendly

## When to Use Opengrep

**Ideal scenarios:**

- Quick security scans (minutes, not hours)
- Pattern-based vulnerability detection
- Using community rules without license concerns
- Commercial product integration requiring open-source SAST
- Dataflow and taint analysis within files
- Multi-language security scanning
- First-pass security analysis before deeper tools
- When Semgrep licensing is a concern

**Consider CodeQL instead when:**

- Need interprocedural taint tracking across files
- Complex data flow analysis across modules required
- Analyzing custom proprietary frameworks with deep integration

## When NOT to Use

Do NOT use this skill for:

- Complex cross-file data flow analysis (use CodeQL)
- Binary or compiled code analysis without source
- Deep semantic analysis requiring full program analysis
- Runtime vulnerability detection
- Secrets scanning (use Gitleaks)
- Dependency scanning (use OSV-Scanner or Depscan)

## Installation

```bash
# Homebrew
brew install opengrep

# pip
pip install opengrep

# pipx (recommended)
pipx install opengrep

# Docker
docker pull ghcr.io/opengrep/opengrep:latest

# From source
git clone https://github.com/opengrep/opengrep.git
cd opengrep
pip install -e .

# Verify
opengrep --version
```

## Core Workflow

### 1. Quick Scan

```bash
# Auto scan with default rules
opengrep scan .

# Scan with specific ruleset
opengrep scan -f p/security-audit .

# Multiple rulesets
opengrep scan -f p/owasp-top-ten -f p/cwe-top-25 .
```

### 2. SARIF Output

```bash
# Generate SARIF report
opengrep scan --sarif -o results.sarif .

# SARIF with specific rules
opengrep scan -f p/security-audit --sarif -o results.sarif .

# Filter by severity in SARIF
opengrep scan \
  --severity=WARNING \
  --severity=ERROR \
  --sarif \
  -o results.sarif \
  .
```

### 3. Advanced Scanning

```bash
# Enable dataflow traces
opengrep scan --dataflow-traces .

# Taint analysis (intra-file)
opengrep scan --taint-intrafile .

# Experimental features
opengrep scan --experimental .

# Combined: dataflow + taint + experimental
opengrep scan \
  --dataflow-traces \
  --taint-intrafile \
  --experimental \
  .
```

### 4. Custom Rules

```bash
# Local rule files
opengrep scan -f /path/to/rules .

# Multiple rule directories
opengrep scan -f ./rules -f ./custom-rules .

# Exclude specific rules
opengrep scan \
  -f p/security-audit \
  --exclude-rule="rule-id-to-skip" \
  .
```

## Rulesets

### Public Rulesets

| 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/trailofbits` | Trail of Bits security rules |
| `p/python` | Python-specific security |
| `p/javascript` | JavaScript/TypeScript security |
| `p/golang` | Go-specific security |
| `p/java` | Java security patterns |
| `p/ruby` | Ruby security patterns |

### Community Rules

```bash
# Clone community rules
git clone https://github.com/opengrep/opengrep-rules.git

# Use community rules
opengrep scan -f opengrep-rules/ .

# Trail of Bits rules (fully open)
git clone https://github.com/trailofbits/semgrep-rules.git
opengrep scan -f semgrep-rules/rules .
```

## Output Formats

```bash
# Text output (default)
opengrep scan .

# SARIF (for CI/CD)
opengrep scan --sarif .

# JSON
opengrep scan --json .

# JUnit XML
opengrep scan --junit-xml .

# GitLab SAST format
opengrep scan --gitlab-sast .

# Vim quickfix
opengrep scan --vim .

# Emacs format
opengrep scan --emacs .
```

## Configuration

### .opengrepignore

Create `.opengrepignore`:

```
tests/fixtures/
**/testdata/
generated/
vendor/
node_modules/
__pycache__/
*.test.js
*.spec.ts
```

### Project Configuration

Create `.opengrep.yml`:

```yaml
rules:
  - id: custom-hardcoded-secret
    languages: [python, javascript]
    message: "Hardcoded secret detected"
    severity: ERROR
    pattern: |
      $VAR = "$SECRET"
    metadata:
      cwe: "CWE-798"
      owasp: "A07:2021 - Identification and Authentication Failures"

  - id: sql-injection-risk
    languages: [python]
    message: "Potential SQL injection"
    severity: ERROR
    mode: taint
    pattern-sources:
      - pattern: request.args.get(...)
    pattern-sinks:
      - pattern: cursor.execute($QUERY)
    pattern-sanitizers:
      - pattern: int(...)

exclude:
  - tests/
  - vendor/
```

Use config:

```bash
opengrep scan --config .opengrep.yml .
```

## CI/CD Integration (GitHub Actions)

```yaml
name: Opengrep Security Scan

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 1'  # Weekly

jobs:
  opengrep:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Opengrep
        run: pip install opengrep

      - name: Run Opengrep
        run: |
          opengrep scan \
            -f p/security-audit \
            -f p/owasp-top-ten \
            --dataflow-traces \
            --taint-intrafile \
            --experimental \
            --sarif \
            -o opengrep-results.sarif \
            --severity=WARNING \
            --severity=ERROR \
            --exclude=test \
            --exclude=tests \
            .

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: opengrep-results.sarif
          category: opengrep

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: opengrep-results
          path: opengrep-results.sarif
```

## Writing Custom Rules

### Basic Rule Structure

```yaml
rules:
  - id: dangerous-eval
    languages: [javascript, python]
    message: "Use of eval() is dangerous"
    severity: ERROR
    patterns:
      - pattern: eval($CODE)
      - pattern-not: eval("...")  # Literal strings okay
```

### 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 |

### Taint Mode

```yaml
rules:
  - id: xss-vulnerability
    languages: [javascript]
    message: "User input flows to innerHTML (XSS risk)"
    severity: ERROR
    mode: taint
    pattern-sources:
      - pattern: req.query.$PARAM
      - pattern: req.body.$PARAM
    pattern-sinks:
      - pattern: $ELEMENT.innerHTML = $DATA
    pattern-sanitizers:
      - pattern: escapeHtml(...)
      - pattern: DOMPurify.sanitize(...)
```

## Common Use Cases

### 1. Comprehensive Security Audit

```bash
# Multi-ruleset scan
opengrep scan \
  -f p/security-audit \
  -f p/owasp-top-ten \
  -f p/cwe-top-25 \
  --dataflow-traces \
  --experimental \
  -