osv-scanner

What this skill does

# Google OSV-Scanner - Vulnerability Detection for Dependencies

## When to Use OSV-Scanner

**Ideal scenarios:**

- Software Composition Analysis (SCA)
- Dependency vulnerability scanning
- License compliance checking
- SBOM (Software Bill of Materials) analysis
- Container image vulnerability scanning
- Supply chain security assessment
- CI/CD security gates for dependencies
- Open source risk management

**Complements other tools:**

- Use alongside code scanners (Semgrep, CodeQL) for complete coverage
- Combine with Depscan for enhanced SCA capabilities
- Use with SARIF Issue Reporter for findings analysis
- Pair with Gitleaks for secrets + dependency security

## When NOT to Use

Do NOT use this skill for:

- Application code vulnerability scanning (use Semgrep or CodeQL)
- Secrets detection (use Gitleaks)
- IaC security analysis (use KICS)
- API endpoint discovery (use Noir)
- Custom/proprietary code analysis

## Installation

```bash
# Go install
go install github.com/google/osv-scanner/cmd/osv-scanner@latest

# Homebrew
brew install osv-scanner

# Download binary (Linux)
wget https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64
chmod +x osv-scanner_linux_amd64
sudo mv osv-scanner_linux_amd64 /usr/local/bin/osv-scanner

# Download binary (macOS)
wget https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_darwin_amd64
chmod +x osv-scanner_darwin_amd64
sudo mv osv-scanner_darwin_amd64 /usr/local/bin/osv-scanner

# Docker
docker pull ghcr.io/google/osv-scanner:latest

# Verify
osv-scanner --version
```

## Core Workflow

### 1. Quick Scan

```bash
# Scan current directory
osv-scanner scan .

# Scan specific directory
osv-scanner scan /path/to/project

# Recursive scan
osv-scanner scan -r /path/to/project

# Scan multiple paths
osv-scanner scan ./app ./services ./libs
```

### 2. SARIF Output

```bash
# Generate SARIF report
osv-scanner scan --format sarif /path/to/project > results.sarif

# Named output file
osv-scanner scan --format sarif -o results.sarif /path/to/project

# Quiet mode with SARIF
osv-scanner scan -q --format sarif /path/to/project > results.sarif
```

### 3. Scan Specific Files

```bash
# Package manifest files
osv-scanner scan --lockfile package-lock.json
osv-scanner scan --lockfile Gemfile.lock
osv-scanner scan --lockfile requirements.txt
osv-scanner scan --lockfile go.mod
osv-scanner scan --lockfile Cargo.lock
osv-scanner scan --lockfile composer.lock
osv-scanner scan --lockfile pom.xml

# Multiple lock files
osv-scanner scan \
  --lockfile package-lock.json \
  --lockfile go.mod \
  --lockfile requirements.txt
```

### 4. SBOM Scanning

```bash
# Scan CycloneDX SBOM
osv-scanner scan --sbom sbom.json

# Scan SPDX SBOM
osv-scanner scan --sbom sbom.spdx.json

# Multiple SBOMs
osv-scanner scan --sbom app-sbom.json --sbom lib-sbom.json
```

### 5. Container Image Scanning

```bash
# Scan Docker image
osv-scanner scan --docker nginx:latest

# Scan local image
osv-scanner scan --docker my-app:1.0.0

# Export to SARIF
osv-scanner scan --docker my-app:1.0.0 --format sarif -o results.sarif
```

## Supported Ecosystems

| Ecosystem | Manifest Files | Lock Files |
|-----------|----------------|------------|
| **npm** | package.json | package-lock.json, yarn.lock, pnpm-lock.yaml |
| **Python** | requirements.txt, setup.py | Pipfile.lock, poetry.lock, pdm.lock |
| **Go** | go.mod | go.sum |
| **Rust** | Cargo.toml | Cargo.lock |
| **Java/Maven** | pom.xml | - |
| **Ruby** | Gemfile | Gemfile.lock |
| **PHP** | composer.json | composer.lock |
| **.NET** | packages.config, *.csproj | packages.lock.json |
| **Pub (Dart)** | pubspec.yaml | pubspec.lock |
| **CocoaPods** | Podfile | Podfile.lock |

## Output Formats

```bash
# Table format (default, human-readable)
osv-scanner scan /path/to/project

# JSON output
osv-scanner scan --format json /path/to/project

# SARIF output (for CI/CD integration)
osv-scanner scan --format sarif /path/to/project

# Markdown output
osv-scanner scan --format markdown /path/to/project

# Vertical format (detailed)
osv-scanner scan --format vertical /path/to/project
```

## Advanced Options

### Severity Filtering

```bash
# Show all severities (default)
osv-scanner scan /path/to/project

# Exit with error on any vulnerability
osv-scanner scan --fail-on-vuln /path/to/project

# Custom exit code
osv-scanner scan --exit-code 2 /path/to/project
```

### Offline Mode

```bash
# Download vulnerability database
osv-scanner scan --download-databases /path/to/db

# Use offline database
osv-scanner scan --offline --db-path /path/to/db /path/to/project
```

### Call Analysis (Experimental)

```bash
# Enable call analysis to reduce false positives
osv-scanner scan --experimental-call-analysis /path/to/project

# Requires source code analysis to determine if vulnerable code is actually used
```

### License Scanning

```bash
# Include license information
osv-scanner scan --experimental-licenses /path/to/project

# Output licenses only
osv-scanner scan --experimental-licenses --format json /path/to/project | jq '.licenses'
```

## CI/CD Integration (GitHub Actions)

```yaml
name: OSV-Scanner

on:
  push:
    branches: [main]
    paths:
      - '**/package*.json'
      - '**/requirements*.txt'
      - '**/go.mod'
      - '**/Cargo.lock'
      - '**/Gemfile.lock'
      - '**/composer.lock'
  pull_request:
  schedule:
    - cron: '0 0 * * *'  # Daily

jobs:
  osv-scan:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run OSV-Scanner
        uses: google/osv-scanner-action@v2
        with:
          scan-args: |-
            --recursive
            --format sarif
            --output results.sarif
            ./

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

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

## Configuration

### Ignore Vulnerabilities

Create `osv-scanner.toml`:

```toml
# Ignore specific vulnerabilities
[[IgnoredVulns]]
id = "CVE-2024-12345"
reason = "False positive - not used in our code path"
expiry = "2025-12-31"

[[IgnoredVulns]]
id = "GHSA-xxxx-yyyy-zzzz"
reason = "Accepted risk - fix scheduled for Q2"

# Ignore specific packages
[[PackageOverrides]]
name = "lodash"
version = "4.17.19"
ignore = true
reason = "Locked to specific version for compatibility"
```

Use config:

```bash
osv-scanner scan --config osv-scanner.toml /path/to/project
```

### Inline Ignores

```bash
# Scan and create ignore file from results
osv-scanner scan --json /path/to/project > vulnerabilities.json

# Review and selectively ignore
# Edit osv-scanner.toml based on vulnerabilities.json

# Rescan with ignores
osv-scanner scan --config osv-scanner.toml /path/to/project
```

## Common Use Cases

### 1. Pre-commit Dependency Check

```bash
# Scan staged lock files
git diff --cached --name-only | grep -E '(package-lock\.json|go\.sum|Cargo\.lock)' | \
  xargs -I {} osv-scanner scan --lockfile {}
```

### 2. Container Image Security

```bash
# Before deployment
osv-scanner scan --docker myapp:latest --format sarif -o image-vulns.sarif

# Fail build on vulnerabilities
osv-scanner scan --docker myapp:latest --fail-on-vuln || exit 1
```

### 3. SBOM Analysis

```bash
# Generate SBOM
syft dir:/path/to/project -o cyclonedx-json > sbom.json

# Scan SBOM for vulnerabilities
osv-scanner scan --sbom sbom.json --format sarif -o vuln-report.sarif

# Combine for complete view
sarif summary vuln-report.sarif
```

### 4. Multi-language Project

```bash
# Scan entire monorepo
osv-scanner scan -r /monorepo --format sarif -o complete-scan.sarif

# Per-language breakdown
osv-scanner scan --lockfile frontend/package-lock.json --format json > npm-vulns.json
osv-scanner scan --lockfile backend/go.mod --form