trivy

# Aqua Trivy - Comprehensive Security Scanner ## When to Use Trivy **Ideal scenarios:** - Container image vulnerability scanning - Filesystem and repository scanning - Infrastructure-as-Code (IaC) misconfiguration detection - Secrets detection in code and images - Software Bill of Materials (SBOM) generation - License compliance checking - Kubernetes cluster security assessment - CI/CD security gates **Complements other tools:** - Use alongside Semgrep/CodeQL for application code analysis - Combine with KICS for additional IaC coverage - Use with Gitleaks for dedicated secrets scanning - Pair with OSV-Scanner/Depscan for enhanced SCA ## When NOT to Use Do NOT use this skill for: - Deep application code vulnerability analysis (use Semgrep or CodeQL) - API endpoint discovery (use Noir) - Advanced SAST with taint tracking (use CodeQL) - Penetration testing (use specialized tools) ## Installation ### Homebrew (Recommended for macOS/Linux) ```bash # macOS and Linux (preferred method) brew install trivy # Verify installation trivy --version ``` ### Other Installation Methods ```bash # Docker docker pull aquasec/trivy:latest # Install script (Linux/macOS) curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin # apt (Debian/Ubuntu) sudo apt-get install wget apt-transport-https gnupg lsb-release wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list sudo apt-get update sudo apt-get install trivy # yum/dnf (RHEL/CentOS/Fedora) sudo rpm -ivh https://github.com/aquasecurity/trivy/releases/latest/download/trivy_*_Linux-64bit.rpm # Windows (Chocolatey) choco install trivy # Windows (Scoop) scoop install trivy # Go install go install github.com/aquasecurity/trivy/cmd/trivy@latest ``` ## Core Workflow ### 1. Quick Scan ```bash # Scan container image trivy image nginx:latest # Scan filesystem/project directory trivy fs /path/to/project # Scan current directory trivy fs . # Scan remote git repository trivy repo https://github.com/owner/repo # Scan Kubernetes cluster trivy k8s --report summary cluster ``` ### 2. SARIF Output ```bash # Container image to SARIF trivy image --format sarif --output results.sarif nginx:latest # Filesystem to SARIF trivy fs --format sarif --output results.sarif /path/to/project # Repository to SARIF trivy repo --format sarif --output results.sarif https://github.com/owner/repo # IaC scan to SARIF trivy config --format sarif --output iac-results.sarif /path/to/terraform ``` ### 3. Specific Scanner Types ```bash # Vulnerability scanning only trivy image --scanners vuln nginx:latest # Secrets scanning only trivy fs --scanners secret /path/to/project # Misconfiguration scanning only trivy config /path/to/iac # License scanning trivy image --scanners license nginx:latest # Combined scanners trivy fs --scanners vuln,secret,misconfig /path/to/project ``` ### 4. SBOM Generation ```bash # Generate CycloneDX SBOM trivy image --format cyclonedx --output sbom.json nginx:latest # Generate SPDX SBOM trivy image --format spdx-json --output sbom.spdx.json nginx:latest # Scan existing SBOM for vulnerabilities trivy sbom sbom.json ``` ## Scan Targets | Target | Command | Description | |--------|---------|-------------| | **Container Image** | `trivy image IMAGE` | Scan container images from registries or local | | **Filesystem** | `trivy fs PATH` | Scan local project directory | | **Repository** | `trivy repo URL` | Scan remote git repository | | **Kubernetes** | `trivy k8s` | Scan Kubernetes cluster resources | | **IaC/Config** | `trivy config PATH` | Scan IaC files (Terraform, CloudFormation, etc.) | | **SBOM** | `trivy sbom FILE` | Scan existing SBOM file | | **VM Image** | `trivy vm IMAGE` | Scan virtual machine images | | **Rootfs** | `trivy rootfs PATH` | Scan root filesystem | ## Supported Ecosystems ### Package Managers | Ecosystem | Manifest/Lock Files | |-----------|---------------------| | **npm** | package.json, package-lock.json, yarn.lock, pnpm-lock.yaml | | **Python** | requirements.txt, Pipfile.lock, poetry.lock, setup.py | | **Go** | go.mod, go.sum | | **Rust** | Cargo.lock | | **Java** | pom.xml, build.gradle, gradle.lockfile | | **Ruby** | Gemfile.lock | | **PHP** | composer.lock | | **.NET** | packages.lock.json, *.deps.json | | **Swift** | Package.resolved | | **Dart** | pubspec.lock | | **Elixir** | mix.lock | | **Conan (C/C++)** | conan.lock | ### IaC Platforms | Platform | File Types | |----------|------------| | **Terraform** | *.tf, *.tf.json | | **CloudFormation** | *.yaml, *.json (CFN templates) | | **Kubernetes** | *.yaml (K8s manifests) | | **Helm** | Chart.yaml, values.yaml | | **Docker** | Dockerfile | | **Azure ARM** | *.json (ARM templates) | ## Output Formats ```bash # Table format (default, human-readable) trivy image nginx:latest # JSON output trivy image --format json --output results.json nginx:latest # SARIF output (for CI/CD integration) trivy image --format sarif --output results.sarif nginx:latest # CycloneDX SBOM trivy image --format cyclonedx --output sbom.cdx.json nginx:latest # SPDX SBOM trivy image --format spdx-json --output sbom.spdx.json nginx:latest # GitHub dependency snapshot trivy image --format github nginx:latest # Template output (custom) trivy image --format template --template "@contrib/html.tpl" --output report.html nginx:latest ``` ## Advanced Options ### Severity Filtering ```bash # Critical and High only trivy image --severity CRITICAL,HIGH nginx:latest # All severities (default) trivy image --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL nginx:latest # Exit with error on findings trivy image --exit-code 1 --severity HIGH,CRITICAL nginx:latest ``` ### Vulnerability Options ```bash # Show only fixed vulnerabilities trivy image --ignore-unfixed nginx:latest # Ignore specific vulnerabilities trivy image --ignorefile .trivyignore nginx:latest # Skip vulnerability database update trivy image --skip-db-update nginx:latest # Offline mode (use cached DB) trivy image --offline-scan nginx:latest ``` ### Image Scanning Options ```bash # Scan from tar archive trivy image --input image.tar # Scan specific platform trivy image --platform linux/amd64 nginx:latest # Scan with image config trivy image --image-config-scanners config nginx:latest # Skip files by pattern trivy image --skip-files "/path/to/skip" nginx:latest # Skip directories trivy image --skip-dirs node_modules nginx:latest ``` ### Secret Scanning ```bash # Enable secret scanning trivy fs --scanners secret /path/to/project # Custom secret config trivy fs --scanners secret --secret-config trivy-secret.yaml /path/to/project ``` ## CI/CD Integration (GitHub Actions) ```yaml name: Trivy Security Scan on: push: branches: [main] pull_request: schedule: - cron: '0 0 * * *' # Daily jobs: trivy-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run Trivy vulnerability scanner (filesystem) uses: aquasecurity/trivy-action@master with: scan-type: 'fs' scan-ref: '.' format: 'sarif' output: 'trivy-fs-results.sarif' severity: 'CRITICAL,HIGH' - name: Upload Trivy SARIF (filesystem) if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'trivy-fs-results.sarif' category: trivy-fs - name: Run Trivy config scanner (IaC) uses: aquasecurity/trivy-action@master with: scan-type: 'config' scan-ref: '.' format: 'sarif' output: 'trivy-config-results.sarif' - name: Upload Trivy SARIF (config) if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'trivy-config-results.sarif' category: trivy-config container-scan: runs-on: ubuntu-latest needs: [build] # Assuming a build job creates the image steps: - name: Run Trivy container scan uses: aquasecurity/trivy-action@master with: image-ref: 'myapp:${{ github.sha }}' format: 'sarif' output: 'trivy-image-results.sarif' severity: 'CRITICAL,HIGH' ignore-unfixed: true - name: Upload Trivy SARIF (image) if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: 'trivy-image-results.sarif' category: trivy-image ``` ## Configuration ### Config File (trivy.yaml) ```yaml # trivy.yaml severity: - CRITICAL - HIGH - MEDIUM exit-code: 1 ignore-unfixed: true # Vulnerability settings vulnerability: type: - os - library # Secret scanning secret: config: trivy-secret.yaml # Misconfiguration settings misconfiguration: terraform: excluded-checks: - AVD-AWS-0013 # Skip patterns skip-files: - "**/*.test.js" - "**/testdata/**" skip-dirs: - node_modules - .git - vendor # Cache settings cache: dir: /tmp/trivy-cache ``` ### Ignore File (.trivyignore) ```text # .trivyignore # Ignore specific CVEs CVE-2023-12345 CVE-2023-67890 # Ignore with expiration CVE-2024-11111 exp:2025-06-01 # Ignore specific package vulnerabilities CVE-2024-22222 pkg:lodash # Secret ignore patterns aws-access-key-id ``` ### Secret Config (trivy-secret.yaml) ```yaml # trivy-secret.yaml rules: - id: custom-api-key category: general title: Custom API Key severity: HIGH regex: 'CUSTOM_API_KEY[=:]\s*["\']?([A-Za-z0-9]{32})["\']?' allow-rules: - id: allow-test-secrets description: Allow test/mock secrets path: '.*test.*|.*mock.*' ``` ## Common Use Cases ### 1. Container Security Pipeline ```bash # Build image docker build -t myapp:latest . # Scan for vulnerabilities trivy image --severity HIGH,CRITICAL --exit-code 1 myapp:latest # Generate SBOM trivy image --format cyclonedx --output sbom.json myapp:latest # Export SARIF for tracking trivy image --format sarif --output results.sarif myapp:latest ``` ### 2. IaC Security Review ```bash # Scan Terraform files trivy config --format sarif --output iac-results.sarif ./terraform # Scan Kubernetes manifests trivy config --format sarif --output k8s-results.sarif ./k8s # Scan Dockerfiles trivy config --format sarif --output docker-results.sarif . ``` ### 3. Repository Security Audit ```bash # Full repository scan trivy fs --scanners vuln,secret,misconfig \ --format sarif --output full-scan.sarif \ /path/to/project # Scan remote repository trivy repo --format sarif --output repo-scan.sarif \ https://github.com/owner/repo ``` ### 4. Kubernetes Cluster Assessment ```bash # Summary report trivy k8s --report summary cluster # Detailed scan with SARIF trivy k8s --format sarif --output k8s-cluster.sarif cluster # Scan specific namespace trivy k8s --namespace production --report all cluster ``` ### 5. Supply Chain Security ```bash # Generate SBOM trivy image --format cyclonedx --output sbom.cdx.json myapp:latest # Scan SBOM for vulnerabilities trivy sbom sbom.cdx.json # Sign SBOM with cosign (if available) cosign sign-blob --key cosign.key sbom.cdx.json ```