# github/artifact-attestations-opa-provider architecture

> Architecture diagram of the GitHub repository github/artifact-attestations-opa-provider, 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/github/artifact-attestations-opa-provider
- Repository: https://github.com/github/artifact-attestations-opa-provider

## Overview

This is a Gatekeeper ExternalData provider that retrieves and cryptographically verifies container-image attestations so Gatekeeper policies can evaluate them during admission. The main flow is admission request → TLS provider → registry authentication and bundle retrieval → Sigstore verification → attestations returned to Gatekeeper for Rego evaluation and a policy decision. Supporting branches include trust-root configuration, certificate injection, metrics, and the documented example policies. Some subsystem links are based on README descriptions because their implementation was not sampled.

Main entry points: [`pkg/provider/provider.go`](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/provider/provider.go) (ExternalData handler), [`cmd/aaop/aaop.go`](https://github.com/github/artifact-attestations-opa-provider/blob/main/cmd/aaop/aaop.go) (Provider server), [`pkg/verifier/multi.go`](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/verifier/multi.go) (Trust-root selection), [`pkg/fetcher/bundle.go`](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/fetcher/bundle.go) (Bundle fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Provider runtime"]
  node_entrypoint["Provider server<br/>[aaop.go]"]
  node_provider["ExternalData handler<br/>[provider.go]"]
  node_cainjector["CA bundle injection<br/>[injector.go]"]
end

subgraph group_retrieval["Attestation retrieval"]
  node_keychain["Registry keychain<br/>[provider.go]"]
  node_bundlefetch["Bundle fetcher<br/>[bundle.go]"]
  node_fetchtrace["Fetch tracing<br/>[trace.go]"]
end

subgraph group_verification["Trust and verification"]
  node_verifierconfig["Verifier configuration<br/>[verifier.go]"]
  node_multiverifier["Trust-root selection<br/>[multi.go]"]
  node_sigstoreverify["Bundle verification<br/>[verifier.go]"]
end

subgraph group_policy["Policy and operations"]
  node_metrics["Prometheus metrics<br/>[prom.go]"]
  node_rego["Example Gatekeeper policies<br/>[policies.rego]"]
  node_orgconstraint["Organization constraints"]
  node_repoconstraint["Repository constraints"]
  node_signerconstraint["Signer constraints"]
end

node_kubernetes(("Kubernetes admission"))
node_gatekeeper["OPA Gatekeeper"]
node_registry["OCI registry"]
node_trustservices["Sigstore TUF services"]

node_kubernetes -->|"requests admission"| node_gatekeeper
node_gatekeeper -->|"requests image data"| node_entrypoint
node_entrypoint -->|"routes requests"| node_provider
node_entrypoint -->|"creates verifier"| node_verifierconfig
node_entrypoint -->|"starts keychain"| node_keychain
node_provider -->|"gets credentials"| node_keychain
node_provider -->|"fetches bundles"| node_bundlefetch
node_bundlefetch -->|"retrieves attestations"| node_registry
node_provider -->|"verifies bundles"| node_multiverifier
node_verifierconfig -->|"assembles verifiers"| node_multiverifier
node_multiverifier -->|"tries trust roots"| node_sigstoreverify
node_sigstoreverify -->|"loads trust roots"| node_trustservices
node_provider -->|"returns attestations"| node_gatekeeper
node_gatekeeper -->|"evaluates policies"| node_rego
node_gatekeeper -->|"returns decision"| node_kubernetes
node_provider -->|"records metrics"| node_metrics
node_entrypoint -.->|"may initialize"| node_cainjector
node_orgconstraint -->|"configures policy"| node_gatekeeper
node_repoconstraint -->|"configures policy"| node_gatekeeper
node_signerconstraint -->|"configures policy"| node_gatekeeper

click node_entrypoint "https://github.com/github/artifact-attestations-opa-provider/blob/main/cmd/aaop/aaop.go"
click node_provider "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/provider/provider.go"
click node_keychain "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/authn/provider.go"
click node_bundlefetch "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/fetcher/bundle.go"
click node_fetchtrace "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/fetcher/trace.go"
click node_verifierconfig "https://github.com/github/artifact-attestations-opa-provider/blob/main/internal/app/verifier.go"
click node_multiverifier "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/verifier/multi.go"
click node_sigstoreverify "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/verifier/verifier.go"
click node_cainjector "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/cainjector/injector.go"
click node_metrics "https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/metrics/prom.go"
click node_rego "https://github.com/github/artifact-attestations-opa-provider/blob/main/rego/policies.rego"
click node_orgconstraint "https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-org-constraint-template.yaml"
click node_repoconstraint "https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-repo-constraint-template.yaml"
click node_signerconstraint "https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-org-with-signer-constraint-template.yaml"

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_entrypoint,node_provider,node_cainjector toneBlue
class node_keychain,node_bundlefetch,node_fetchtrace toneAmber
class node_verifierconfig,node_multiverifier,node_sigstoreverify toneMint
class node_metrics,node_rego,node_orgconstraint,node_repoconstraint,node_signerconstraint toneRose
class node_kubernetes,node_gatekeeper,node_registry,node_trustservices toneIndigo
```

## Components

### Provider runtime

- [Provider server](https://github.com/github/artifact-attestations-opa-provider/blob/main/cmd/aaop/aaop.go): `cmd/aaop/aaop.go`
- [ExternalData handler](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/provider/provider.go): `pkg/provider/provider.go`
- [CA bundle injection](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/cainjector/injector.go): `pkg/cainjector/injector.go`

### Attestation retrieval

- [Registry keychain](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/authn/provider.go): `pkg/authn/provider.go`
- [Bundle fetcher](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/fetcher/bundle.go): `pkg/fetcher/bundle.go`
- [Fetch tracing](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/fetcher/trace.go): `pkg/fetcher/trace.go`

### Trust and verification

- [Verifier configuration](https://github.com/github/artifact-attestations-opa-provider/blob/main/internal/app/verifier.go): `internal/app/verifier.go`
- [Trust-root selection](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/verifier/multi.go): `pkg/verifier/multi.go`
- [Bundle verification](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/verifier/verifier.go): `pkg/verifier/verifier.go`

### Policy and operations

- [Prometheus metrics](https://github.com/github/artifact-attestations-opa-provider/blob/main/pkg/metrics/prom.go): `pkg/metrics/prom.go`
- [Example Gatekeeper policies](https://github.com/github/artifact-attestations-opa-provider/blob/main/rego/policies.rego): `rego/policies.rego`
- [Organization constraints](https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-org-constraint-template.yaml): `validation/from-org-constraint-template.yaml`
- [Repository constraints](https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-repo-constraint-template.yaml): `validation/from-repo-constraint-template.yaml`
- [Signer constraints](https://github.com/github/artifact-attestations-opa-provider/blob/main/validation/from-org-with-signer-constraint-template.yaml): `validation/from-org-with-signer-constraint-template.yaml`

### Other components

- **Kubernetes admission**
- **OPA Gatekeeper**
- **OCI registry**
- **Sigstore TUF services**

## Connections

- Kubernetes admission → OPA Gatekeeper: requests admission (evidence: `README.md`)
- OPA Gatekeeper → Provider server: requests image data (evidence: `README.md`)
- Provider server → ExternalData handler: routes requests (evidence: `cmd/aaop/aaop.go`)
- Provider server → Verifier configuration: creates verifier (evidence: `cmd/aaop/aaop.go`)
- Provider server → Registry keychain: starts keychain (evidence: `cmd/aaop/aaop.go`)
- ExternalData handler → Registry keychain: gets credentials (evidence: `pkg/provider/provider.go`)
- ExternalData handler → Bundle fetcher: fetches bundles (evidence: `pkg/provider/provider.go`)
- Bundle fetcher → OCI registry: retrieves attestations (evidence: `README.md`)
- ExternalData handler → Trust-root selection: verifies bundles (evidence: `pkg/provider/provider.go`)
- Verifier configuration → Trust-root selection: assembles verifiers (evidence: `internal/app/verifier.go`)
- Trust-root selection → Bundle verification: tries trust roots (evidence: `pkg/verifier/multi.go`)
- Bundle verification → Sigstore TUF services: loads trust roots (evidence: `README.md`)
- ExternalData handler → OPA Gatekeeper: returns attestations (evidence: `README.md`)
- OPA Gatekeeper → Example Gatekeeper policies: evaluates policies (evidence: `README.md`)
- OPA Gatekeeper → Kubernetes admission: returns decision (evidence: `README.md`)
- ExternalData handler → Prometheus metrics: records metrics (evidence: `pkg/provider/provider.go`)
- Provider server → CA bundle injection: may initialize
- Organization constraints → OPA Gatekeeper: configures policy (evidence: `README.md`)
- Repository constraints → OPA Gatekeeper: configures policy (evidence: `README.md`)
- Signer constraints → OPA Gatekeeper: configures policy (evidence: `README.md`)
