Managing compliance with Enterprise Contract

Procedure

1. Configure your policy in the command line as a JSON or YAML string, as in the following example:

   ec validate image --policy '{
       "sources": [
           {
               "policy": ["oci::quay.io/enterprise-contract/ec-release-policy:latest"],
               "data": ["git::https://github.com/enterprise-contract/ec-policies//example/data"],
               "config": {"include": ["@minimal"]}
           }
       ]
   }' ...

2. (Optional) Exclude a particular package of rules from your Enterprise Contract policy, as in the following example:

   {
     "sources": [
       {
         "policy": [
           "oci::quay.io/enterprise-contract/ec-release-policy:latest"
         ],
         "data": [
           "git::https://github.com/enterprise-contract/ec-policies//example/data"
         ],
         "config": {
           "exclude": [
             "attestation_task_bundle",
             "slsa_build_scripted_build"
           ]
         }
       }
     ]
   }

   This command includes every rule from every package except for the rules in the specified packages.

3. (Optional) Exclude a single rule, as in the following example:

   {
     "sources": [
       {
         "policy": [
           "oci::quay.io/enterprise-contract/ec-release-policy:latest"
         ],
         "data": [
           "git::https://github.com/enterprise-contract/ec-policies//example/data"
         ],
         "config": {
           "exclude": [
             "attestation_task_bundle.unacceptable_task_bundle"
           ]
         }
       }
     ]
   }

   This commands includes every rule from the attestation_task_bundle package except for the unacceptable_task_bundle rule.

4. (Optional) Include rules from only a particular package, as in the following example:

   {
     "sources": [
       {
         "policy": [
           "oci::quay.io/enterprise-contract/ec-release-policy:latest"
         ],
         "data": [
           "git::https://github.com/enterprise-contract/ec-policies//example/data"
         ],
         "config": {
           "include": [
             "test",
             "java"
           ]
         }
       }
     ]
   }

   This command includes only the rules from the specified packages.

5. (Optional) Include only some rules from a particular package. This means that you can specify both include and exclude to select only the rules you want your Enterprise Contract policy to include, as in the following example:

   {
     "sources": [
       {
         "policy": [
           "oci::quay.io/enterprise-contract/ec-release-policy:latest"
         ],
         "data": [
           "git::https://github.com/enterprise-contract/ec-policies//example/data"
         ],
         "config": {
           "include": [
             ""*"", 1
             "attestation_task_bundle.unacceptable_task_bundle"
           ],
           "exclude": [
             "attestation_task_bundle.*"
           ]
         }
       }
     ]
   }

   1

   The asterisk (*) acts as a wildcard to match any package. Note that it does not match partial names, which means that, for example, you can’t specify "s*" to match every package that starts with "s".

   These commands specify that you want to include only the unacceptable_task_bundle rule from the attestation_task_bundle package, and exclude all the other rules in that package.

6. (Optional) Exclude certain checks so that Enterprise Contract can validate your container image even if those checks fail or don’t complete, as in the following example:

   {
     "sources": [
       {
         "policy": [
           "oci::quay.io/enterprise-contract/ec-release-policy:latest"
         ],
         "data": [
           "git::https://github.com/enterprise-contract/ec-policies//example/data"
         ],
         "config": {
           "exclude": [
             "test:get-clair-scan",
             "test:clamav-scan"
           ]
         }
       }
     ]
   }

   This command specifies that, if either of the identified checks fails or doesn’t complete, Enterprise Contract can still finish to validate your container image.

7. (Optional) Modify the defaults for rules in a package by running either the config.policy.include command or the config.policy.exclude command, along with a list of strings.

   Your list of strings should include one of the following:

   • "package name" - Choose from the packages in the Available rule collections list.
   • "rule name" - Specify a rule name by entering the name of the package and the rule code, separated by a dot (.), as in this example: attestation_type.unknown_att_type. You can find rule codes under "Attestation type" here.
   • "package name:term" - Some policy rules process a list of items. When you add "term" to the "package name" string, you can exclude or include a particular item from that list. This works similarly to "package name," except that it applies only to policy rules in the package that match that term. For example, if you run the test package, you can choose to ignore a given test case but include all the others.
   • "rule name:term" - This is similar to "package name:term" except that, instead of including or excluding an item from a package, you can include ot exclude a particular package policy rule.
   • "@collection name" - Add this to your string to specify a predefined collection of rules. TMake sure you prefix the collection name with the @ symbol. Choose from the available rule collections here.

Procedure

1. In your CLI, run this command: cosign generate-key-pair.
2. When prompted, enter a new password for the key-pair. Make sure your password is memorable and strong.

Procedure

1. Download the ec binary file from the OpenShift cluster:

   1. Log in to the OpenShift web console. From the home page, click the ? icon in the upper right, then select Command Line Tools.
   2. From the ec download section, click the link for your platform.

   3. Open a terminal, decompress the .gz file, and set the execute bit on the ec binary file:

      Examples for Linux and macOS

      • $ gunzip ec-amd64.gz
      • $ chmod +x ec-amd64

   4. Move the ec binary file to a directory within your $PATH environment:

      Example

      $ sudo mv ec-amd64 /usr/local/bin/ec

2. Configure your shell environment for container image signing and verification.

   1. Open a terminal and run the tas-env-variables.sh script from the sigstore-ocp directory:

      Example

      cd sigstore-ocp
      source tas-env-variables.sh

   2. (Optional) Set the environment variables manually:

      Example

      export OPENSHIFT_APPS_SUBDOMAIN=apps.$(oc get dns cluster -o jsonpath='{ .spec.baseDomain }')
      export OIDC_AUTHENTICATION_REALM=sigstore
      export FULCIO_URL=https://fulcio.$OPENSHIFT_APPS_SUBDOMAIN
      export OIDC_ISSUER_URL=https://keycloak-keycloak-system.$OPENSHIFT_APPS_SUBDOMAIN/auth/realms/$OIDC_AUTHENTICATION_REALM
      export REKOR_URL=https://rekor.$OPENSHIFT_APPS_SUBDOMAIN
      export TUF_URL=https://tuf.$OPENSHIFT_APPS_SUBDOMAIN

      Example

      $ source ./tas-env-vars.sh

3. Initialize The Update Framework (TUF) system:

   Example

   cosign initialize --mirror=$TUF_URL --root=$TUF_URL/root.json

4. Sign your container image:

   Syntax

   cosign sign -y --fulcio-url=$FULCIO_URL --rekor-url=$REKOR_URL --oidc-issuer=$OIDC_ISSUER_URL IMAGE_NAME

   Example

   cosign sign -y --fulcio-url=$FULCIO_URL --rekor-url=$REKOR_URL --oidc-issuer=$OIDC_ISSUER_URL example-hello-world@sha256:2788a47fd0ef1ece30898c1e608050ea71036d3329b9772dbb3d1f69313f745c

   In the web browser that opens, sign the container image with an email address.

5. Create a predicate.json file:

   Example

   {
     "builder": {
       "id": "https://localhost/dummy-id"
     },
     "buildType": "https://example.com/tekton-pipeline",
     "invocation": {},
     "buildConfig": {},
     "metadata": {
       "completeness": {
         "parameters": false,
         "environment": false,
         "materials": false
       },
       "reproducible": false
     },
     "materials": []
   }

6. Associate the predicate.json file with your container image:

   Syntax

   cosign attest -y --predicate ./predicate.json \
   --type slsaprovenance IMAGE_NAME:TAG

   Example

   $ cosign attest -y --predicate ./predicate.json \
   --type slsaprovenance example.io/hello-world:latest

7. Verify that the container image has at least one attestation and signature:

   Syntax

   cosign tree IMAGE_NAME:TAG

   Example

   $ cosign tree example.io/hello-world:latest
   📦 Supply Chain Security Related artifacts for an image: example.io/hello-world@sha256:7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35
   └── 💾 Attestations for an image tag: example.io/hello-world:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.att
      └── 🍒 sha256:40d94d96a6d3ab3d94b429881e1b470ae9a3cac55a3ec874051bdecd9da06c2e
   └── 🔐 Signatures for an image tag: example.io/hello-world:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.sig
      └── 🍒 sha256:f32171250715d4538aec33adc40fac2343f5092631d4fc2457e2116a489387b7

8. Verify the container image with Enterprise Contract:

   Syntax

   ec validate image --image IMAGE_NAME:TAG \
   --certificate-identity-regexp 'SIGNER_EMAIL_ADDR' \
   --certificate-oidc-issuer-regexp 'keycloak-keycloak-system' \
   --output yaml --show-successes

   Example

   $ ec validate image --image example.io/hello-world:latest \
   --certificate-identity 'jdoe@example.com' \
   --certificate-oidc-issuer 'keycloak-keycloak-system' \
   --output yaml --show-successes
   
   success: true
   successes:
     - metadata:
         code: builtin.attestation.signature_check
       msg: Pass
     - metadata:
         code: builtin.attestation.syntax_check
       msg: Pass
     - metadata:
         code: builtin.image.signature_check
       msg: Pass
   ec-version: v0.1.2427-499ef12
   effective-time: "2024-01-21T19:57:51.338191Z"
   key: ""
   policy: {}
   success: true

   Enterprise Contract generates a pass/fail report with details about any security violations. When you add the --info flag, the report includes more details and possible solutions for any violations.