ABOUTME: Security vulnerability scanning skill using Trivy for pre-commit validation

ABOUTME: Enforces blocking of CRITICAL and HIGH severity vulnerabilities across all scan targets

Trivy Security Scanning Skill

Tool: Trivy

Overview

This skill enforces security vulnerability scanning using Trivy before code is committed. CRITICAL and HIGH severity vulnerabilities MUST be resolved before commit.

When to Use

Trigger	Action
New dependency added	Scan filesystem for vulnerabilities
Dockerfile modified	Scan container image
go.mod/go.sum changed	Scan Go dependencies
requirements.txt/pyproject.toml changed	Scan Python dependencies
package.json/package-lock.json changed	Scan Node.js dependencies
Terraform files changed	Scan IaC misconfigurations
Before commit with dependency changes	MANDATORY full scan

Quick Reference

# Filesystem scan (most common)
trivy fs --severity CRITICAL,HIGH --exit-code 1 .

# Container image scan
trivy image --severity CRITICAL,HIGH --exit-code 1 IMAGE_NAME

# IaC scan (Terraform, CloudFormation, etc.)
trivy config --severity CRITICAL,HIGH --exit-code 1 .

# Generate SBOM
trivy fs --format spdx-json --output sbom.json .

Severity Policy

Severity	Action	Commit Allowed
CRITICAL	BLOCK - Must fix immediately	NO
HIGH	BLOCK - Must fix or upgrade	NO
MEDIUM	WARN - Review and plan remediation	YES (with warning)
LOW	INFO - Document in backlog	YES

Workflow: Pre-Commit Security Scan

Step 1: Identify Scan Targets

Check what changed to determine scan type:

# Check for dependency file changes
git diff --cached --name-only | grep -E "(go\.(mod|sum)|requirements.*\.txt|pyproject\.toml|package.*\.json|Gemfile|Cargo\.(toml|lock)|pom\.xml|build\.gradle)"

# Check for Dockerfile changes
git diff --cached --name-only | grep -iE "(Dockerfile|\.dockerfile|docker-compose)"

# Check for IaC changes
git diff --cached --name-only | grep -E "\.(tf|hcl|yaml|yml)$"

Step 2: Run Appropriate Scan

Filesystem Scan (Dependencies)

trivy fs \
    --severity CRITICAL,HIGH \
    --exit-code 1 \
    --ignore-unfixed \
    --format table \
    .

Container Image Scan

# Build the image first if needed
docker build -t local-scan:latest .

# Scan the image
trivy image \
    --severity CRITICAL,HIGH \
    --exit-code 1 \
    --ignore-unfixed \
    --format table \
    local-scan:latest

IaC Configuration Scan

trivy config \
    --severity CRITICAL,HIGH \
    --exit-code 1 \
    --format table \
    .

Step 3: Handle Results

If scan passes (exit code 0):

• Proceed with commit

If scan fails (exit code 1):

1. Review the vulnerability report
2. Identify affected packages
3. Apply remediation (see below)
4. Re-scan to verify fix
5. Only then proceed with commit

Remediation Strategies

Strategy 1: Upgrade Dependency

The preferred approach; upgrade to a patched version.

# Go
go get package@latest
go mod tidy

# Python (uv)
uv pip install --upgrade package

# Python (pip)
pip install --upgrade package

# Node.js
npm update package
# or
npm install package@latest

# Rust
cargo update -p package

Strategy 2: Use Trivy to Find Fixed Version

# Show which version fixes the vulnerability
trivy fs --severity CRITICAL,HIGH --format json . | jq '.Results[].Vulnerabilities[] | {pkg: .PkgName, installed: .InstalledVersion, fixed: .FixedVersion}'

Strategy 3: Exclude False Positives (With Justification)

Only when vulnerability is confirmed false positive or not applicable.

Create .trivyignore file:

# Vulnerability ID with justification comment
# CVE-2023-XXXXX: Not applicable - we don't use affected feature (code path X)
CVE-2023-XXXXX

WARNING: Every exclusion MUST have a documented justification.

Strategy 4: Vendor Override (Last Resort)

For transitive dependencies that cannot be directly upgraded:

# Go: Use replace directive in go.mod
replace vulnerable/package => vulnerable/package vX.Y.Z-fixed

# Node.js: Use overrides in package.json
{
  "overrides": {
    "vulnerable-package": "^X.Y.Z"
  }
}

Scan Output Examples

Clean Scan

2024-01-09T10:00:00.000Z  INFO  Vulnerability scanning enabled
2024-01-09T10:00:01.000Z  INFO  Detected OS: alpine
2024-01-09T10:00:02.000Z  INFO  Number of PL managers: 1
2024-01-09T10:00:03.000Z  INFO  No vulnerabilities found

Total: 0 (CRITICAL: 0, HIGH: 0)

Failed Scan (Blocking)

package-lock.json (npm)
=======================
Total: 2 (CRITICAL: 1, HIGH: 1)

+-----------+------------------+----------+-------------------+---------------+
|  LIBRARY  | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION |
+-----------+------------------+----------+-------------------+---------------+
| lodash    | CVE-2021-23337   | CRITICAL | 4.17.15           | 4.17.21       |
| minimist  | CVE-2021-44906   | HIGH     | 1.2.5             | 1.2.6         |
+-----------+------------------+----------+-------------------+---------------+

Integration with Pre-Commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: trivy-fs
        name: Trivy Filesystem Scan
        entry: trivy fs --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed .
        language: system
        pass_filenames: false
        stages: [commit]

Or create a Git hook directly at .git/hooks/pre-commit:

#!/bin/bash
set -euo pipefail

echo "[SECURITY] Running Trivy vulnerability scan..."

if ! command -v trivy &> /dev/null; then
    echo "[ERROR] Trivy is not installed. Install with: brew install trivy"
    exit 1
fi

# Check for dependency file changes
DEPS_CHANGED=$(git diff --cached --name-only | grep -E "(go\.(mod|sum)|requirements.*\.txt|pyproject\.toml|package.*\.json|Gemfile|Cargo\.(toml|lock))" || true)

if [[ -n "${DEPS_CHANGED}" ]]; then
    echo "[SECURITY] Dependency files changed, scanning for vulnerabilities..."

    if ! trivy fs --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed .; then
        echo ""
        echo "=========================================="
        echo "[BLOCKED] CRITICAL or HIGH vulnerabilities found!"
        echo "Fix vulnerabilities before committing."
        echo "=========================================="
        exit 1
    fi
fi

# Check for Dockerfile changes
DOCKER_CHANGED=$(git diff --cached --name-only | grep -iE "(Dockerfile|\.dockerfile)" || true)

if [[ -n "${DOCKER_CHANGED}" ]]; then
    echo "[SECURITY] Dockerfile changed, building and scanning image..."

    # Build image for scanning (adjust tag as needed)
    docker build -t pre-commit-scan:latest . 2>/dev/null || true

    if docker image inspect pre-commit-scan:latest &>/dev/null; then
        if ! trivy image --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed pre-commit-scan:latest; then
            echo ""
            echo "=========================================="
            echo "[BLOCKED] Container image has vulnerabilities!"
            echo "Fix vulnerabilities before committing."
            echo "=========================================="
            docker rmi pre-commit-scan:latest 2>/dev/null || true
            exit 1
        fi
        docker rmi pre-commit-scan:latest 2>/dev/null || true
    fi
fi

echo "[SECURITY] Vulnerability scan passed."

Advanced Options

JSON Output for CI/CD

trivy fs \
    --severity CRITICAL,HIGH \
    --exit-code 1 \
    --format json \
    --output trivy-report.json \
    .

SARIF Output for GitHub Security

trivy fs \
    --severity CRITICAL,HIGH \
    --format sarif \
    --output trivy-results.sarif \
    .

Scan Specific Language

# Only scan Go dependencies
trivy fs --scanners vuln --pkg-types library --file-patterns "go.mod" .

# Only scan Python dependencies
trivy fs --scanners vuln --pkg-types library --file-patterns "requirements.txt,pyproject.toml" .

Offline Scanning

# Download vulnerability database
trivy --download-db-only

# Scan offline
trivy fs --skip-update --offline-scan .

Trivy Installation

# macOS
brew install trivy

# Linux (Debian/Ubuntu)
sudo apt-get install trivy

# Linux (RHEL/CentOS)
sudo yum install trivy

# Docker
docker pull aquasec/trivy

# Binary download
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

Checklist

Before committing code with dependency or container changes:

• Trivy is installed and accessible
• Ran trivy fs --severity CRITICAL,HIGH --exit-code 1 .
• No CRITICAL vulnerabilities present
• No HIGH vulnerabilities present (or documented exception)
• Any .trivyignore entries have documented justification
• Container images (if applicable) scanned and clean
• IaC configurations (if applicable) scanned and clean

Claude Code Integration

This skill integrates with Claude Code's commit workflow. See scm/references/commit-workflow.md for the full workflow.

Automatic Invocation

Claude Code automatically invokes Trivy scanning when committing changes to:

File Pattern	Scan Type
go.mod, go.sum	trivy fs
requirements*.txt, pyproject.toml	trivy fs
package*.json, yarn.lock	trivy fs
Dockerfile*, docker-compose*.yml	trivy config + trivy image
*.tf, *.hcl	trivy config

Workflow Integration

User: "/commit-push" or "/commit-push-pr"
           │
           ▼
┌─────────────────────────────┐
│ Detect security-relevant    │
│ files in staged changes     │
└──────────────┬──────────────┘
               │
    ┌──────────┴──────────┐
    ▼                     ▼
[Triggers found]    [No triggers]
    │                     │
    ▼                     │
┌─────────────────┐       │
│ Run Trivy scans │       │
└────────┬────────┘       │
         │                │
  ┌──────┴──────┐         │
  ▼             ▼         │
[VULN]       [CLEAN]      │
  │             │         │
  ▼             └────┬────┘
┌──────────────┐     │
│ Generate     │     │
│ Remediation  │     │
│ Plan         │     │
└──────────────┘     │
                     ▼
              ┌────────────┐
              │ Proceed to │
              │ commit     │
              └────────────┘

Remediation Plan Format

When vulnerabilities are found, Claude Code generates a remediation plan:

# Vulnerability Remediation Plan

## Summary
- **Total**: X vulnerabilities (CRITICAL: Y, HIGH: Z)
- **Scan Type**: filesystem / config / image

## Findings

| Severity | Package | CVE | Installed | Fixed |
|----------|---------|-----|-----------|-------|
| CRITICAL | example | CVE-XXXX-YYYY | 1.0.0 | 1.0.1 |

## Remediation Steps

1. Upgrade `example` to version 1.0.1:
   ```bash
   npm install example@1.0.1

2. Verify fix:

   trivy fs --severity CRITICAL,HIGH --exit-code 1 .
   

### Related Skills

| Skill | Purpose |
|-------|---------|
| `scm/SKILL.md` | Git workflow, Conventional Commits |
| `scm/references/commit-workflow.md` | Full secure commit workflow |
| `gemini-review/SKILL.md` | Code review (after security scan) |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `trivy: command not found` | Install Trivy: `brew install trivy` |
| Slow scan | Use `--skip-update` after initial DB download |
| False positive | Add to `.trivyignore` with justification |
| Transitive dependency | Use package manager override mechanism |
| Old vulnerability DB | Run `trivy --download-db-only` to update |

## Additional Resources

- [Trivy Documentation](https://trivy.dev/latest/)
- [Trivy GitHub](https://github.com/aquasecurity/trivy)
- [CVE Database](https://cve.mitre.org/)
- [NVD - National Vulnerability Database](https://nvd.nist.gov/)