kubewarden / kubewarden-controller

Manage admission policies in your Kubernetes cluster with ease
https://kubewarden.io
Apache License 2.0
195 stars 33 forks source link
hacktoberfest kubernetes kubernetes-security policy-as-code webassembly

Kubewarden Core Repository Stable Artifact HUB OpenSSF Best Practices FOSSA license scan OpenSSF Scorecard CLOMonitor

Kubewarden is a Kubernetes Dynamic Admission Controller that uses policies written in WebAssembly.

For more information refer to the official Kubewarden website.

kubewarden-controller

kubewarden-controller is a Kubernetes controller that allows you to dynamically register Kubewarden admission policies.

The kubewarden-controller reconciles the admission policies you have registered with the Kubernetes webhooks of the cluster where it's deployed.

Installation

The kubewarden-controller can be deployed using a Helm chart. For instructions, see https://charts.kubewarden.io.

Usage

Once the kubewarden-controller is up and running, you can define Kubewarden policies using the ClusterAdmissionPolicy resource.

The documentation of this Custom Resource can be found here or on docs.crds.dev.

Note: ClusterAdmissionPolicy resources are cluster-wide.

Deploy your first admission policy

The following snippet defines a Kubewarden Policy based on the psp-capabilities policy:

apiVersion: policies.kubewarden.io/v1alpha2
kind: ClusterAdmissionPolicy
metadata:
  name: psp-capabilities
spec:
  module: registry://ghcr.io/kubewarden/policies/psp-capabilities:v0.1.3
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  mutating: true
  settings:
    allowed_capabilities:
      - CHOWN
    required_drop_capabilities:
      - NET_ADMIN

This ClusterAdmissionPolicy evaluates all the CREATE and UPDATE operations performed against Pods. The homepage of this policy provides more insights about how this policy behaves.

Creating the resource inside Kubernetes is sufficient to enforce the policy:

kubectl apply -f https://raw.githubusercontent.com/kubewarden/kubewarden-controller/main/config/samples/policies_v1alpha2_clusteradmissionpolicy.yaml

Remove your first admission policy

You can delete the admission policy you just created:

kubectl delete clusteradmissionpolicy psp-capabilities
kubectl patch clusteradmissionpolicy psp-capabilities -p '{"metadata":{"finalizers":null}}' --type=merge

Learn more

The documentation provides more insights about how the project works and how to use it.

Software bill of materials & provenance

Kubewarden controller has its software bill of materials (SBOM) and build Provenance information published every release. It follows the SPDX format and SLSA provenance schema. Both of the files are generated by Docker buildx during the build process and stored in the container registry together with the container image as well as upload in the release page.

You can find them together with the signature and certificate used to sign it in the release assets, and attached to the image as JSON-encoded documents following the in-toto SPDX predicate format. You can obtain them with crane or docker buildx imagetools inspect.

You can verify the container image with:

cosign verify-blob --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \
    --certificate-identity="https://github.com/${{github.repository_owner}}/kubewarden-controller/.github/workflows/attestation.yml@<TAG TO VERIFY>" \
    --bundle kubewarden-controller-attestation-amd64-provenance-cosign.bundle \
    kubewarden-controller-attestation-amd64-provenance.json

To verify the attestation manifest and its layer signatures:

cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \
    --certificate-identity="https://github.com/${{github.repository_owner}}/kubewarden-controller/.github/workflows/attestation.yml@<TAG TO VERIFY>" \
    ghcr.io/kubewarden/kubewarden-controller@sha256:1abc0944378d9f3ee2963123fe84d045248d320d76325f4c2d4eb201304d4c4e

That sha256 hash is the digest of the attestation manifest or its layers. Therefore, you need to find this hash in the registry using the UI or tools like crane. For example, the following command will show you all the attestation manifests of the latest tag:

crane manifest  ghcr.io/kubewarden/kubewarden-controller:latest | jq '.manifests[] | select(.annotations["vnd.docker.reference.type"]=="attestation-manifest")'
{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8",
  "size": 1655,
  "annotations": {
    "vnd.docker.reference.digest": "sha256:611d499ec9a26034463f09fa4af4efe2856086252d233b38e3fc31b0b982d369",
    "vnd.docker.reference.type": "attestation-manifest"
  },
  "platform": {
    "architecture": "unknown",
    "os": "unknown"
  }
}
{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:e0cd736c2241407114256e09a4cdeef55eb81dcd374c5785c4e5c9362a0088a2",
  "size": 1655,
  "annotations": {
    "vnd.docker.reference.digest": "sha256:03e5db83a25ea2ac498cf81226ab8db8eb53a74a2c9102e4a1da922d5f68b70f",
    "vnd.docker.reference.type": "attestation-manifest"
  },
  "platform": {
    "architecture": "unknown",
    "os": "unknown"
  }
}

Then you can use the digest field to verify the attestation manifest and its layers signatures.

cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \
    --certificate-identity="https://github.com/${{github.repository_owner}}/kubewarden-controller/.github/workflows/attestation.yml@<TAG TO VERIFY>" \
    ghcr.io/kubewarden/kubewarden-controller@sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8

crane manifest  ghcr.io/kubewarden/kubewarden-controller@sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:eda788a0e94041a443eca7286a9ef7fce40aa2832263f7d76c597186f5887f6a",
    "size": 463
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:563689cdee407ab514d057fe2f8f693189279e10bfe4f31f277e24dee00793ea",
      "size": 94849,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    },
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:7ce0572628290373e17ba0bbb44a9ec3c94ba36034124931d322ca3fbfb768d9",
      "size": 7363045,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    },
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:dacf511c5ec7fd87e8692bd08c3ced2c46f4da72e7271b82f1b3720d5b0a8877",
      "size": 71331,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    },
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:594da3e8bd8c6ee2682b0db35857933f9558fd98ec092344a6c1e31398082f4d",
      "size": 980,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    },
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:7738d8d506c6482aaaef1d22ed920468ffaf4975afd28f49bb50dba2c20bf2ca",
      "size": 13838,
      "annotations": {
        "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2"
      }
    }
  ]
}

cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \
    --certificate-identity="https://github.com/${{github.repository_owner}}/kubewarden-controller/.github/workflows/attestation.yml@<TAG TO VERIFY>" \
    ghcr.io/kubewarden/kubewarden-controller@sha256:594da3e8bd8c6ee2682b0db35857933f9558fd98ec092344a6c1e31398082f4d

Note that each attestation manifest (for each architecture) has its own layers. Each layer is a different SBOM SPDX or provenance file generated by Docker Buildx during the multi stage build process. You can also use crane to download the attestation file:

crane blob ghcr.io/kubewarden/kubewarden-controller@sha256:7738d8d506c6482aaaef1d22ed920468ffaf4975afd28f49bb50dba2c20bf2ca

Security disclosure

See SECURITY.md on the kubewarden/community repo.

Changelog

See GitHub Releases content.