Managing compliance with Conforma

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"]}
           }
       ]
   }' ...

   Copy to Clipboard Toggle word wrap

2. (Optional) Exclude a particular package of rules from your Conforma 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"
           ]
         }
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

   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"
           ]
         }
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

   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"
           ]
         }
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

   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 Conforma 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": [
             ""*"",
             "attestation_task_bundle.unacceptable_task_bundle"
           ],
           "exclude": [
             "attestation_task_bundle.*"
           ]
         }
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

   asterisk (*)

   The asterisk (*) acts as a wildcard to match any package. It does not match partial names. For example, you cannot 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 Conforma 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"
           ]
         }
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

   This command specifies that, if either of the identified checks fails or does not complete, Conforma 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" in the upstream Conforma documentation.

   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 or exclude a particular package policy rule.

   @collection name

   Add this to your string to specify a predefined collection of rules. Prefix the collection name with the @ symbol. Choose from the available rule collections.

Procedure

1. Generate a key pair by running the following command:

   $ cosign generate-key-pair

   Copy to Clipboard Toggle word wrap
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 OCP cluster:

   1. Log in to the OpenShift Container Platform 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.

   4. Decompress the .gz file by running the following command:

      $ gunzip ec-amd64.gz

      Copy to Clipboard Toggle word wrap

   5. Make the ec binary file executable by running the following command:

      $ chmod +x ec-amd64

      Copy to Clipboard Toggle word wrap

   6. Move the ec binary file to a directory within your $PATH environment. For example:

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

      Copy to Clipboard Toggle word wrap
      Tip

      Run the ec validate image --help command to see all the image validation command options.

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

   1. Navigate to the sigstore-ocp directory by running the following command:

      $ cd sigstore-ocp

      Copy to Clipboard Toggle word wrap

   2. Configure the shell by running the tas-env-variables.sh script:

      $ source tas-env-variables.sh

      Copy to Clipboard Toggle word wrap

   3. (Optional) Set the environment variables manually:

      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

      Copy to Clipboard Toggle word wrap

      $ source ./tas-env-vars.sh

      Copy to Clipboard Toggle word wrap

3. Initialize The Update Framework (TUF) system by running the following command:

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

   Copy to Clipboard Toggle word wrap

4. Sign your container image by running the following command:

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

   Copy to Clipboard Toggle word wrap

   For example:

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

   Copy to Clipboard Toggle word wrap

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

5. Create a predicate.json file:

   {
     "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": []
   }

   Copy to Clipboard Toggle word wrap

6. Associate the predicate.json file with your container image by running the following command:

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

   Copy to Clipboard Toggle word wrap

   For example:

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

   Copy to Clipboard Toggle word wrap

7. Verify that the container image has at least one attestation and signature by running the following command:

   $ cosign tree IMAGE_NAME:TAG

   Copy to Clipboard Toggle word wrap

   For 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

   Copy to Clipboard Toggle word wrap

8. Verify the container image with Conforma by running the following command:

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

   Copy to Clipboard Toggle word wrap

   For 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

   Copy to Clipboard Toggle word wrap

   Use the output to verify the container image:

   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

   Copy to Clipboard Toggle word wrap

   Conforma generates a pass or 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.