The Complete Production SOP: How to Deploy and Run Trivy All-in-One Container & Filesystem Scanner in Autonomous AI Agents
Step-by-step SOP to install and run Trivy Container & Filesystem Scanner in Codex, Claude Code, and Cursor. Master SARIF exports, CVE scans, and CI gates.
Technical Overview & Architectural Context
Autonomous coding agents like Claude Code, Cursor, and Codex frequently generate container definitions and dependency manifests with out-of-date base images, transitive CVEs, and insecure infrastructure-as-code defaults. Left unconstrained, an agent will generate a Dockerfile, verify that it builds locally, and conclude its task without auditing whether the image imports high-severity vulnerabilities or hardcoded service credentials. The Trivy All-in-One Container & Filesystem Scanner skill establishes a strict, deterministic operational boundary. Instead of delegating security audits to LLM probabilistic guesswork, this skill forces the agent to execute real-time Aqua Security Trivy scans across container layers, local filesystems, package manifests, and IaC templates. It mandates concrete exit codes, structured SARIF output formatting, and pre-commit security gates to ensure zero vulnerable assets enter production branches.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent context.
Autonomous runtimes discover capabilities by reading standardized markdown files located in local config directories (.claude/skills, .cursor/rules, or .agents/skills). Mounting the Trivy skill registers deterministic command flags and trigger terms such as 'scan container image trivy' and 'export trivy sarif report'. This prevents the agent from attempting unstructured terminal commands or hallucinating non-existent vulnerability database flags.
mkdir -p ~/.agents/skills/trivy-container-security-scanner && cat <<'EOF' > ~/.agents/skills/trivy-container-security-scanner/SKILL.md
---
name: "trivy-container-security-scanner"
description: "Scan container images, file systems, Git repos, and cloud configs for CVEs and misconfigs."
metadata:
author: "Aqua Security"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "scan container image trivy"
- "run trivy filesystem scan"
- "export trivy sarif report"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: true
net_access: true
---
# Trivy All-in-One Container & Filesystem Scanner
Performs comprehensive security scanning using Aqua Security Trivy: OS packages, language dependencies, Terraform misconfigurations, exposed secrets, and Kubernetes security checks.
## Execution SOP & Rules
1. Always run with `--severity HIGH,CRITICAL` and `--exit-code 1` when enforcing validation gates.
2. When evaluating source code, invoke `trivy fs --scanners vuln,secret,config .`.
3. Suppress noise with `--ignore-unfixed` unless specifically requested to inspect unpatched CVEs.
4. Persist automated results using `--format sarif -o trivy-report.sarif` for GitHub CodeQL and IDE ingestion.
EOF---
name: "trivy-container-security-scanner"
description: "Scan container images, file systems, Git repos, and cloud configs for CVEs and misconfigs."
metadata:
author: "Aqua Security"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "scan container image trivy"
- "run trivy filesystem scan"
- "export trivy sarif report"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: true
net_access: true
---To save context window tokens, instruct the agent to consume Trivy scan output as tabular summaries or write them directly to file (`-o trivy-report.sarif`) rather than piping massive multi-megabyte raw JSON payloads directly into conversation tokens.
Claude Code and Cursor terminal execution runs inside restricted user sandboxes. Ensure Trivy's vulnerability DB cache directory (`~/.cache/trivy`) has read/write permissions for your active user account.
Environment Secrets & Dependency Validation
Configure Trivy database paths, rate limits, and GitHub API credentials safely.
Trivy frequently fetches vulnerability database updates from GitHub Container Registry (ghcr.io). Without an authenticated token or pre-warmed cache, automated agents hitting rate limits will abort mid-run. We supply safe environment definitions and pre-download the vulnerability database.
trivy image --download-db-only && echo 'export TRIVY_NON_SSL=false' >> ~/.bashrc# Optional: Provide GitHub token to circumvent API rate limits on DB updates
GITHUB_TOKEN=ghp_exampleTokenForTrivyDbDownload
TRIVY_CACHE_DIR=/tmp/trivy-cache
TRIVY_QUIET=trueNever allow an agent to write cleartext GITHUB_TOKEN values to standard stdout; use workspace environment variables or an existing credentials provider mounted into the container daemon.
Running scans without pre-downloading databases will cause timeouts in restricted environments with constrained or non-interactive terminal execution timeouts.
Intent Matching & Trigger Invocation
Prompt the agent using deterministic skill triggers to run targeted scans.
Invoke the agent using precise intent phrases matching the SKILL.md triggers. By using explicit commands like 'run trivy filesystem scan', the agent triggers the exact SOP rule enforcing `--severity HIGH,CRITICAL` and formatting standards.
Run trivy filesystem scan across the current workspace. Audit dependencies and Terraform files, ignore unfixed issues, and export trivy sarif report to reports/trivy.sarif.Specify output directory paths (`reports/`) so the agent organizes artifacts cleanly without polluting the root repository workspace.
Omitting `--ignore-unfixed` may overwhelm your agent with non-actionable zero-days that lack an upstream vendor fix, stalling your CI pipeline.
Verification, Linting & Output Quality Gate
Verify SARIF artifact generation and validate zero critical issues.
The skill enforces an automated self-check. The agent evaluates the return code of Trivy and confirms the SARIF document adheres to valid JSON schema before reporting task completion.
test -s reports/trivy.sarif && jq '.runs[0].results | length' reports/trivy.sarif#!/usr/bin/env bash
set -euo pipefail
if [ ! -f "reports/trivy.sarif" ]; then
echo "Error: SARIF report missing!"
exit 1
fi
ISSUES=$(jq '[.runs[].results[]? | select(.level == "error")] | length' reports/trivy.sarif)
if [ "$ISSUES" -gt 0 ]; then
echo "Quality Gate Failed: $ISSUES HIGH/CRITICAL vulnerabilities found."
exit 1
fi
echo "Trivy scan passed verification quality gate."Use `jq` within custom evaluation scripts to quickly filter severities without overloading context windows with hundreds of low-severity notices.
Ensure that the exit code validation in CI runners accounts for `--exit-code 1` throwing non-zero exit statuses upon finding genuine vulnerabilities.
Real-World Scenario: Audit Base Container Image and Generate CI SARIF Artifact for GitHub CodeQL
“We just updated our Dockerfile to use node:20-alpine. Scan container image trivy on myapp:local, export trivy sarif report to build/security/results.sarif, and fail the gate if any CRITICAL CVEs or leaked secrets are detected.”
Runtime Troubleshooting & Failure Modes
Root Cause: The autonomous agent is running in an unprivileged container or sandbox where `/var/run/docker.sock` is not accessible, preventing direct image introspection.
trivy image --input image-archive.tar or export TRIVY_CONTAINER_RUNTIME=containerd or bind-mount the docker socket: docker run -v /var/run/docker.sock:/var/run/docker.sock ...Root Cause: Anonymous pulls against ghcr.io for Aqua's vulnerability DB cache hit strict network rate limits within CI/CD runner pools.
trivy image --download-db-only --db-repository mirror.gcr.io/aquasec/trivy-db:2Frequently Asked Questions (Trivy All-in-One Container & Filesystem Scanner SOP)
Q:Can I use Trivy All-in-One Container & Filesystem Scanner across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. By placing the file in your root workspace `.agents/skills/trivy-container-security-scanner/SKILL.md` or referencing it inside `.cursor/rules` or Claude's agent configuration, all modern runtimes parse and honor the procedural steps seamlessly.
Q:How does Trivy All-in-One Container & Filesystem Scanner prevent context window overflow during long agent sessions?
By forcing output persistence via `--format sarif -o <path>` and using strict severity filtering (`--severity HIGH,CRITICAL`), Trivy prevents thousands of lines of terminal text from entering the active token window. The agent only reads summary metrics or parsed JSON blocks through structured CLI tools.
Q:Does this skill require escalated root or container permissions?
No. Filesystem and configuration scans require only standard workspace file read access. Container image scanning requires read access to the Docker socket or an exported image tarball, holding a low security risk profile and a certified score of 98/100.
Ready to equip your autonomous agent with Trivy All-in-One Container & Filesystem Scanner?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.