# aquasecurity/trivy-operator architecture

> Architecture diagram of the GitHub repository aquasecurity/trivy-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aquasecurity/trivy-operator
- Repository: https://github.com/aquasecurity/trivy-operator

## Overview

Trivy Operator watches Kubernetes resources and responds to changes with scans, then publishes findings as Kubernetes-native custom-resource reports. The principal workload path is reconciliation, scan-job construction, Trivy execution, report building, and API persistence. Separate branches cover configuration and policy audits, RBAC, infrastructure, compliance, SBOMs, exposed secrets, metrics, and webhook delivery. The README documents several capabilities not fully sampled; edges for those rely on its statements, and unsampled implementation details are not asserted.

Main entry points: [`pkg/operator/operator.go`](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/operator/operator.go) (Operator manager), [`pkg/vulnerabilityreport/controller/workload.go`](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/workload.go) (Workload reconciler), [`pkg/vulnerabilityreport/controller/scanjob.go`](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/scanjob.go) (Scan-job controller), [`pkg/configauditreport/controller/resource.go`](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/configauditreport/controller/resource.go) (Config audit controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control"]
  node_operator["Operator manager<br/>[operator.go]"]
  node_config["Operator configuration<br/>[config.go]"]
  node_resolver["Object resolver<br/>[object.go]"]
end

subgraph group_scanning["Workload scanning"]
  node_workload["Workload reconciler<br/>[workload.go]"]
  node_scanjob["Scan-job controller<br/>[scanjob.go]"]
  node_jobbuilder["Scan-job builder<br/>[builder.go]"]
  node_trivyplugin["Trivy scan plugin<br/>[image.go]"]
end

subgraph group_assessments["Cluster assessments"]
  node_configaudit["Config audit controller<br/>[resource.go]"]
  node_policies["Policy evaluation<br/>[policy.go]"]
  node_infra["Infrastructure assessment<br/>[builder.go]"]
  node_rbac["RBAC assessment<br/>[builder.go]"]
  node_compliance["Compliance reports<br/>[io.go]"]
end

subgraph group_reporting["Reports and APIs"]
  node_sbom["SBOM reports<br/>[builder.go]"]
  node_vulnreport["Vulnerability reports<br/>[builder.go]"]
  node_crds["Report resource types"]
end

subgraph group_integrations["Observability and delivery"]
  node_metrics["Prometheus metrics<br/>[collector.go]"]
  node_webhook["Webhook reporter<br/>[webhookreporter.go]"]
end

node_user(("Cluster changes"))
node_kubeapi[("Kubernetes API")]
node_trivy["Trivy scanner"]
node_endpoint(("Webhook endpoint"))

node_user -->|"changes resources"| node_kubeapi
node_kubeapi -->|"notifies changes"| node_operator
node_operator -->|"loads configuration"| node_config
node_operator -->|"sets up controller"| node_workload
node_operator -->|"sets up controller"| node_configaudit
node_operator -->|"registers collector"| node_metrics
node_workload -->|"resolves owners"| node_resolver
node_workload -->|"handles completed jobs"| node_scanjob
node_workload -.->|"builds scan jobs"| node_jobbuilder
node_jobbuilder -->|"requests job spec"| node_trivyplugin
node_trivyplugin -.->|"runs scans"| node_trivy
node_scanjob -->|"builds findings"| node_vulnreport
node_scanjob -->|"builds SBOM reports"| node_sbom
node_scanjob -.->|"persists report resources"| node_crds
node_configaudit -->|"evaluates policies"| node_policies
node_configaudit -->|"creates assessment reports"| node_infra
node_configaudit -->|"runs RBAC assessment"| node_rbac
node_operator -->|"sets up reporting"| node_compliance
node_operator -.->|"registers report types"| node_crds
node_metrics -->|"reads reports"| node_kubeapi
node_webhook -->|"posts report events"| node_endpoint
node_vulnreport -.->|"publishes reports"| node_kubeapi
node_sbom -.->|"publishes reports"| node_kubeapi
node_infra -.->|"publishes reports"| node_kubeapi
node_rbac -.->|"publishes reports"| node_kubeapi
node_compliance -.->|"publishes reports"| node_kubeapi

click node_operator "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/operator/operator.go"
click node_config "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/operator/etc/config.go"
click node_resolver "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/kube/object.go"
click node_workload "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/workload.go"
click node_scanjob "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/scanjob.go"
click node_jobbuilder "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/builder.go"
click node_trivyplugin "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/plugins/trivy/image.go"
click node_configaudit "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/configauditreport/controller/resource.go"
click node_policies "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/policy/policy.go"
click node_infra "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/infraassessment/builder.go"
click node_rbac "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/rbacassessment/builder.go"
click node_compliance "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/compliance/io.go"
click node_sbom "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/sbomreport/builder.go"
click node_vulnreport "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/builder.go"
click node_crds "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/apis/aquasecurity/v1alpha1/vulnerability_types.go"
click node_metrics "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/metrics/collector.go"
click node_webhook "https://github.com/aquasecurity/trivy-operator/blob/main/pkg/webhook/webhookreporter.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_operator,node_config,node_resolver toneBlue
class node_workload,node_scanjob,node_jobbuilder,node_trivyplugin,node_kubeapi toneAmber
class node_configaudit,node_policies,node_infra,node_rbac,node_compliance,node_endpoint toneMint
class node_sbom,node_vulnreport,node_crds toneRose
class node_metrics,node_webhook,node_user,node_trivy toneIndigo
```

## Components

### Operator control

- [Operator manager](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/operator/operator.go): `pkg/operator/operator.go`
- [Operator configuration](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/operator/etc/config.go): `pkg/operator/etc/config.go`
- [Object resolver](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/kube/object.go): `pkg/kube/object.go`

### Workload scanning

- [Workload reconciler](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/workload.go): `pkg/vulnerabilityreport/controller/workload.go`
- [Scan-job controller](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/controller/scanjob.go): `pkg/vulnerabilityreport/controller/scanjob.go`
- [Scan-job builder](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/builder.go): `pkg/vulnerabilityreport/builder.go`
- [Trivy scan plugin](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/plugins/trivy/image.go): `pkg/plugins/trivy/image.go`

### Cluster assessments

- [Config audit controller](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/configauditreport/controller/resource.go): `pkg/configauditreport/controller/resource.go`
- [Policy evaluation](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/policy/policy.go): `pkg/policy/policy.go`
- [Infrastructure assessment](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/infraassessment/builder.go): `pkg/infraassessment/builder.go`
- [RBAC assessment](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/rbacassessment/builder.go): `pkg/rbacassessment/builder.go`
- [Compliance reports](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/compliance/io.go): `pkg/compliance/io.go`

### Reports and APIs

- [SBOM reports](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/sbomreport/builder.go): `pkg/sbomreport/builder.go`
- [Vulnerability reports](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/vulnerabilityreport/builder.go): `pkg/vulnerabilityreport/builder.go`
- [Report resource types](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/apis/aquasecurity/v1alpha1/vulnerability_types.go): `pkg/apis/aquasecurity/v1alpha1/vulnerability_types.go`

### Observability and delivery

- [Prometheus metrics](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/metrics/collector.go): `pkg/metrics/collector.go`
- [Webhook reporter](https://github.com/aquasecurity/trivy-operator/blob/main/pkg/webhook/webhookreporter.go): `pkg/webhook/webhookreporter.go`

### Other components

- **Cluster changes**
- **Kubernetes API**
- **Trivy scanner**
- **Webhook endpoint**

## Connections

- Cluster changes → Kubernetes API: changes resources
- Kubernetes API → Operator manager: notifies changes
- Operator manager → Operator configuration: loads configuration
- Operator manager → Workload reconciler: sets up controller (evidence: `pkg/operator/operator.go`)
- Operator manager → Config audit controller: sets up controller (evidence: `pkg/operator/operator.go`)
- Operator manager → Prometheus metrics: registers collector (evidence: `pkg/operator/operator.go`)
- Workload reconciler → Object resolver: resolves owners (evidence: `pkg/vulnerabilityreport/controller/workload.go`)
- Workload reconciler → Scan-job controller: handles completed jobs (evidence: `pkg/vulnerabilityreport/controller/workload.go`)
- Workload reconciler → Scan-job builder: builds scan jobs
- Scan-job builder → Trivy scan plugin: requests job spec (evidence: `pkg/vulnerabilityreport/builder.go`)
- Trivy scan plugin → Trivy scanner: runs scans
- Scan-job controller → Vulnerability reports: builds findings (evidence: `pkg/vulnerabilityreport/controller/scanjob.go`)
- Scan-job controller → SBOM reports: builds SBOM reports (evidence: `pkg/vulnerabilityreport/controller/scanjob.go`)
- Scan-job controller → Report resource types: persists report resources
- Config audit controller → Policy evaluation: evaluates policies (evidence: `pkg/configauditreport/controller/resource.go`)
- Config audit controller → Infrastructure assessment: creates assessment reports (evidence: `pkg/configauditreport/controller/resource.go`)
- Config audit controller → RBAC assessment: runs RBAC assessment (evidence: `pkg/configauditreport/controller/resource.go`)
- Operator manager → Compliance reports: sets up reporting (evidence: `pkg/operator/operator.go`)
- Operator manager → Report resource types: registers report types
- Prometheus metrics → Kubernetes API: reads reports (evidence: `pkg/metrics/collector.go`)
- Webhook reporter → Webhook endpoint: posts report events (evidence: `pkg/webhook/webhookreporter.go`)
- Vulnerability reports → Kubernetes API: publishes reports
- SBOM reports → Kubernetes API: publishes reports
- Infrastructure assessment → Kubernetes API: publishes reports
- RBAC assessment → Kubernetes API: publishes reports
- Compliance reports → Kubernetes API: publishes reports
