aquasecurity/trivy

Kubernetes scanning

Active contributors: chenk, knqyf263, nikpivkin

Purpose

trivy k8s (alias trivy kubernetes) scans a live Kubernetes cluster: it inventories workloads via the Kubernetes API, scans the underlying container images for vulnerabilities and secrets, and runs misconfiguration checks against the cluster's resource manifests. It is also the in-process engine that powers the Trivy Operator.

Directory layout

pkg/k8s/
├── k8s.go              # entrypoint helper
├── writer.go           # report writer
├── writer_test.go
├── commands/
│   ├── run.go          # `trivy k8s` Cobra command
│   └── cluster.go      # cluster discovery
├── report/             # k8s-specific report shapes
└── scanner/
    ├── scanner.go      # the scanner (~18k lines)
    └── io.go           # bridges Kubernetes types to scan inputs

The Kubernetes API client lives in the trivy-kubernetes library; this repo contains only the consumer.

How a cluster scan works

graph TD
    CLI[trivy k8s cluster] --> Cmd[k8s commands]
    Cmd --> Disc[trivy-kubernetes<br/>cluster discovery]
    Disc -->|workloads| Scanner[k8s.Scanner]
    Scanner -->|for each pod image| Image[image scan]
    Scanner -->|for each manifest| Misconf[misconfig scan]
    Image --> Report
    Misconf --> Report
    Report --> Writer[k8s report writer]
    Writer --> Output[stdout / file]

k8s.Scanner runs three logical passes:

Inventory. Use the Kubernetes API to list workloads (deployments, daemonsets, jobs, pods, etc.). The trivy-kubernetes library handles RBAC, namespacing, and resource expansion.
Image scan. For each unique container image referenced by a workload, run a vulnerability/secret scan via the regular pkg/scan pipeline.
Misconfig scan. For each manifest, run the Kubernetes IaC scanner to flag dangerous configurations (hostPath, privileged containers, missing resource requests, etc.).

Findings are aggregated into a Kubernetes-shaped report (one node per resource) and rendered by pkg/k8s/writer.go.

Configuration

Flag	Purpose
`--context`, `--kubeconfig`	Standard kubeconfig overrides.
`--namespace`, `--all-namespaces`, `-A`	Scope.
`--report`	`summary` (default) or `all`.
`--components`	Restrict to `workload`, `infra`, etc.
`--include-kinds`, `--exclude-kinds`	Filter resource kinds.
`--scanners`	Subset of `vuln,misconfig,secret`.
`--qps`, `--burst`	API client throttling.

The full list lives in pkg/flag/kubernetes_flags.go.

Output shapes

Summary table — per-namespace, per-kind counts of findings by severity.
Resource table — one row per resource with the worst finding.
JSON — full nested structure (per-namespace, per-resource, per-finding). Useful as input for trivy k8s reporting tools.
SARIF — for code-scanning consumers.

Trivy Operator

The Trivy Operator embeds the same scanner. It runs as a Kubernetes-native operator that watches workloads and writes results back to the cluster as CRDs (VulnerabilityReports, ConfigAuditReports, etc.). The operator and the CLI share pkg/k8s/scanner/.

Integration points

trivy-kubernetes — the cluster-discovery library (separate repo, listed in go.mod).
Vulnerability scanning — image scans use the same engine.
Misconfiguration — manifest scans use the Kubernetes scanner.
Server — trivy k8s --server <url> works the same as standalone scans.

Entry points for modification

Add a resource kind — coordinate with trivy-kubernetes; the consumer side requires only renderer updates.
Add a report shape — extend pkg/k8s/report/ and register a writer.
Tune throttling/RBAC — pkg/k8s/commands/cluster.go is where the client is configured.

Key source files

File	Purpose
`pkg/k8s/k8s.go`	Top-level helper.
`pkg/k8s/commands/run.go`	`trivy k8s` Cobra command.
`pkg/k8s/commands/cluster.go`	Cluster discovery.
`pkg/k8s/scanner/scanner.go`	Core scanner.
`pkg/k8s/scanner/io.go`	Bridges Kubernetes types to scan inputs.
`pkg/k8s/writer.go`	Top-level report writer.
`pkg/k8s/report/`	Per-format renderers.
`pkg/flag/kubernetes_flags.go`	K8s-specific flags.