Connaisseur

https://sse-secure-systems.github.io/connaisseur/latest/
Admin
A Kubernetes admission controller to integrate container image signature verification and trust...
Tokens:39,768
Snippets:428
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic Docker Image Push

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Example of pulling, tagging, and pushing a Docker image.

```bash
IMAGE=docker.io/securesystemsengineering/demo:test
docker pull hello-world
docker image tag hello-world ${IMAGE}
docker push ${IMAGE}
```

--------------------------------

### Test Image Creation and Push

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Placeholder for the command to create and push a test image, using 'hello-world' as an example.

```bash
# ... (command to create and push test image, e.g. using hello-world)

```

--------------------------------

### Clone Connaisseur Repository

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Clones the Connaisseur GitHub repository.

```bash
git clone https://github.com/sse-secure-systems/connaisseur.git
cd connaisseur

```

--------------------------------

### Kubernetes Deployment (Unsigned Image)

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Attempting to deploy an unsigned image, which Connaisseur will deny.

```bash
kubectl run test --image=${IMAGE}
```

--------------------------------

### Connaisseur Uninstallation

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Command to uninstall Connaisseur using Helm.

```bash
helm uninstall connaisseur --namespace connaisseur
```

--------------------------------

### Check Running Connaisseur Pods

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Command to verify that Connaisseur pods are running.

```bash
kubectl get all -n connaisseur

```

--------------------------------

### Example Static Validators (Allowlist/Denylist)

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

This example demonstrates how to configure static validators for implementing an allowlist or denylist.

```yaml
application:
  validators:
  - name: allow
    type: static
    approve: true
  - name: deny
    type: static
    approve: false
```

--------------------------------

### Cosign Image Signing

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Signing an image using Cosign with a private key.

```bash
cosign sign --key cosign.key ${IMAGE}
```

--------------------------------

### Keybase Alerting Configuration Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/alerting

Example configuration for receiving Keybase notifications on admitted requests.

```yaml
alerting:
  admitRequest:
    receivers:
      - template: keybase
        receiverUrl: https://bots.keybase.io/webhookbot/<Your-Keybase-Hook-Token>
```

--------------------------------

### Docker Push with Content Trust Disabled

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Pushing an image while disabling Docker Content Trust.

```bash
docker push ${IMAGE} --disable-content-trust=false
```

--------------------------------

### Common Examples: Own Images and Deny All Others

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Configuration for validating own images and denying all others, including validator and policy setup.

```yaml
application:
  validators:
  - name: allow
    type: static
    approve: true
  - name: default
    type: notaryv1  # or e.g. 'cosign'
    host: notary.docker.io  # only required in case of notaryv1
    trustRoots:
    - name: default
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvtc/qpHtx7iUUj+rRHR99a8mnGni
        qiGkmUb9YpWWTS4YwlvwdmMDiGzcsHiDOYz6f88u2hCRF5GUCvyiZAKrsA==
        -----END PUBLIC KEY-----
  - name: dockerhub_basics
    type: notaryv1
    host: notary.docker.io
    trustRoots:
    - name: securesystemsengineering_official
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEsx28WV7BsQfnHF1kZmpdCTTLJaWe
        d0CA+JOi8H4REuBaWSZ5zPDe468WuOJ6f71E7WFg3CVEVYHuoZt2UYbN/Q==
        -----END PUBLIC KEY-----

  policy:
  - pattern: "*:*"
  - pattern: "registry.k8s.io/*:*"
    validator: allow
  - pattern: "docker.io/securesystemsengineering/*:*"
    validator: dockerhub_basics
    with:
      trustRoot: securesystemsengineering_official

```

--------------------------------

### Cosign Validator Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Example configuration for the Cosign validator, highlighting the 'type' and 'host' differences from Notary v1.

```yaml
- name: default
  type: cosign  # or other supported validator (e.g. "cosign")
  trustRoots:
  # the `default` key is used if no key is specified in image policy
  - name: default
    key: |  # enter your key below
      -----BEGIN PUBLIC KEY-----
      MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvtc/qpHtx7iUUj+rRHR99a8mnGni
      qiGkmUb9YpWWTS4YwlvwdmMDiGzcsHiDOYz6f88u2hCRF5GUCvyiZAKrsA==
      -----END PUBLIC KEY-----
  #cert: |  # in case the trust data host is using a self-signed certificate
  #  -----BEGIN CERTIFICATE-----
  #  ...
  #  -----END CERTIFICATE-----
  #auth:  # credentials in case the trust data requires authentication
  #  # either (preferred solution)
  #  secretName: mysecret  # reference a k8s secret in the form required by the validator type (check the docs)
  #  # or (only for notaryv1 validator)
  #  username: myuser
  #  password: mypass

```

--------------------------------

### Example Policy Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

An example of how to configure policies in `charts/connaisseur/values.yaml`.

```yaml
application:
  policy:
  - pattern: "*:*"
  - pattern: "docker.io/myrepo/*:*"
    validator: myvalidator
    with:
      trustRoot: mykey
  - pattern: "docker.io/myrepo/deniedimage:*"
    validator: deny
  - pattern: "docker.io/myrepo/allowedimage:v*"
    validator: allow
    with:
      mode: insecureValidateOnly

```

--------------------------------

### Example Validator and Policy Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

A minimal example demonstrating validator and policy configuration, with most fields omitted for clarity.

```yaml
application:
  validators:
  - name: default     # validator 1
    trustRoots:
    - name: default   # key 1
      key: |
        ...
  - name: myvalidator # validator 2
    trustRoots:
    - name: default   # key 2
      key: |
        ...
    - name: mykey     # key 3
      key: |
        ...

  policy:
  - pattern: "*:*"                      # rule 1
  - pattern: "docker.io/myrepo/*:*"     # rule 2
    validator: myvalidator
  - pattern: "docker.io/myrepo/myimg:*" # rule 3
    validator: myvalidator
    with:
      trustRoot: mykey

```

--------------------------------

### Generate DCT Signing Key Pair

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Generates a public-private root key pair for Docker Content Trust.

```bash
docker trust key generate root

```

--------------------------------

### Generate Cosign Signing Key Pair

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Generates a public-private key pair for Cosign.

```bash
cosign generate-key-pair

```

--------------------------------

### Setup preliminary hook

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Applies the preliminary hook resources from the rendered deploy.yaml.

```bash
kubectl apply -f deploy.yaml -l 'app.kubernetes.io/component=connaisseur-init' -n connaisseur
```

--------------------------------

### Caching Configuration Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/caching

Example of how to configure caching settings in `charts/connaisseur/values.yaml`.

```yaml
application:
  features:
    cache:
      expirySeconds: 15
      cacheErrors: false

```

--------------------------------

### Install Connaisseur via Helm (chart repository)

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Installs Connaisseur using the default configuration from the chart repository.

```bash
helm install connaisseur connaisseur/connaisseur --rollback-on-failure --create-namespace --namespace connaisseur
```

--------------------------------

### Makefile commands

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Lists available commands for the Makefile, including installation, uninstallation, and building the Docker image.

```makefile
make install -- Install Connaisseur.
make upgrade -- Upgrade Connaisseur.
make uninstall -- Uninstall Connaisseur and delete the namespace.
make annihilate -- Remove all Connaisseur Kubernetes resources including its namespace. This command is usually helpful, should the normal `make uninstall` not work.
make docker -- Builds the _connaisseur_ container image.
```

--------------------------------

### Clone the Connaisseur repository

Source: https://sse-secure-systems.github.io/connaisseur

This command clones the Connaisseur repository to get started.

```bash
git clone https://github.com/sse-secure-systems/connaisseur.git

```

--------------------------------

### Example configuration for Opsgenie alerts

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/alerting

This YAML configuration demonstrates how to set up Opsgenie alerts for both admit and reject requests, customizing responders based on the request type.

```yaml
alerting:
  admitRequest:
    receivers:
      - template: opsgenie
        receiverUrl: https://api.eu.opsgenie.com/v2/alerts
        priority: 4
        customHeaders: ["Authorization: GenieKey ABC-DEF"]
        payloadFields:
          responders:
            - username: "someone@testcompany.de"
              type: user
  rejectRequest:
    receivers:
      - template: opsgenie
        receiverUrl: https://api.eu.opsgenie.com/v2/alerts
        priority: 4
        customHeaders: ["Authorization: GenieKey ABC-DEF"]
        payloadFields:
          responders:
            - username: "cert@testcompany.de"
              type: user

```

--------------------------------

### Notary v1 Validator Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/getting_started

Example configuration for the Notary v1 validator, including trust roots and optional authentication settings.

```yaml
- name: default
  type: notaryv1  # or other supported validator (e.g. "cosign")
  host: notary.docker.io # configure the notary server to be used
  trustRoots:
  # the `default` key is used if no key is specified in image policy
  - name: default
    key: |  # enter your key below
      -----BEGIN PUBLIC KEY-----
      MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELDzXwqie/P66R3gVpFDWMhxOyol5
      YWD/KWnAaEIcJVTYUR+21NJSZz0yL7KLGrv50H9kHai5WWVsVykOZNoZYQ==
      -----END PUBLIC KEY-----
  #cert: |  # in case the trust data host is using a self-signed certificate
  #  -----BEGIN CERTIFICATE-----
  #  ...
  #  -----END CERTIFICATE-----
  #auth:  # credentials in case the trust data requires authentication
  #  # either (preferred solution)
  #  secretName: mysecret  # reference a k8s secret in the form required by the validator type (check the docs)
  #  # or (only for notaryv1 validator)
  #  username: myuser
  #  password: mypass

```

--------------------------------

### Detection Mode Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/detection_mode

Example of running an unsigned image in detection mode and the expected output.

```bash
kubectl run unsigned --image=docker.io/securesystemsengineering/testimage:unsigned
> Warning: Unable to find signed digest for image docker.io/securesystemsengineering/testimage:unsigned. (not denied due to DETECTION_MODE)
> pod/unsigned created

```

--------------------------------

### Install Connaisseur via Helm (template definition files)

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Installs Connaisseur using the Helm template definition files from the local 'helm' directory.

```bash
helm install connaisseur helm --rollback-on-failure --create-namespace --namespace connaisseur
```

--------------------------------

### Notation Validator Configuration Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

Example of how to configure the Notation validator in Connaisseur's values.yaml file, including trust roots for Bitnami images.

```yaml
application:
  validators:
  - name: bitnami_notation
    type: notation
    trustRoots:
    - name: bitnami
      cert: |
        -----BEGIN CERTIFICATE-----
        MIIGdDCCBFygAwIBAgIUDBaWhJB62sRxczoYu1AcuyKzx9gwDQYJKoZIhvcNAQEL
        BQAwdjELMAkGA1UEBhMCVVMxFTATBgNVBAoMDFZNd2FyZSwgSW5jLjEjMCEGA1UE
        CwwaVk13YXJlIEFwcGxpY2F0aW9uIENhdGFsb2cxKzApBgNVBAMMIlZNd2FyZSBB
        cHBsaWNhdGlvbiBDYXRhbG9nIFJvb3QgQ0EwHhcNMjMxMTA2MTUzMDM0WhcNNDMx
        MTAyMTUzMDM0WjB2MQswCQYDVQQGEwJVUzEVMBMGA1UECgwMVk13YXJlLCBJbmMu
        MSMwIQYDVQQLDBpWTXdhcmUgQXBwbGljYXRpb24gQ2F0YWxvZzErMCkGA1UEAwwi
        Vk13YXJlIEFwcGxpY2F0aW9uIENhdGFsb2cgUm9vdCBDQTCCAiIwDQYJKoZIhvcN
        AQEBBQADggIPADCCAgoCggIBAKa8IGkj5z0TDXV0MmHOBpCcl+Prnr+PR1qM44O5
        tJtw0Uniaka3Vttp4E+M5rbKqjd/neWwClaJWT3Fg2HC7vi4G0QhauZiuaob4hBc
        2DSPJd7/x3T+CIvu6CC3gCLcMJCEYE5mBoCFEiDeiqlHHzf4SI2e6RFJtv+dC7Oc
        Jj7BgccZvZXHeL4qHQs+zGU/oGyK+Iwn7mHnJp8rmDEHaHTbtXDeTqbxcPPJurDT
        trAW/HfrohCoRMZuZBBgf9s876XgoNz8b8FIQksA8OOTgLQdgDaqDAql+ddZzsrk
        l7VhFkztpinrynKpiz2FtlNfOaaD6rq3hpvbYMe3LkJdqw9cr64H2qGf1/Lx+SEh
        rxBwCcs1tmD8LfK4X1Io4JBDMmwfwZ70NdNqxmCxp6y03F52tAhr1DjvEPVXmBgL
        qdPdmpjNMFgPcjMniTBUfQczsy7UNDlmIUvEVNUQISP3KYFJFV4UOWZ+Kpdf1UPY
        95r/JPlRgJKVQ973EvUPlDkSAlY476L46C+jpZNUf6qm352Mf/VMhoSvAXKCYEzj
        WCf46x4nVRCXTR+StapUy5Ru5Azeo0/BXxTErtHatvGA8+igHD4Sn98MiHDO7gXt
        G9eBzIFPx3jyOIQPFhwujHR+8jA/Y9Z5k3T5C6VNpVRZGG7kW3p5gYCM5yq9cCyB
        tm7nAgMBAAGjgfkwgfYwHQYDVR0OBBYEFA22F2MbRn7kx4J5/ZppgpvCKBqhMIGz
        BgNVHSMEgaswgaiAFA22F2MbRn7kx4J5/ZppgpvCKBqhoXqkeDB2MQswCQYDVQQG
        EwJVUzEVMBMGA1UECgwMVk13YXJlLCBJbmMuMSMwIQYDVQQLDBpWTXdhcmUgQXBw
        bGljYXRpb24gQ2F0YWxvZzErMCkGA1UEAwwiVk13YXJlIEFwcGxpY2F0aW9uIENh
        dGFsb2cgUm9vdCBDQYIUDBaWhJB62sRxczoYu1AcuyKzx9gwDwYDVR0TAQH/BAUw
        AwEB/zAOBgNVHQ8BAf8EBAMCAYYwDQYJKoZIhvcNAQELBQADggIBAGOdQSsRNipU
        dZIL/K5fqbgjdYwafpgdjF8z1r9yLKWIEuCCiQFqRZ1CzjnP4jnIlYJXqvqpwklA
        AE56ZNvjo4LzOkElA4emEa+GmLSQ4CqXn+iwX1DYwkyVP7rgZ+k8kjSFjIF2rDhz
        dqnqHA1eyUyb3PhmDFY2694bhWv7D76MzGKLZOFBg3ar0khQp5VaI/bHW1nALAAd
        paM7uAQW/6I20McETtON0weCvbTuljuIVGADLOGwQwjsn7kHbrldEr0EIbtdiEPb
        2Ohis50tPyfrtKVKP/gZBsyTHMaiYxkiNacEDB+cdeDi6kH1Vmm3EFSXWX3vs30D
        3A8AnXw6L7YbXk4PnRy2ueIrs6bya5B9PSzbA2+gEzGnWpZsZmo85DmgpulSSOCM
        lzsP/72ikru888yR0Mvf6BgGestpuXfSSNqUYUTcZVwetyMx/1UC1yCapLJN6eu4
        0oPiQGhSv2uyu6070ne4kXkZL+DYQIjIzqUhS+4AFhBM7drKpo/9gWtHrTq4NRI1
        Q5mnf3lzlPxKV8Uyu2LzdwGb7ySFogAH5/1BGwWVbJvuV+GozJ/AzoPGsNE7mRHu
        ijySwgpMy1PoslxC6UhAeY6IdzoqS1PPQzinknikc4XvG7GLZUwtTooOyHx/ofQo
        RlcLAokhium7GrRC8aceTPeaZHW1+ewh
        -----END CERTIFICATE-----

  policy:
  - pattern: "bitnami/*:*"
    validator: bitnami_notation
    with:
      trustRoot: bitnami

```

--------------------------------

### Install Connaisseur via Helm (custom values.yaml)

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Installs Connaisseur using a custom values.yaml file for configuration.

```bash
helm install connaisseur connaisseur/connaisseur --rollback-on-failure --create-namespace --namespace connaisseur -f values.yaml
```

--------------------------------

### Cosign Validator Configuration Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for the Cosign validator within the Connaisseur application's values.yaml file, including trust roots and policy settings.

```yaml
application:
  validators:
  - name: myvalidator
    type: cosign
    trustRoots:
    - name: mykey
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvtc/qpHtx7iUUj+rRHR99a8mnGni
        qiGkmUb9YpWWTS4YwlvwdmMDiGzcsHiDOYz6f88u2hCRF5GUCvyiZAKrsA==
        -----END PUBLIC KEY-----

  policy:
  - pattern: "docker.io/securesystemsengineering/testimage:co-*"
    validator: myvalidator
    with:
      key: mykey

```

--------------------------------

### Example Authentication Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Example of adding authentication to a validator in `charts/connaisseur/values.yaml`.

```yaml
    auth:
      secretName: k8ssecret

```

--------------------------------

### Prometheus Metrics Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/metrics

This example shows the metrics exposed by Connaisseur, including admission requests, validations, and Go process information.

```prometheus
# HELP connaisseur_requests_admitted_total The total number of admission requests that were admitted
# TYPE connaisseur_requests_admitted_total counter
connaisseur_requests_admitted_total 3
# HELP connaisseur_requests_denied_total The total number of admission requests that were denied
# TYPE connaisseur_requests_denied_total counter
connaisseur_requests_denied_total{timeout="false"} 4
# HELP connaisseur_requests_total The total number of admission requests posed to Connaisseur
# TYPE connaisseur_requests_total counter
connaisseur_requests_total 7
# HELP connaisseur_validations_failed_total The total number of image validations that failed
# TYPE connaisseur_validations_failed_total counter
connaisseur_validations_failed_total{type="notaryv1",validator_name="dockerhub"} 2
connaisseur_validations_failed_total{type="static",validator_name="deny"} 2
# HELP connaisseur_validations_skipped_total The total number of image validations that were skipped
# TYPE connaisseur_validations_skipped_total counter
connaisseur_validations_skipped_total{reason="automatic approval of child image reference",type="notaryv1",validator_name="dockerhub"} 2
# HELP connaisseur_validations_successful_total The total number of image validations that were successful
# TYPE connaisseur_validations_successful_total counter
connaisseur_validations_successful_total{type="notaryv1",validator_name="dockerhub"} 3
# HELP connaisseur_validations_total The total number of image validations performed by Connaisseur
# TYPE connaisseur_validations_total counter
connaisseur_validations_total{result="error",type="notaryv1",validator_name="dockerhub"} 2
connaisseur_validations_total{result="error",type="static",validator_name="deny"} 2
connaisseur_validations_total{result="success",type="notaryv1",validator_name="dockerhub"} 3
# HELP go_gc_duration_seconds A summary of the wall-time pause (stop-the-world) duration in garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0.000120088
go_gc_duration_seconds{quantile="0.25"} 0.000364499
go_gc_duration_seconds{quantile="0.5"} 0.000666734
go_gc_duration_seconds{quantile="0.75"} 0.001108909
go_gc_duration_seconds{quantile="1"} 0.001615903
go_gc_duration_seconds_sum 0.007242773
go_gc_duration_seconds_count 9
# HELP go_gc_gogc_percent Heap size target percentage configured by the user, otherwise 100. This value is set by the GOGC environment variable, and the runtime/debug.SetGCPercent function. Sourced from /gc/gogc:percent.
# TYPE go_gc_gogc_percent gauge
go_gc_gogc_percent 100
# HELP go_gc_gomemlimit_bytes Go runtime memory limit configured by the user, otherwise math.MaxInt64. This value is set by the GOMEMLIMIT environment variable, and the runtime/debug.SetMemoryLimit function. Sourced from /gc/gomemlimit:bytes.
# TYPE go_gc_gomemlimit_bytes gauge
go_gc_gomemlimit_bytes 9.223372036854776e+18
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 18
# HELP go_info Information about the Go environment.
# TYPE go_info gauge
go_info{version="go1.25.8"} 1
# HELP go_memstats_alloc_bytes Number of bytes allocated in heap and currently in use. Equals to /memory/classes/heap/objects:bytes.
# TYPE go_memstats_alloc_bytes gauge
go_memstats_alloc_bytes 7.347368e+06
# HELP go_memstats_alloc_bytes_total Total number of bytes allocated in heap until now, even if released already. Equals to /gc/heap/allocs:bytes.
# TYPE go_memstats_alloc_bytes_total counter
go_memstats_alloc_bytes_total 2.361952e+07
# HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. Equals to /memory/classes/profiling/buckets:bytes.
# TYPE go_memstats_buck_hash_sys_bytes gauge
go_memstats_buck_hash_sys_bytes 1.461774e+06
# HELP go_memstats_frees_total Total number of heap objects frees. Equals to /gc/heap/frees:objects + /gc/heap/tiny/allocs:objects.
# TYPE go_memstats_frees_total counter
go_memstats_frees_total 164143
# HELP go_memstats_gc_sys_bytes Number of bytes used for garbage collection system metadata. Equals to /memory/classes/metadata/other:bytes.
# TYPE go_memstats_gc_sys_bytes gauge
go_memstats_gc_sys_bytes 3.930896e+06
# HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and currently in use, same as go_memstats_alloc_bytes. Equals to /memory/classes/heap/objects:bytes.
# TYPE go_memstats_heap_alloc_bytes gauge
go_memstats_heap_alloc_bytes 7.347368e+06
# HELP go_memstats_heap_idle_bytes Number of heap bytes waiting to be used. Equals to /memory/classes/heap/released:bytes + /memory/classes/heap/free:bytes.
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 4.554752e+06
```

--------------------------------

### Install Connaisseur via Helm

Source: https://sse-secure-systems.github.io/connaisseur

This command installs Connaisseur using Helm, with rollback and namespace creation enabled.

```bash
helm install connaisseur helm --rollback-on-failure --create-namespace --namespace connaisseur

```

--------------------------------

### Complete Conventional Commit Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/CONTRIBUTING

An example of a complete commit message following conventional commit guidelines.

```bash
git commit -m "fix: extend registry validation regex to custom ports" -m "The current regex used for validation of the image name does not allow using non-default ports for the image repository name. The regex is extended to optionally provide a port number." -m "Fix #3"

```

--------------------------------

### Example Notary and Cosign Validators

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

This example shows how to configure both Notary v1 and Cosign validators with their respective trust roots and authentication details.

```yaml
application:
  validators:
  - name: default
    type: notaryv1
    host: notary.docker.io
    trustRoots:
    - name: default
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEsx28WV7BsQfnHF1kZmpdCTTLJaWe
        d0CA+JOi8H4REuBaWSZ5zPDe468WuOJ6f71E7WFg3CVEVYHuoZt2UYbN/Q==
        -----END PUBLIC KEY-----
    auth:
      username: superuser
      password: lookatmeimjumping
  - name: myvalidator
    type: cosign
    trustRoots:
    - name: mykey
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIFXO1w6oj0oI2Fk9SiaNJRKTiO9d
        ksm6hFczQAq+FDdw0istEdCwcHO61O/0bV+LC8jqFoomA28cT+py6FcSYw==
        -----END PUBLIC KEY-----
```

--------------------------------

### Resulting payload example

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/alerting

This JSON snippet shows an example of the resulting payload sent to the webhook endpoint, specifically highlighting the 'responders' field.

```json
{
    ... 
    "responders": [{"type": "user", "username": "cert@testcompany.de"}],
    ...
}

```

--------------------------------

### Configuration example in values.yaml

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/namespaced_validation

Example of how to configure namespaced validation mode in the Connaisseur Helm chart's values.yaml file.

```yaml
application:
  features:
    namespacedValidation:
      mode: validate
```

--------------------------------

### Creating a Conventional Commit

Source: https://sse-secure-systems.github.io/connaisseur/latest/CONTRIBUTING

Example of how to structure a commit message using header, body, and footer.

```bash
git commit -m "<header>" -m "<body>" -m "<footer>"

```

--------------------------------

### Injecting KMS Credentials via Environment Variables

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example of injecting KMS credentials (e.g., for Vault) into Connaisseur via environment variables in values.yaml.

```yaml
  envs:
    VAULT_ADDR: myvault.com
    VAULT_TOKEN: secrettoken
```

--------------------------------

### Keyless Validator Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for a keyless validator using Cosign, specifying issuer regex and subject.

```yaml
- name: keylessvalidator
  type: cosign
  trustRoots:
  - name: keyless
    keyless:
      issuerRegex: "github"
      subject: "philipp.belitz@securesystems.de

```

--------------------------------

### Kubernetes Secret for Ambient Registry Credentials (ECR Example)

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example of a Kubernetes Secret to provide ambient registry credentials for ECR, to be used with cosign's --k8s-keychain.

```yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: connaisseur-env-secrets
  ...
data:
  AWS_ACCESS_KEY_ID: ***
  AWS_SECRET_ACCESS_KEY: ***
  ...
```

--------------------------------

### Notary V1 Validator Configuration Example

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

Example configuration for the Notary V1 validator within the Connaisseur application's values.yaml file.

```yaml
application:
  validators:
  - name: docker_essentials
    type: notaryv1
    host: notary.docker.io
    trustRoots:
    - name: sse
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvtc/qpHtx7iUUj+rRHR99a8mnGni
        qiGkmUb9YpWWTS4YwlvwdmMDiGzcsHiDOYz6f88u2hCRF5GUCvyiZAKrsA==
        -----END PUBLIC KEY-----

  policy:
  - pattern: "docker.io/securesystemsengineering/connaisseur:*"
    validator: docker_essentials
    with:
      key: sse
      delegations:
      - belitzphilipp
      - starkteetje

```

--------------------------------

### Private Infrastructure Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for private Sigstore infrastructure, including Rekor, CT log, and Fulcio public keys/certificates.

```yaml
name: default
type: cosign
host:
  rekorPubkey: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
  ctLogPubkey: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
  fulcioCert: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  ...

```

--------------------------------

### Multi-signature Verification - Trust Roots Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for defining multiple trust roots (alice, bob, charlie) for multi-signature verification.

```yaml
application:
  validators:
  - name: multicosigner
    type: cosign
    trustRoots:
    - name: alice
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEusIAt6EJ3YrTHdg2qkWVS0KuotWQ
        wHDtyaXlq7Nhj8279+1u/l5pZhXJPW8PnGRRLdO5NbsuM6aT7pOcP100uw==
        -----END PUBLIC KEY-----
    - name: bob
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE01DasuXJ4rfzAEXsURSnbq4QzJ6o
        EJ2amYV/CBKqEhhl8fDESxsmbdqtBiZkDV2C3znIwV16SsJlRRYO+UrrAQ==
        -----END PUBLIC KEY-----
    - name: charlie
      key: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEHBUYJVrH+aFYJPuryEkRyE6m0m4
        ANj+o/oW5fLRiEiXp0kbhkpLJR1LSwKYiX5Toxe3ePcuYpcWZn8Vqe3+oA==
        -----END PUBLIC KEY-----
```

--------------------------------

### Image Policy Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

Example configuration for the image policy in `application.policy` to associate an image pattern with a validator.

```yaml
- pattern: "docker.io/<REPOSITORY>/<IMAGE>:*"
  validator: customvalidator

```

--------------------------------

### Labeling namespaces

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/namespaced_validation

Example commands to label namespaces for namespaced validation, either to ignore or validate them.

```bash
# either
kubectl namespaces <namespace> securesystemsengineering.connaisseur/webhook=ignore
# or
kubectl namespaces <namespace> securesystemsengineering.connaisseur/webhook=validate
```

--------------------------------

### RBAC Configuration for KMS

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example Role and RoleBinding for Connaisseur to access Kubernetes secrets, potentially for KMS integration.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: connaisseur-kms-role
  namespace: connaisseur  # namespace of respective k8s secret, might have to change that
  labels:
    app.kubernetes.io/name: connaisseur
rules:
- apiGroups: ["*"]
  resources: ["secrets"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: connaisseur-kms-rolebinding
  namespace: connaisseur  # namespace of respective k8s secret, might have to change that
  labels:
    app.kubernetes.io/name: connaisseur
subjects:
- kind: ServiceAccount
  name: connaisseur-serviceaccount
  namespace: connaisseur  # Connaisseur's namespace, might have to change that
roleRef:
  kind: Role
  name: connaisseur-kms-role
  apiGroup: rbac.authorization.k8s.io

```

--------------------------------

### Getting the public root key using a pre-built image

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

This command uses a pre-built Docker image to extract the public root key of a specified image.

```bash
# pre-built
docker run --rm docker.io/securesystemsengineering/get-public-root-key -i securesystemsengineering/testimage

```

--------------------------------

### Connaisseur Image Policy Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for an image policy in Connaisseur to match a repository with a specific validator.

```yaml
- pattern: "docker.io/securesystemsengineering/testimage:co*"  # YOUR REPOSITORY
  validator: customvalidator

```

--------------------------------

### Getting the public root key using a self-built image

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

This command uses a self-built Docker image to extract the public root key of a specified image.

```bash
# or self-built
docker run --rm get-public-root-key -i securesystemsengineering/testimage

```

--------------------------------

### Test successful verification with official Docker images

Source: https://sse-secure-systems.github.io/connaisseur

This command deploys the 'hello-world' image to test successful verification.

```bash
kubectl run hello-world --image=docker.io/hello-world

```

--------------------------------

### Render Kubernetes manifests using Helm

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Renders the Kubernetes resources from the Helm chart into a single deploy.yaml file.

```bash
helm template helm -n connaisseur > deploy.yaml
```

--------------------------------

### Running Documentation Locally

Source: https://sse-secure-systems.github.io/connaisseur/latest/CONTRIBUTING

Command to run the documentation locally using Docker.

```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

```

--------------------------------

### Arm the webhook

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Applies the admission webhook resources from the rendered deploy.yaml.

```bash
kubectl apply -f deploy.yaml -l 'app.kubernetes.io/component=connaisseur-webhook' -n connaisseur
```

--------------------------------

### Signing images

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

Once you have certificates configured, you can sign and push container images using the Notation CLI.

```bash
# Push the image
docker image push <IMAGE_URI>

# Sign with a specific certificate
notation sign --key "mykey" <IMAGE_URI>

```

--------------------------------

### Running Linters Locally

Source: https://sse-secure-systems.github.io/connaisseur/latest/CONTRIBUTING

Commands to run linters (gosec and golangci-lint) locally using Docker.

```bash
docker run --rm -v $(pwd):/app -w /app/cmd/connaisseur securego/gosec gosec ./...
docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint golangci-lint run -v --timeout=10m --skip-dirs="test"

```

--------------------------------

### Build and load Docker image for Kind

Source: https://sse-secure-systems.github.io/connaisseur/latest/CONTRIBUTING

Steps to build the Connaisseur Docker image and load it onto a Kind cluster.

```bash
make docker
IMAGE_REPO=$(yq e '.kubernetes.deployment.image.repository' charts/connaisseur/values.yaml) && VERSION=$(yq e '.appVersion' charts/connaisseur/Chart.yaml)
kind load docker-image ${IMAGE_REPO}:v${VERSION}

```

--------------------------------

### Creating certificates

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

For testing purposes, you can create a self-signed certificate using the Notation CLI.

```bash
# Create a self-signed certificate
notation cert generate-test --default "mykey"

```

--------------------------------

### Sign a Container Image with Cosign

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Signs a container image using the generated private key.

```bash
# Here, ${IMAGE} is REPOSITORY/IMAGE_NAME:TAG
cosign sign --key cosign.key ${IMAGE}

```

--------------------------------

### Creating trust policy

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

Create a trust policy to match certain images to their respective keys, used for verification. This involves creating a JSON file and importing it.

```bash
cat <<EOF > ./trustpolicy.json
{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "my-images",
            "registryScopes": [ "*" ],
            "signatureVerification": {
                "level" : "strict"
            },
            "trustStores": [ "ca:mykey" ],
            "trustedIdentities": [
                "*"
            ]
        }
    ]
}
EOF

Use `notation policy import` to import the policy:
notation policy import ./trustpolicy.json

```

--------------------------------

### Prometheus Metrics Exposition

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/metrics

Example of metrics exposed by Connaisseur in Prometheus exposition format.

```text
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 1.341710336e+09
# HELP process_virtual_memory_max_bytes Maximum amount of virtual memory available in bytes.
# TYPE process_virtual_memory_max_bytes gauge
process_virtual_memory_max_bytes 1.8446744073709552e+19
# HELP promhttp_metric_handler_requests_in_flight Current number of scrapes being served.
# TYPE promhttp_metric_handler_requests_in_flight gauge
promhttp_metric_handler_requests_in_flight 1
# HELP promhttp_metric_handler_requests_total Total number of scrapes by HTTP status code.
# TYPE promhttp_metric_handler_requests_total counter
promhttp_metric_handler_requests_total{code="200"} 1
promhttp_metric_handler_requests_total{code="500"} 0
promhttp_metric_handler_requests_total{code="503"} 0
```

--------------------------------

### Verify Image Signed with Different Key

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Kubectl command to run a test image signed with an alternative key for verification.

```bash
kubectl run altsigned --image=docker.io/securesystemsengineering/testimage:co-signed-alt

```

--------------------------------

### Notary V1 Validator Configuration

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

Example configuration for the notaryv1 validator in `application.validators`.

```yaml
- name: customvalidator
  type: notaryv1
  host: notary.docker.io
  trustRoots:
  - name: default
    key: |
      -----BEGIN PUBLIC KEY-----
      MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEOXYta5TgdCwXTCnLU09W5T4M4r9f
      QQrqJuADP6U7g5r9ICgPSmZuRHP/1AYUfOQW3baveKsT969EfELKj1lfCA==
      -----END PUBLIC KEY-----

```

--------------------------------

### Verify Unsigned Image

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Kubectl command to run an unsigned test image for comparison.

```bash
kubectl run unsigned --image=docker.io/securesystemsengineering/testimage:co-unsigned

```

--------------------------------

### Labelling target namespace

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/namespaced_validation

Example command to label a specific namespace to be validated by Connaisseur.

```bash
kubectl namespaces validateme securesystemsengineering.connaisseur/webhook=validate
```

--------------------------------

### Testing validation

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

You can test the validation by deploying pods with signed and unsigned images.

```bash
# This should succeed if the image is properly signed
kubectl run signed-app --image=docker.io/myrepo/myimage:signed

# This should fail if the image is not signed or signed with a different certificate
kubectl run unsigned-app --image=docker.io/myrepo/myimage:unsigned

```

--------------------------------

### Test unsigned image deployment

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Attempts to deploy a pod with an unsigned image, which should be denied by Connaisseur.

```bash
kubectl run demo --image=docker.io/securesystemsengineering/testimage:unsigned
> Error from server: admission webhook "connaisseur-svc.connaisseur.svc" denied the request (...).
```

--------------------------------

### Verifying signatures

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notation

You can verify signatures using the Notation CLI.

```bash
# Verify an image signature
notation verify <IMAGE_URI>

```

--------------------------------

### Enable Automatic Unchanged Approval

Source: https://sse-secure-systems.github.io/connaisseur/latest/features/automatic_unchanged_approval

Example configuration in `charts/connaisseur/values.yaml` to enable the automatic unchanged approval feature.

```yaml
application:
  features:
    automaticUnchangedApproval: true

```

--------------------------------

### Allowing Own Images and Denying Others

Source: https://sse-secure-systems.github.io/connaisseur/latest/basics

Configuration example for Connaisseur to admit images from specific registries and repositories while denying all others.

```yaml
application:
  validators:
  - name: allow
    type: static
    approve: true
  - name: deny
    type: static
    approve: false

  policy:
  - pattern: "*:*"
    validator: deny
  - pattern: "docker.io/myrepo/*:*"
    validator: allow
  - pattern: "registry.k8s.io/*:*"
    validator: allow
  - pattern: "docker.io/securesystemsengineering/*:*"
    validator: allow

```

--------------------------------

### Connaisseur policy rule for enforcing delegations

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/notaryv1

Example of a Connaisseur values.yaml configuration to enforce specific delegations for an image.

```yaml
application:
  policy:
  - pattern: "<your-repo>/busybox:*"
    with:
      delegations:
      - <key-name>
      - <other-key-name>

```

--------------------------------

### Connaisseur Validator Configuration (Cosign)

Source: https://sse-secure-systems.github.io/connaisseur/latest/validators/sigstore_cosign

Example configuration for a Cosign validator in Connaisseur, including trust root with a public key.

```yaml
- name: customvalidator
  type: cosign
  trustRoots:
  - name: default
    key: |
      -----BEGIN PUBLIC KEY-----
      MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvtc/qpHtx7iUUj+rRHR99a8mnGni
      qiGkmUb9YpWWTS4YwlvwdmMDiGzcsHiDOYz6f88u2hCRF5GUCvyiZAKrsA==
      -----END PUBLIC KEY-----

```

--------------------------------

### Validator Configuration Structure

Source: https://sse-secure-systems.github.io/connaisseur/latest/adr/ADR-4_modular

Example of how the 'validators' section in values.yaml can be structured to define different validation methods.

```yaml
validators:
- name: "dockerhub-nv2"
  type: "notaryv2"
  ...
- name: "harbor-nv1"
  type: "notaryv1"
  host: "notary.harbor.io"
  root_keys:
    - name: "default"
      key: "..."
- name: "cosign"
  type: "cosign"
  ...
```

--------------------------------

### Signing with Notation

Source: https://sse-secure-systems.github.io/connaisseur/latest/RELEASING

Command to sign a multi-arch Docker image using Notation.

```bash
notation sign --key "sse" docker.io/securesystemsengineering/connaisseur@sha256:${SHA}

```
Tokens:
Raw