DOCSEARCHbyAlgolia
Submit Docs

Connaisseur Documentation

repository·master·Indexed 19 days ago

https://github.com/sse-secure-systems/connaisseur

A Kubernetes admission controller that enforces container image signature verification and trust pinning to ensure image integrity and provenance. It supports multiple signing solutions including Notary/Docker Content Trust, sigstore/Cosign, and Notation. Key features include detection mode, namespaced validation, alerting, and caching, with compatibility for Kubernetes v1.16 and higher across various environments like EKS, AKS, GKE, and minikube.

Tokens
30.5K
Snippets
80
Records
133
Agent score
65%

What's inside Connaisseur

  1. Overview of Connaisseur features

    master

    Connaisseur provides several advanced features to support DevOps workflows and improve supply-chain security. These features can be used in combination to balance security enforcement with service availability.

    Key features include:

    • Alerting: Send alerts based on verification results.
    • Detection Mode: Configure Connaisseur to warn about invalid images without blocking them, preventing service interruptions.
    • Namespaced Validation: Restrict image validation to specific dedicated namespaces.
    • Resource Validation Mode: Configure Connaisseur to warn about invalid images of specific resource types without blocking them.
    • Caching: Improve performance by caching image digests.

  2. Supported signing solutions in Connaisseur

    master

    Connaisseur is designed to be extendable and supports multiple digital signing solutions. You can use any single solution or a combination of them to verify signatures. The currently supported solutions are:

    • Docker Content Trust (DCT) / Notary (V1)
    • sigstore / Cosign
    • Notation

    For specific details on how to integrate each solution with Connaisseur, refer to the individual integration pages in the documentation. For a comparison of the advantages and disadvantages of each signing method, consult the official documentation for the respective solution.

  3. What is Automatic Unchanged Approval?

    master

    Automatic Unchanged Approval is a feature that allows Connaisseur to automatically approve resource updates if the image references remain unchanged.

    This is primarily used to prevent scaling operations from being denied when dealing with long-lived resources. In a standard workflow, Connaisseur updates an image:tag reference to a specific immutable digest (e.g., image@sha256:123...). If the signature data for that tag is later updated to point to a new digest (e.g., image@sha256:456...), a scaling event using the old digest (image@sha256:123...) would normally be denied because the digest is no longer in the signature data. Enabling this feature skips validation for these specific cases because the image itself hasn't changed.

    Security Warning: Enabling this feature means Connaisseur will no longer guarantee that updated resources have the freshest, most up-to-date signatures. It is disabled by default and should be used with caution. Note that resource creation still enforces full signature validation regardless of this setting.

  4. What is Connaisseur?

    master

    Connaisseur is a Kubernetes admission controller designed to ensure the integrity and provenance of container images. It intercepts resource creation or update requests in a Kubernetes cluster, identifies container images, and verifies their signatures against pre-configured public keys. Based on the verification result, Connaisseur either accepts or denies the request.

    Supported Signing Solutions:

    • Notary / Docker Content Trust
    • Sigstore / Cosign
    • Notation

    Key Features:

    • Alerting: Send alerts based on verification results.
    • Detection Mode: Warn about invalid images without blocking them.
    • Namespaced Validation: Restrict validation rules to specific namespaces.

  5. Understand Notation verification levels

    master

    Notation supports three verification levels that determine how strictly signatures are checked:

    • strict (default): Enforces all validations, including integrity, authenticity, authentic timestamp, expiry, and revocation checks.
    • permissive: Enforces integrity and authenticity, but only logs failures for revocation and expiry.
    • audit: Only enforces integrity; all other checks are logged but do not cause failure.

  6. Understand Connaisseur installation and upgrade behavior

    master

    Connaisseur is an admission controller, which means its webhook intercepts Kubernetes requests. Because the webhook depends on the Connaisseur pods being ready, a race condition can occur during installation: if the webhook is active before the pods are ready and FailurePolicy is set to Fail, the webhook will block the deployment of the Connaisseur pods themselves.

    To solve this, Connaisseur uses a Kubernetes-native approach during Helm operations:

    1. Installation: An "unarmed" (empty) webhook configuration is applied alongside other resources. Once the Connaisseur pods are ready, a post-install Helm hook "arms" the webhook by updating it with actual interception rules.
    2. Upgrades: To ensure high availability during upgrades, Connaisseur uses a post-delete hook to reapply the webhook in an unarmed state, ensuring the webhook remains available to admit new pods while the old ones are being replaced. This allows for a rolling update strategy without blocking the cluster.
    3. Uninstallation: Because the webhook is part of the standard Helm release (unlike previous versions that used separate bootstrap pods), a standard helm uninstall will correctly remove all Connaisseur resources, including the webhook.

  7. Difference between Detection Mode and Failure Policy

    master

    It is important to distinguish between detectionMode and the Kubernetes failurePolicy (kubernetes.webhook.failurePolicy in charts/connaisseur/values.yaml):

    • Detection Mode: Controls how Connaisseur behaves when it is running but finds a policy violation (e.g., an unsigned image). When true, it warns instead of denying.
    • Failure Policy: Controls how Kubernetes behaves when the Connaisseur service is unavailable (e.g., the pod is crashing or unreachable).

    Use Case: Never Block Requests To ensure Connaisseur never blocks a request under any circumstances, you must set both:

    1. detectionMode: true (to allow untrusted images when Connaisseur is healthy).
    2. failurePolicy: Ignore (to allow requests when Connaisseur is unhealthy/unavailable).

  8. How Connaisseur handles configuration updates

    master

    Connaisseur uses a Kubernetes-native approach for configuration management. Instead of using dynamic access via the Kubernetes API (which would allow 'on the fly' changes without restarts), Connaisseur relies on ConfigMaps.

    Because updating a ConfigMap does not automatically update the files inside running pods, configuration changes require a pod restart to take effect. To automate this, it is recommended to use the Helm pattern of including a hash of the configuration files as an annotation in your Deployment. When the configuration changes, the hash changes, triggering a rolling update of the pods.

  9. Relationship between caching and automatic child approval

    master

    While Connaisseur implements a caching mechanism to bypass verification for recently admitted images, caching cannot replace automatic child approval.

    This is because images may be mutated during verification (e.g., replacing a tag with a digest). If the child resource's image differs from the original image used in the cache, it might be subject to a different policy pattern that explicitly denies that specific digest. Automatic child approval handles this by verifying the child against the parent's API-queried state, whereas caching alone would not account for the policy implications of the mutation.

  10. How Notation works with Connaisseur

    master

    Notation is a CNCF project for signing and verifying OCI artifacts using X.509 certificates. Unlike Notary V1, it uses a simpler trust model based on certificate chains and stores signatures as OCI artifacts in the same registry as the images.

    Connaisseur supports validating Notation signatures by using X.509 certificates configured as trustRoots. The validator can verify signatures created by the Notation CLI or any compatible tool implementing the Notation specification.

  11. How Connaisseur manages TLS certificates for webhooks

    master

    Admission webhooks require TLS for communication with Kubernetes. Connaisseur manages this automatically to minimize configuration effort:

    • Automatic Generation: By default, Connaisseur uses the Helm genSelfSignedCert function to create self-signed certificates within the Helm chart. This keeps the installation pipeline-friendly as it does not require external tools like OpenSSL.
    • Certificate Persistence: To avoid the need for pod restarts during upgrades (which occurs when a new certificate is generated and injected into a secret), Connaisseur uses the Helm lookup function. This function checks if a certificate secret already exists in the cluster. If found, it reuses the existing certificate; if not, it generates a new one.
    • External TLS: While Connaisseur prioritizes automatic management, users can still provide external TLS certificates for more complex environments.

  12. How namespaced validation works

    master

    Namespaced validation allows you to restrict image trust verification to specific Kubernetes namespaces. This is useful for stepwise rollouts or excluding namespaces where image signatures are not yet feasible.

    Connaisseur supports two operational modes:

    1. ignore mode: Connaisseur validates all namespaces except those labeled with securesystemsengineering.connaisseur/webhook: ignore.
    2. validate mode: Connaisseur only validates namespaces labeled with securesystemsengineering.connaisseur/webhook: validate.

    Warning: Enabling this feature allows roles with edit permissions on namespaces to bypass validation by applying the ignore label to their namespaces.

    # To use 'ignore' mode, label namespaces to skip:
kubectl label namespace <namespace> securesystemsengineering.connaisseur/webhook=ignore

# To use 'validate' mode, label namespaces to include:
kubectl label namespace <namespace> securesystemsengineering.connaisseur/webhook=validate