{"id":28026856,"url":"https://github.com/github/artifact-attestations-opa-provider","last_synced_at":"2025-05-11T06:11:59.308Z","repository":{"id":292176481,"uuid":"948471742","full_name":"github/artifact-attestations-opa-provider","owner":"github","description":"OPA Gatekeeper provider for GitHub Artifact Attestations","archived":false,"fork":false,"pushed_at":"2025-05-09T11:24:39.000Z","size":10173,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-11T06:11:21.221Z","etag":null,"topics":["package-security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-14T11:55:15.000Z","updated_at":"2025-05-09T11:24:10.000Z","dependencies_parsed_at":"2025-05-08T14:55:58.611Z","dependency_job_id":null,"html_url":"https://github.com/github/artifact-attestations-opa-provider","commit_stats":null,"previous_names":["github/artifact-attestations-opa-provider"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fartifact-attestations-opa-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fartifact-attestations-opa-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fartifact-attestations-opa-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fartifact-attestations-opa-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/artifact-attestations-opa-provider/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253523779,"owners_count":21921824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["package-security"],"created_at":"2025-05-11T06:11:58.704Z","updated_at":"2025-05-11T06:11:59.288Z","avatar_url":"https://github.com/github.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Artifact Attestations OPA Provider\n\n\u003e [!CAUTION]\n\u003e This project is in an early preview state and contains experimental\n\u003e code. It is under active development and not ready for production\n\u003e use. Breaking changes are likely, and stability or security is not\n\u003e guaranteed. Use at your own risk.\n\nThis integrates [OPA Gatekeeper's ExternalData\nfeature](https://open-policy-agent.github.io/gatekeeper/website/docs/externaldata)\nwith [Artifact attestations](https://github.com/actions/attest) to\nallow for policy evaluation based on image's signed SLSA build\nprovenance.\n\n\u003e [!IMPORTANT]\n\u003e For this to work, OPA Gatekeeper must run with\n\u003e `enableExternalData=true`, which can be configured during\n\u003e installation.\n\n## Limitations\n\n* mTLS between OPA Gatekeeper and the external data provider is not\n  yet implemented, only server side TLS\n* No offline mode exposed via the helm chart\n\n## Networking\n\nThe Artifact Attestations OPA Provider needs to have network access\nto:\n\n* The OCI registry where the containers are stored, to be able to\n  download the SLSA build provenance documents.\n* `https://tuf-repo.github.com` to update and verify the trust root\n  for GitHub's Sigstore instance.\n* `https://tuf-repo-cdn.sigstore.dev` to update and verify the trust\n  root for Sigstore's public good instance (this can be disabled with\n  the `-no-public-good` flag)\n\n## Installation\n\n### Preparation\n\nBefore the installation starts, two steps are required to prepare:\n\n1. How OPA Gatekeeper authenticates the OPA External Data\n   Provider. This is done via regular TLS certificates, but they must\n   be created and made available to the services.\n1. If private OPI registries are used, the authentication must be\n   configured.\n\n#### OCI Authentication\n\nCurrently there are two tested authentication methods known to work\nwith private OCI registries:\n\n1. Using `imagePullSecrets`\n2. Using Managed Identities with Azure Managed Kubernetes Service\n   (AKS)\n\nAlthough these are the only tested authentication methods, others may\nwork (Azure using Sevice Principals, GKE and EKS configurations) as\nlong as the POD/Service Accounts are configured properly.\n\nTo use `imagePullSecrets`, prepare the secret in the namespace used by\nthe Artifact Attestations OPA Provider. The default name is\n`aa-login-secret` but can be changed if needed, just make sure to\nupdate the value in `values.yaml` before installing.\n\nTo use Azure Managed Identities, first configure the Managed Identity\nwith the required permission (ACR Pull against the relevant\nregistries), then [configure a federated\ncredential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-config-app-trust-managed-identity?tabs=microsoft-entra-admin-center#configure-a-federated-identity-credential-on-an-existing-application)\nagainst the K8s cluster.\n\nTo enable the use of Azure Managed Identities, you must provide the\nManaged Identity's Client ID: `--set azureClientId=${AZURE_CLIENT_ID}`\nduring helm install.\n\n#### TLS certificates\n\n\u003e [!NOTE]\n\u003e Tested version of OPA Gatekeeper up to version 3.18.2 only supports\n\u003e RSA keys for the TLS certificates.\n\nOPA Gatekeeper relies on TLS authentication when communicating with\nexternal data providers. There is a provided\n[script](scripts/gen_certs.sh) to generate a self signed CA and TLS\ncertificate. The certificate can be created via other means, as long\nas the private key can be mounted as a secret to the Artifact\nAttestations OPA Provider POD.\n\nWhen installing the Artifacts Attestations OPA Provider, the CA\ncertificate bundle must be provided to configure the root of trust.\n\nThe secret containing the TLS certificate and private key can be\nautomatically created, or created separately from the helm\ninstallation. The secret must have the name `provider-tls-cert`.\n\n### Install via helm\n\n#### Using `imagePullSecrets`\n\n```\n$ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \\\n    --set provider.tls.caBundle=\"$(cat certs/ca.crt | base64 | tr -d '\\n\\r')\" \\\n    --set serverCert=\"$(cat certs/tls.crt | base64 | tr -d '\\n\\r')\" \\\n    --set serverKey=\"$(cat certs/tls.key | base64 | tr -d '\\n\\r')\" \\\n    --set imagePullSecrets=\u003cname-of-your-secret\u003e \\\n    --namespace provider-system \\\n    --create-namespace\n```\n\n#### Using Azure Managed Identity\n\n```\n$ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \\\n    --set provider.tls.caBundle=\"$(cat certs/ca.crt | base64 | tr -d '\\n\\r')\" \\\n    --set serverCert=\"$(cat certs/tls.crt | base64 | tr -d '\\n\\r')\" \\\n    --set serverKey=\"$(cat certs/tls.key | base64 | tr -d '\\n\\r')\" \\\n    --set azureClientId=${AZURE_CLIENT_ID} \\\n    --namespace provider-system \\\n    --create-namespace\n```\n\n#### Using Azure Managed Identity and an existing TLS secret\n\n```\n$ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \\\n    --set provider.tls.caBundle=\"$(cat certs/ca.crt | base64 | tr -d '\\n\\r')\" \\\n    --set serverCert=\"\" \\\n    --set azureClientId=${AZURE_CLIENT_ID} \\\n    --namespace provider-system \\\n    --create-namespace\n```\n\n## Verification\n\n### Architecture\n\nGitHub Artifact Attestations OPA provider is a regular [OPA Gatekeeper\nexternal data\nprovider](https://open-policy-agent.github.io/gatekeeper/website/docs/externaldata).\n\nIt works by interacting with OCI registries to fetch [Sigstore\nbundles](https://github.com/sigstore/architecture-docs/blob/main/client-spec.md#5-serialization-and-wire-format)\ncontaining attestations for the container to be deployed. The Artifact\nAttestations OPA provider will fetch the bundles, verify the\ncryptographic integrity, and if valid, return them to OPA Gatekeeper,\nwhere the data can be used during policy evaluation. This means only\nthe cryptographic properties are verified within the Artifact\nAttestations OPA provider, the rego policy is evaluated by OPA\nGatekeeper with normal [constraint\nobjects](https://open-policy-agent.github.io/gatekeeper/website/docs/constrainttemplates). In\nthe constraint configuration is where affected resources and\nnamespaces are configured.\n\n\u003e [!NOTE]\n\u003e OPA Gatekeeper has a hard timeout on 3 seconds, which include the\n\u003e time for the external data provider. Be sure that you don't have\n\u003e unnecessary attestations stored in the OCI registry as it may impact\n\u003e the duration so that a timeout can occur.\n\n```mermaid\nsequenceDiagram\n    participant k8s as K8s\n    participant opag as OPA Gatekeeper\n    participant opadp as Artifact Attestations OPA Provider\n    participant ocir as OCI Registry\n\n    k8s-\u003e\u003eopag: Admit OCI image ref?\n    opag-\u003e\u003eopadp: Validate OCI image ref\n    opadp-\u003e\u003eocir: Fetch attestations for image ref\n    ocir-\u003e\u003eopadp: Zero or more attestations\n    opadp-\u003e\u003eopadp: Verify integrity and authenticity of attestations\n    opadp-\u003e\u003eopag: Verified attestations\n    opag-\u003e\u003eopag: Perform rego policy evaluation on attestations\n    opag-\u003e\u003ek8s: Policy decision\n\n```\n\n### Rego policies\n\nThree examples are provided that can be used as references when\nbuilding out the policy.\n\nThe policies are regular OPA Gatekeeper Constraints, where the\nenforcement action can be set, and the targeted/ignored resources.\n\nWhen writing the policy using the provided examples, the organization\nshould be the name of the GitHub org, like `octo-org`, and the\nrepository must include the org name like `octo-org/octo-repo`.\n\nThe following three examples are provided:\n\n1. [Verify image](validation/from-org-constraint-template.yaml) is\n   built from a list of provided organizations.\n1. [Verify image](validation/from-repo-constraint-template.yaml) is\n   built from a list of provided repositories.\n1. [Verify\n   image](validation/from-org-with-signer-constraint-template.yaml) is\n   originating from a list of organizations, and built with a reusable\n   workflow from a list of provided repositories.\n\nThe examples are also defined in [policies.rego](rego/policies.rego)\nwith tests, and example data. An example policy for working with a\ncustom attestation type is also provided.\n\nAssuming the policy for verifying images originating from a specific\nrepository is updated to contain the expected repositories, apply\nthem to OPA Gatekeeper with the following command:\n\n```\n$ kubectl apply -f validation/from-repo-constraint-template.yaml\n$ kubectl apply -f validation/from-repo-constraint.yaml\n```\n\n## Metrics\n\nThe GitHub Artifact Attestations OPA data provider provided Prometheus\nmetrics, exposed via `http` at `:9090/metrics`. The port can be\nconfigured with the `-metrics-port` flag (`9090` is the default).\n\nThe metrics exposed beyond the default Prometheus metrics are:\n\n* `aaop_attestations_retrieved_total`: the total number of\n  attestations downloaded from the OCI registry.\n* `aaop_attestations_retrieved_failed`: the total number of\n  failed attestations downloaded from the OCI registry.\n* `aaop_attestations_verified_ok`: the total number of verified\n  attestations.\n* `aaop_attestations_verified_failed`: the total number of\n  attestations that failed to verify.\n* `aaop_attestations_request_timer`: the duration in seconds for\n  the validation webhook.\n* `aaop_attestations_retrieved_timer`: the duration in seconds for the\n   time it takes to download the attestations from the OCI registry.\n* `aaop_attestations_verification_timer`: the duration in seconds for\n  the time it takes to verify the retrieved attestations.\n\n## Uninstall\n\n```\n$ kubectl delete -f validation\n$ helm uninstall artifact-attestations-opa-provider -n provider-system\n```\n\n## License\n\nThis project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE.txt) for the full terms.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fartifact-attestations-opa-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fartifact-attestations-opa-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fartifact-attestations-opa-provider/lists"}