Trivy for Enterprise DevSecOps: Architecture, Deployment, and Secure CI/CD Integration
Prerequisites
- Familiarity with container images and OCI registries
- Working knowledge of CI/CD pipelines and YAML
Steps
Trivy is a lightweight but enterprise-capable security scanner for containers, filesystems, Git repositories, Kubernetes, and infrastructure as code. This guide explains how to deploy Trivy at scale, integrate it into CI/CD, and harden operations for regulated environments.
Overview
Trivy is an open-source security scanner from Aqua Security that detects vulnerabilities, misconfigurations, secrets, licenses, and software bill of materials (SBOM) issues across container images, Kubernetes, repositories, and IaC templates. Enterprises adopt it because it is fast, supports multiple artifact types through a single CLI, and fits well into shift-left DevSecOps programs where security checks must run consistently in developer workstations, CI pipelines, registries, and Kubernetes admission workflows.
Key enterprise use cases include:
- Container image scanning before promotion to production
- IaC scanning for Terraform, Kubernetes manifests, Helm charts, and CloudFormation
- SBOM generation and vulnerability correlation for software supply chain controls
- Kubernetes posture checks for runtime cluster hygiene
- Policy enforcement in CI/CD using severity thresholds and exit codes
Architecture
Trivy uses a local or remote scan model. The CLI can scan directly on developer laptops and CI runners, while enterprise deployments often centralize cache and database updates to reduce internet egress and improve consistency.
Core components:
- Trivy CLI: executes scans and renders reports
- Vulnerability DB: downloaded from OCI registries and cached locally
- Java DB and checks bundle: enriches language and misconfiguration analysis
- Cache backend: filesystem or Redis for shared caching in server mode
- CI/CD platform: GitHub Actions, GitLab CI, Jenkins, Azure DevOps
View as text
[Developer Workstation] ---- 1. trivy image/fs/config ----> [Local Cache] [CI Runner] ---- 2. trivy scan request ----> [Trivy Server] [Trivy Server] ---- 3. fetch DB updates ----> [OCI Registry] [Trivy Server] ---- 4. return findings JSON/SARIF ----> [CI Runner] [CI Runner] | v [Artifact Repository] ---- 5. image pull ----> [Container Registry] [CI Runner] ---- 6. policy gate on severity/exit-code ----> [Deployment Pipeline]
Deployment models:
- Standalone CLI: simplest, ideal for small teams and ephemeral runners
- Client/server: better for large CI fleets; centralizes cache and DB downloads
- Air-gapped: mirror Trivy databases into internal OCI registries and point clients to internal sources
Implementation Guide
1. Install Trivy on Linux
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin
trivy --version
2. Pre-download databases for controlled environments
trivy image --download-db-only
trivy image --download-java-db-only
trivy config --download-checks-bundle-only
3. Create enterprise config
# trivy.yaml
cache-dir: /var/lib/trivy
format: table
severity:
- HIGH
- CRITICAL
ignore-unfixed: true
vuln-type:
- os
- library
scanners:
- vuln
- secret
- misconfig
timeout: 10m
exit-code: 1
4. Scan a container image in CI
trivy image --config trivy.yaml --input app-image.tar --format sarif --output trivy.sarif
trivy image --config trivy.yaml registry.example.com/payments/api:1.24.7
5. Scan Terraform and Kubernetes manifests
trivy config --config trivy.yaml infra/
trivy k8s --report summary cluster
6. Run Trivy in server mode with Redis cache
docker run -d --name trivy-redis -p 6379:6379 redis:7-alpine
docker run -d --name trivy-server -p 4954:4954 -v /var/lib/trivy:/root/.cache/trivy aquasec/trivy:latest server --listen 0.0.0.0:4954 --cache-backend redis://host.docker.internal:6379
trivy client --remote http://127.0.0.1:4954 image registry.example.com/payments/api:1.24.7
Code Examples
Example 1: GitHub Actions pipeline gate
name: trivy-scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aquasecurity/trivy-action@0.24.0
with:
scan-type: 'fs'
scan-ref: '.'
severity: 'HIGH,CRITICAL'
ignore-unfixed: true
exit-code: '1'
Example 2: Generate SBOM and JSON report
trivy image --format cyclonedx --output sbom.cdx.json registry.example.com/payments/api:1.24.7
trivy image --format json --output findings.json registry.example.com/payments/api:1.24.7
Example 3: Parse critical findings in Python
import json
with open('findings.json') as f:
data = json.load(f)
critical = 0
for result in data.get('Results', []):
for vuln in result.get('Vulnerabilities', []) or []:
if vuln.get('Severity') == 'CRITICAL':
critical += 1
print({'critical_findings': critical})
if critical > 0:
raise SystemExit(1)
Security Hardening
- Mirror databases internally to avoid uncontrolled outbound access and improve provenance.
- Use least privilege for CI runners; scanners should read artifacts but not push to production registries.
- Protect cache storage with filesystem permissions or Redis ACLs and TLS where supported by your platform.
- Sign and verify images before and after scanning using enterprise supply chain controls such as Cosign.
- Store reports securely because SARIF and JSON outputs may reveal package names, paths, and secrets metadata.
- Pin Trivy versions in CI to prevent unexpected rule changes from breaking release gates.
Comparison
| Feature | Trivy | Snyk Container | Prisma Cloud Compute |
|---|---|---|---|
| Pricing | Open-source core; enterprise support via Aqua | Commercial subscription | Commercial platform licensing |
| Deployment | CLI, client/server, air-gapped capable | SaaS-first with brokered integrations | SaaS and self-hosted enterprise options |
| Scalability | Strong for CI fleets with shared cache/server | Strong for developer workflows and SaaS scale | Strong for large runtime and registry estates |
| Security Coverage | Vulns, misconfig, secrets, SBOM, K8s | Vulns, IaC, code, container | Vulns, compliance, runtime defense, host/container |
| Best Fit | Cost-efficient DevSecOps standardization | Developer-centric remediation workflows | Broad CNAPP and runtime protection |
Troubleshooting
1. Database download failures
Log sample:
2026-03-18T08:11:42Z ERROR DB error: failed to download vulnerability DB
2026-03-18T08:11:42Z FATAL init error: DB error: OCI artifact error: denied
Fix: verify registry egress, proxy settings, or internal OCI mirror permissions; run trivy image --download-db-only --debug.
2. Image scan cannot access private registry
Log sample:
2026-03-18T08:14:03Z WARN image scan error: failed to parse image reference
2026-03-18T08:14:03Z ERROR unable to initialize a scanner: 401 Unauthorized
Fix: authenticate first with the registry client or provide supported credentials to the runtime environment; confirm the CI runner can docker pull the same image.
3. Timeout on large monorepo or image
Log sample:
2026-03-18T08:17:55Z ERROR scan error: context deadline exceeded
2026-03-18T08:17:55Z FATAL timeout: increase --timeout value
Fix: raise --timeout 20m, exclude irrelevant paths, and use server mode with warm cache.
Best Practices
Do:
- Gate on HIGH and CRITICAL initially, then tighten over time.
- Separate policy by artifact type; for example, stricter blocking on production images than on feature-branch IaC scans.
- Baseline and suppress carefully using reviewed ignore files with expiration dates.
- Export SARIF/JSON into SIEM or code scanning dashboards for trend analysis.
Don't:
- Fail every build on unfixed CVEs without triage; use
--ignore-unfixedwhen patch availability is low. - Run internet-dependent scans in restricted production networks; mirror databases internally.
- Treat secret scanning output casually; route findings through incident handling because exposed credentials may require immediate rotation.
Have a project in mind?
Get an instant AI price estimate for it, or talk directly to our team.
One email a month on what we learn building with AI