diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8f952b6..42c2cea 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -84,6 +84,11 @@ "name": "webcam-automation", "source": "./plugins/webcam-automation", "description": "Webcam capture CLI tool for photographing paper notes" + }, + { + "name": "dep-vulnerability-scanner", + "source": "./plugins/dep-vulnerability-scanner", + "description": "Dependency vulnerability scanning with Trivy, Grype, npm/bun audit, and pip-audit" } ] } diff --git a/plugins/dep-vulnerability-scanner/.claude-plugin/plugin.json b/plugins/dep-vulnerability-scanner/.claude-plugin/plugin.json new file mode 100644 index 0000000..3e171e8 --- /dev/null +++ b/plugins/dep-vulnerability-scanner/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "dep-vulnerability-scanner", + "version": "1.0.0", + "description": "Dependency vulnerability scanning tools: Trivy, Grype, npm audit, bun audit, and pip-audit", + "author": "Val Redchenko" +} diff --git a/plugins/dep-vulnerability-scanner/README.md b/plugins/dep-vulnerability-scanner/README.md new file mode 100644 index 0000000..d8d6bc2 --- /dev/null +++ b/plugins/dep-vulnerability-scanner/README.md @@ -0,0 +1,197 @@ +# Dependency Vulnerability Scanner Plugin + +A comprehensive plugin for scanning project dependencies for known security vulnerabilities using industry-standard tools. + +## Supported Tools + +This plugin provides knowledge and commands for working with five vulnerability scanning tools: + +### Universal Scanners + +| Tool | Description | Best For | +|------|-------------|----------| +| **[Trivy](https://github.com/aquasecurity/trivy)** | Comprehensive security scanner by Aqua Security | Containers, filesystems, repos, IaC, secrets | +| **[Grype](https://github.com/anchore/grype)** | Focused vulnerability scanner by Anchore | Fast scanning, SBOM analysis, risk scoring | + +### Language-Specific Scanners + +| Tool | Description | Best For | +|------|-------------|----------| +| **[npm audit](https://docs.npmjs.com/cli/v10/commands/npm-audit)** | Built-in npm security auditor | Node.js/npm projects with auto-fix support | +| **[bun audit](https://bun.com/docs/install/audit)** | Built-in Bun security auditor | Bun.js projects | +| **[pip-audit](https://github.com/pypa/pip-audit)** | Python environment auditor by PyPA | Python projects (supports uv via `uvx pip-audit`) | + +## Installation + +Install this plugin using the Claude Code plugin marketplace: + +```bash +claude plugin install dep-vulnerability-scanner +``` + +## Commands + +### `/vuln-scan` +Run a vulnerability scan on the current project. Automatically detects project type and suggests the appropriate tool. + +**Features:** +- Auto-detects project type (npm, Bun, Python, etc.) +- Runs the appropriate scanner with sensible defaults +- Presents results with severity levels +- Suggests remediation steps + +### `/vuln-setup` +Install and configure vulnerability scanning tools on your system. + +**Supported installation methods:** +- Homebrew (macOS) +- apt/rpm (Linux) +- Docker (any platform) +- pip/pipx/uvx (Python tools) +- Direct binary installation + +### `/vuln-compare` +Compare vulnerability scanning tools to choose the right one for your project. + +**Compares:** +- Supported ecosystems +- Scan speed +- Auto-fix capabilities +- SBOM support +- CI/CD integration quality +- Output formats + +### `/vuln-ci-workflow` +Generate GitHub Actions workflows for automated vulnerability scanning. + +**Workflow templates for:** +- Trivy filesystem scanning with SARIF upload +- Grype scanning with GitHub Security integration +- npm audit for Node.js projects +- bun audit for Bun projects +- pip-audit for Python projects (including uv projects) +- Multi-scanner comprehensive workflows + +## Tool Quick Reference + +### Trivy +```bash +# Install +brew install trivy # macOS +curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin + +# Scan +trivy fs . # Scan filesystem +trivy fs --severity HIGH,CRITICAL . # Filter by severity +trivy fs -f json -o results.json . # JSON output +trivy image myapp:latest # Scan container image +``` + +### Grype +```bash +# Install +brew install grype # macOS +curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sudo sh -s -- -b /usr/local/bin + +# Scan +grype . # Scan directory +grype . --fail-on high # Fail on high severity +grype . -o json # JSON output +grype myapp:latest # Scan container image +``` + +### npm audit +```bash +# No installation needed (built into npm) + +# Scan +npm audit # Basic scan +npm audit --audit-level=high # Only high+ severity +npm audit --production # Production deps only +npm audit --json # JSON output + +# Fix +npm audit fix # Auto-fix vulnerabilities +npm audit fix --dry-run # Preview fixes +``` + +### bun audit +```bash +# No installation needed (built into Bun) + +# Scan +bun audit # Basic scan +bun audit --audit-level=high # Only high+ severity +bun audit --prod # Production deps only +bun audit --json # JSON output +bun audit --ignore CVE-2024-XXXXX # Ignore specific CVE +``` + +### pip-audit +```bash +# Install +pip install pip-audit # Via pip +pipx install pip-audit # Via pipx (recommended) +uvx pip-audit # Run via uv (no install) + +# Scan +pip-audit # Scan current environment +pip-audit -r requirements.txt # Scan requirements file +pip-audit -f json # JSON output +pip-audit -f cyclonedx-json # SBOM output +pip-audit --desc # Include descriptions + +# Fix +pip-audit --fix # Auto-fix vulnerabilities +pip-audit --fix --dry-run # Preview fixes +``` + +## GitHub Actions Examples + +### Quick Setup (Trivy) +```yaml +- uses: aquasecurity/trivy-action@0.28.0 + with: + scan-type: 'fs' + scan-ref: '.' + severity: 'HIGH,CRITICAL' + format: 'sarif' + output: 'trivy-results.sarif' +``` + +### Quick Setup (Grype) +```yaml +- uses: anchore/scan-action@v6 + with: + path: "." + fail-build: true + severity-cutoff: high +``` + +### Quick Setup (pip-audit) +```yaml +- uses: pypa/gh-action-pip-audit@v1.1.0 + with: + inputs: requirements.txt +``` + +## Tool Selection Guide + +| If your project is... | Use this tool | +|-----------------------|---------------| +| Node.js with npm | `npm audit` (has auto-fix) | +| Node.js with Bun | `bun audit` | +| Python | `pip-audit` (or `uvx pip-audit`) | +| Container-based | `trivy image` or `grype` | +| Multi-language monorepo | `trivy fs` or `grype` | +| Need SBOM generation | `trivy` (SBOM + vulns) or `pip-audit -f cyclonedx-json` | +| CI/CD with GitHub Security tab | `trivy` or `grype` (SARIF support) | + +## Related Resources + +- [Trivy Documentation](https://aquasecurity.github.io/trivy/) +- [Grype Documentation](https://github.com/anchore/grype) +- [npm audit Documentation](https://docs.npmjs.com/cli/v10/commands/npm-audit) +- [Bun audit Documentation](https://bun.com/docs/install/audit) +- [pip-audit Documentation](https://github.com/pypa/pip-audit) +- [GitHub Dependabot](https://docs.github.com/en/code-security/dependabot) (complementary tool) diff --git a/plugins/dep-vulnerability-scanner/commands/ci-workflow.md b/plugins/dep-vulnerability-scanner/commands/ci-workflow.md new file mode 100644 index 0000000..9a3fe58 --- /dev/null +++ b/plugins/dep-vulnerability-scanner/commands/ci-workflow.md @@ -0,0 +1,262 @@ +Generate a GitHub Actions workflow for dependency vulnerability scanning: + +1. Ask the user about their project: + - Project type (JavaScript/npm, Bun, Python, multi-language, container) + - Preferred scanner(s) + - Whether to fail builds on vulnerabilities + - Minimum severity threshold (low, medium, high, critical) + - Whether to upload results to GitHub Security tab + +2. Generate the appropriate workflow file(s) in `.github/workflows/` + +## Example Workflows + +### Trivy Filesystem Scan (Universal) +```yaml +name: Security Scan + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '0 0 * * 0' # Weekly scan + +permissions: + contents: read + security-events: write + +jobs: + trivy-scan: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Trivy vulnerability scanner + uses: aquasecurity/trivy-action@0.28.0 + with: + scan-type: 'fs' + scan-ref: '.' + severity: 'HIGH,CRITICAL' + format: 'sarif' + output: 'trivy-results.sarif' + + - name: Upload Trivy scan results + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: 'trivy-results.sarif' +``` + +### Grype Scan (Universal) +```yaml +name: Grype Security Scan + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + security-events: write + +jobs: + grype-scan: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Scan with Grype + uses: anchore/scan-action@v6 + id: scan + with: + path: "." + fail-build: true + severity-cutoff: high + + - name: Upload SARIF report + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: ${{ steps.scan.outputs.sarif }} +``` + +### npm audit (JavaScript/Node.js) +```yaml +name: npm Security Audit + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + npm-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run npm audit + run: npm audit --audit-level=high +``` + +### Bun audit (Bun projects) +```yaml +name: Bun Security Audit + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + bun-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install dependencies + run: bun install + + - name: Run bun audit + run: bun audit --audit-level=high +``` + +### pip-audit (Python) +```yaml +name: Python Security Audit + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + pip-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Run pip-audit + uses: pypa/gh-action-pip-audit@v1.1.0 + with: + inputs: requirements.txt +``` + +### pip-audit with uv (Python/uv projects) +```yaml +name: Python Security Audit (uv) + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + pip-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Run pip-audit via uvx + run: uvx pip-audit -r requirements.txt +``` + +### Multi-scanner workflow (comprehensive) +```yaml +name: Comprehensive Security Scan + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '0 0 * * 0' + +permissions: + contents: read + security-events: write + +jobs: + trivy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Trivy scan + uses: aquasecurity/trivy-action@0.28.0 + with: + scan-type: 'fs' + scan-ref: '.' + severity: 'HIGH,CRITICAL' + format: 'sarif' + output: 'trivy-results.sarif' + - uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: 'trivy-results.sarif' + category: 'trivy' + + grype: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: anchore/scan-action@v6 + id: scan + with: + path: "." + fail-build: false + severity-cutoff: high + - uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: ${{ steps.scan.outputs.sarif }} + category: 'grype' +``` + +3. Create the workflow file in the project's `.github/workflows/` directory + +4. Explain the workflow configuration and how to customize it + +5. Suggest enabling GitHub's Dependabot as a complementary security measure diff --git a/plugins/dep-vulnerability-scanner/commands/compare.md b/plugins/dep-vulnerability-scanner/commands/compare.md new file mode 100644 index 0000000..99a9824 --- /dev/null +++ b/plugins/dep-vulnerability-scanner/commands/compare.md @@ -0,0 +1,93 @@ +Compare dependency vulnerability scanning tools to help choose the right one: + +Present this comparison table and help the user decide based on their needs: + +## Tool Comparison Matrix + +| Feature | Trivy | Grype | npm audit | bun audit | pip-audit | +|---------|-------|-------|-----------|-----------|-----------| +| **Ecosystems** | Multi (OS, containers, code) | Multi (containers, filesystems) | JavaScript/npm | JavaScript/Bun | Python | +| **Scan Speed** | Fast | Fast | Fast | Fast | Medium | +| **Auto-fix** | No | No | Yes | No | Yes | +| **SBOM Support** | Generate & scan | Scan only | No | No | Generate (CycloneDX) | +| **Offline Mode** | Yes (with cached DB) | Yes (with cached DB) | No | No | Limited | +| **CI Integration** | Excellent | Excellent | Good | Good | Good | +| **Output Formats** | JSON, SARIF, table, template | JSON, SARIF, CycloneDX | JSON, text | JSON, text | JSON, CycloneDX, Markdown | + +## When to Use Each Tool + +### Trivy - Best for: +- Container/Docker image scanning +- Kubernetes environments +- Multi-language monorepos +- Infrastructure-as-Code scanning +- Secret detection +- Compliance requirements (generates SBOMs) + +### Grype - Best for: +- Focused vulnerability scanning +- SBOM-based security audits +- Container registries +- When you need EPSS/KEV risk scoring +- Lightweight alternative to Trivy + +### npm audit - Best for: +- Pure Node.js/npm projects +- Quick checks during development +- Auto-fixing vulnerabilities +- Projects using package-lock.json + +### bun audit - Best for: +- Bun.js projects +- Fast JavaScript dependency checks +- Projects using bun.lock + +### pip-audit - Best for: +- Python projects +- Virtual environment auditing +- Integration with pip/pipx/uv workflows +- When you need CycloneDX SBOM output + +## Recommendation Flow + +1. **Single-language project?** + - JavaScript/npm -> npm audit (built-in, has auto-fix) + - Bun -> bun audit (built-in, fast) + - Python -> pip-audit (or uvx pip-audit if using uv) + +2. **Multi-language or container project?** + - Use Trivy for comprehensive scanning + - Add Grype for focused vulnerability checks + +3. **CI/CD Pipeline?** + - Trivy or Grype for comprehensive SARIF reports + - Native tools (npm/bun/pip-audit) for language-specific jobs + +4. **Need auto-remediation?** + - npm audit fix for JavaScript + - pip-audit --fix for Python + - Others require manual updates + +## Pros and Cons Summary + +### Trivy +**Pros:** Most comprehensive, scans everything (vulns, secrets, IaC), excellent CI support +**Cons:** Larger download, more complex output, no auto-fix + +### Grype +**Pros:** Fast, focused, good SBOM support, risk scoring with EPSS/KEV +**Cons:** No auto-fix, fewer scan types than Trivy + +### npm audit +**Pros:** Built-in, auto-fix capability, GitHub Advisory Database +**Cons:** JavaScript only, requires network + +### bun audit +**Pros:** Built-in to Bun, very fast, compatible with npm registry +**Cons:** JavaScript only, no auto-fix, newer tool + +### pip-audit +**Pros:** Python-focused, auto-fix, multiple vuln databases (PyPI, OSV) +**Cons:** Slower for large projects, Python only + +Ask the user about their project type and requirements, then recommend the best tool(s). diff --git a/plugins/dep-vulnerability-scanner/commands/scan.md b/plugins/dep-vulnerability-scanner/commands/scan.md new file mode 100644 index 0000000..cf44c0f --- /dev/null +++ b/plugins/dep-vulnerability-scanner/commands/scan.md @@ -0,0 +1,66 @@ +Scan the current project for dependency vulnerabilities using the appropriate tool: + +1. Detect project type by checking for manifest files: + - package.json + bun.lock -> Use `bun audit` + - package.json + package-lock.json -> Use `npm audit` + - pyproject.toml, requirements.txt, or setup.py -> Use `pip-audit` + - Any project -> Can use `trivy fs .` or `grype .` (universal scanners) + +2. Check if the selected tool is installed, suggest installation if not + +3. Run the scan with appropriate options: + +## For JavaScript/Node.js projects (npm): +```bash +npm audit # Basic scan +npm audit --json # JSON output for CI +npm audit --audit-level=high # Only high+ severity +npm audit --production # Production deps only +npm audit fix # Auto-fix vulnerabilities +npm audit fix --dry-run # Preview fixes +``` + +## For Bun projects: +```bash +bun audit # Basic scan +bun audit --json # JSON output +bun audit --audit-level=high # High+ severity only +bun audit --prod # Production deps only +bun audit --ignore CVE-XXXX-XXXXX # Ignore specific CVE +``` + +## For Python projects: +```bash +pip-audit # Scan current environment +pip-audit -r requirements.txt # Scan requirements file +pip-audit --fix # Auto-fix vulnerabilities +pip-audit -f json # JSON output +pip-audit -f cyclonedx-json # SBOM output +pip-audit --desc # Include descriptions +pip-audit -s osv # Use OSV database +uvx pip-audit # Run via uv (if uv is used) +``` + +## For universal scanning (any project): +```bash +# Trivy - scans OS packages, language deps, secrets, IaC +trivy fs . # Scan filesystem +trivy fs --scanners vuln . # Vulnerabilities only +trivy fs --severity HIGH,CRITICAL . +trivy fs -f json -o results.json . # JSON output + +# Grype - focused vulnerability scanner +grype . # Scan directory +grype . --only-fixed # Show fixable vulns +grype . -o json # JSON output +grype . --fail-on high # Exit 1 on high severity +``` + +4. Present results with severity levels and remediation advice + +5. If vulnerabilities found, suggest: + - Running fix commands where available (npm audit fix, pip-audit --fix) + - Updating specific packages manually + - Adding CI workflow to prevent future issues + +Ask the user which tool they prefer if multiple are applicable. diff --git a/plugins/dep-vulnerability-scanner/commands/setup.md b/plugins/dep-vulnerability-scanner/commands/setup.md new file mode 100644 index 0000000..3867671 --- /dev/null +++ b/plugins/dep-vulnerability-scanner/commands/setup.md @@ -0,0 +1,107 @@ +Install and configure dependency vulnerability scanning tools: + +1. Ask the user which tools they want to install: + - Trivy (universal scanner for containers, filesystems, repos) + - Grype (focused vulnerability scanner) + - pip-audit (Python-specific) + - npm audit (built into npm, no installation needed) + - bun audit (built into Bun, no installation needed) + +2. Detect the operating system and available package managers + +3. Install the requested tools: + +## Trivy Installation + +### macOS (Homebrew) +```bash +brew install trivy +``` + +### Linux (Debian/Ubuntu) +```bash +sudo apt-get install wget apt-transport-https gnupg lsb-release +wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add - +echo deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/trivy.list +sudo apt-get update && sudo apt-get install trivy +``` + +### Linux (RHEL/CentOS) +```bash +sudo rpm -ivh https://github.com/aquasecurity/trivy/releases/download/v0.50.0/trivy_0.50.0_Linux-64bit.rpm +``` + +### Docker (any platform) +```bash +docker pull aquasec/trivy +# Usage: docker run --rm -v $(pwd):/project aquasec/trivy fs /project +``` + +### Binary (any platform) +```bash +curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin +``` + +## Grype Installation + +### macOS (Homebrew) +```bash +brew install grype +``` + +### Linux/macOS (install script) +```bash +curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sudo sh -s -- -b /usr/local/bin +``` + +### Docker (any platform) +```bash +docker pull anchore/grype +# Usage: docker run --rm -v $(pwd):/project anchore/grype /project +``` + +### Windows (Chocolatey) +```powershell +choco install grype +``` + +## pip-audit Installation + +### Using pip +```bash +python -m pip install pip-audit +``` + +### Using pipx (recommended for CLI tools) +```bash +pipx install pip-audit +``` + +### Using uv (if using uv for Python) +```bash +# Run directly without installing: +uvx pip-audit + +# Or install globally: +uv tool install pip-audit +``` + +### Using conda +```bash +conda install -c conda-forge pip-audit +``` + +## Verification + +4. After installation, verify each tool: +```bash +trivy --version +grype version +pip-audit --version +npm audit --version # Part of npm +bun audit --version # Part of bun (bun --version) +``` + +5. Suggest running an initial scan to test the setup + +Note: npm audit and bun audit are built into their respective package managers and don't require separate installation.