Trivy Overview
Trivy is an open-source security scanner used to find vulnerabilities, exposed secrets, and configuration issues across container images, source repositories, filesystems, and Kubernetes resources. In customer environments, it gives platform and application teams one practical way to check software before it reaches production.
This knowledge base focuses on the Trivy Server deployment pattern used in Shakudo environments. Server mode centralizes the vulnerability database so teams can run scans from multiple locations without every workstation or CI runner downloading the same database separately.
What Problem Does Trivy Solve?
- Catch container-image vulnerabilities before a release is promoted
- Find leaked credentials, tokens, and secrets in images and repositories
- Detect risky infrastructure settings in Kubernetes, Helm, and IaC files
- Standardize security scanning across developer laptops, CI/CD, and platform operations
How Trivy Fits in the Shakudo Stack
Trivy usually sits alongside your build and deployment workflows:
- Developers and CI/CD pipelines call the Trivy CLI to scan images and source code
- Trivy Server provides a shared service endpoint and keeps the vulnerability database warm
- Container registries and release pipelines use Trivy results as a quality gate before rollout
- Platform teams can use Trivy Kubernetes scanning or Trivy Operator for broader cluster reviews when needed
What Trivy Can Scan
- Container images for OS package and language-package vulnerabilities
- Filesystems and source repositories for vulnerabilities, secrets, and selected configuration issues
- Kubernetes manifests and Helm charts for misconfigurations before deployment
- Kubernetes clusters with the trivy k8s command or Trivy Operator when cluster-wide scanning is required
Key Concepts
- Trivy CLI: the command-line tool developers, CI pipelines, and platform engineers run
- Trivy Server: a shared endpoint that keeps the vulnerability database updated and serves remote scans
- Vulnerability database: the advisory database Trivy uses to match installed packages to known issues
- Scanners: Trivy can run vulnerability, secret, misconfiguration, and license scans depending on the target and flags used
- Fixable vs. not-yet-fixable findings: not every finding needs to block release; many teams start by focusing on HIGH and CRITICAL issues with available fixes
What to Know About Server Mode
Server mode is especially useful when multiple teams need fast image or filesystem scans. The Trivy server downloads and maintains the vulnerability database once, and clients point at the server for shared scanning.
- Vulnerability and license scanning can be offloaded to the server
- Misconfiguration and secret scanning remain client-side even in server mode, which helps avoid sending sensitive source files to the server
- Server mode is best for centralized, repeatable scanning in CI/CD and shared platform environments
What Trivy Is Not
- Not a runtime protection or intrusion-detection system
- Not a replacement for patch management, image signing, or broader security review
- Not a secret manager — it can detect exposed secrets, but it does not store or rotate them
Administration & Best Practices
Use this page to keep Trivy stable, secure, and useful over time. The goal is not just to deploy Trivy once, but to make sure teams continue trusting and using the scan results.
Keep the Vulnerability Database Healthy
- Ensure the Trivy server can reach the advisory databases or an approved internal mirror
- Monitor startup logs after deploy and after upgrades to confirm DB download and refresh are working
- If your network requires a proxy or custom CA bundle, configure that early — DB sync issues are a common cause of stale results
Secure the Service
- Keep the Trivy service cluster-internal unless there is a clear need for external access
- If external access is required, put it behind authentication, TLS, and network restrictions
- Treat registry credentials and proxy credentials as secrets, not plain values in Helm files
- Give only the required namespace and RBAC access to the teams that operate or validate Trivy
Manage Performance and Resource Usage
- Server mode is the main optimization for shared environments because it prevents repeated DB downloads
- Large Java or multi-layer images can take longer to analyze; use a larger timeout where needed
- Tune CPU, memory, and node placement based on real scan volume rather than guessing upfront
- Watch PVC health and storage growth if scans are frequent or the environment is long-lived
Set Clear Scan Policy
- Define what blocks a release: for example HIGH and CRITICAL findings with available fixes
- Separate gating scans from reporting scans so teams do not ignore everything at once
- Review ignore rules regularly and give each exception an owner, business reason, and expiry date
Handle Private Registries Correctly
- Make sure scan clients can authenticate to private registries before rollout day
- If your registry uses self-signed certificates, distribute the trusted CA instead of defaulting to insecure access
- Test at least one private image scan during onboarding — this is a frequent integration gap
Upgrade Process
Upgrades should be small and testable. Keep a copy of your working values file, update dependencies, redeploy, and validate with a real scan after the rollout.
helm dependency build .
helm --kubeconfig <kubeconfig-path> --kube-context <context> upgrade --install trivy . --namespace <namespace> -f <values-override.yaml> --wait --timeout 10m
Recommended Operating Checklist
- Weekly: confirm the service is healthy and still serving test scans
- Weekly: review any repeated scan failures, timeout patterns, or DB sync warnings
- Monthly: review ignored findings and remove stale exceptions
- Quarterly: review chart version, Trivy release notes, and network/proxy assumptions
When to Add Trivy Operator
If the customer wants continuous in-cluster security visibility across workloads and Kubernetes resources, Trivy Operator can complement this server-based setup. For many teams, however, starting with Trivy Server plus CI/CD scanning is the simpler first step.
Troubleshooting & FAQ
Use this page during onboarding, deployment calls, and production support. Format: Problem → What to check → Fix.
Deployment Issues
Trivy pod stays Pending
- What to check: nodeSelector, taints, resource requests, and the PVC status.
- Fix: point nodeSelector at a real node label, relax placement constraints if needed, and confirm the storage class can bind.
PVC stays Pending
- What to check: whether the namespace can use the intended storage class and whether a default storage class exists.
- Fix: specify the correct storage class or update the environment so the PVC can bind.
Server starts but cannot update the vulnerability database
- What to check: outbound internet access, proxy settings, DNS, and certificate trust.
- Fix: configure the required proxy or mirror, trust the needed CA, and restart the pod after the network path is corrected.
Scan Execution Issues
Client cannot connect to Trivy Server
- What to check: service DNS, port 4954, NetworkPolicy rules, and whether the client used http:// or https:// in the --server flag.
- Fix: use the correct server URL, validate with port-forward if necessary, and confirm the service is actually reachable from the client environment.
Private registry image scan fails
- What to check: registry credentials, registry hostname, proxy settings, and self-signed certificate handling.
- Fix: authenticate to the registry in the client environment and provide trusted CA material instead of using insecure workarounds where possible.
Misconfiguration or secret results are missing in server mode
- What to check: whether you are expecting the server to scan local source files for you.
- Fix: run trivy fs or trivy config from the client with the correct scanners enabled. Secret and misconfiguration scanning remain client-side in server mode.
Scan times out
- What to check: image size, Java or large dependency trees, and the current timeout value.
- Fix: raise the timeout, for example --timeout 15m, and verify that the server has enough CPU and memory.
Trivy says it cannot initialize an image scanner
- What to check: image name typos, registry path, local Docker/containerd/Podman socket access, and whether the image actually exists.
- Fix: correct the image reference, authenticate to the right registry, or point Trivy at the correct local runtime socket.
Result Interpretation Issues
There are too many findings to action
- What to check: severity filter, whether fixes are available, and whether the scan mixes blocking and informational findings together.
- Fix: start with HIGH and CRITICAL issues, separate fixable findings from longer-term backlog items, and agree on a release policy with service owners.
A finding looks like a false positive or accepted risk
- What to check: package source, affected version, whether the package is actually present in the running workload, and whether an exception already exists.
- Fix: document the exception clearly, add an owner and review date, and use ignore rules carefully instead of hiding entire categories of results.
Frequently Asked Questions
Do I need Trivy Server, or is the CLI enough?
For a single developer or occasional ad hoc scans, the CLI alone may be enough. Trivy Server is most useful when many teams or CI runners scan often and want shared, faster access to the vulnerability database.
Can Trivy block deployments automatically?
Not by itself. Trivy returns scan results and exit codes. Your CI/CD pipeline or release workflow decides whether to stop the deployment based on those results.
Can Trivy scan Kubernetes clusters?
Yes. The trivy k8s workflow and Trivy Operator are designed for broader cluster-level review. That is related to, but separate from, the basic Trivy Server deployment covered in this KB.
Where should ignore rules live?
Keep them in version-controlled files alongside the application or in a clearly managed policy location. Every exception should have an owner, a reason, and a review date.
Does Trivy replace runtime security tooling?
No. Trivy is a scanning and visibility tool. It works best as part of a broader security program that also includes patching, access control, signing, monitoring, and runtime protections where needed.
