Skip to content

Latest commit

 

History

History
173 lines (123 loc) · 6.79 KB

enterprise-contract.md

File metadata and controls

173 lines (123 loc) · 6.79 KB
Raw

Enterprise Contract

Overview

The Enterprise Contract's purpose is to ensure container images produced by HACBS meet certain clearly defined requirements before they are considered releasable. Should a container image not meet the requirements the Enterprise Contract will produce a list of the reasons why so they can be addressed as required to produce a releasable build.

Enterprise Contract requirements fall broadly into two categories, "built-in requirements"1 and "rule-based requirements".

Built-in requirements

The built-in requirements are as follows:

  • The container image is signed with a known and trusted key
  • The image has an attestation, also signed with a known and trusted key

Rule-based requirements

The rule-based requirements are based on the content of the pipeline run attestation and are defined using Rego, the Open Policy Agent query language.

Some examples of rule-based requirements are:

  • Tasks used in the pipeline run were defined in known and trusted task bundles
  • A defined set of tests were run during the pipeline build with passing results

The technique of checking for a specific task result from a specific known and trusted task definition is a useful way to create a robust policy rule. The rego language is flexible and expressive so it's easy to create arbitrary policy rules based on anything exposed in pipeline run attestation.

Components

EC CLI

The ec-cli is a command line utility written in Go. Its primary purpose is to perform the EC policy validation, which it does as follows:

  • For each image included in the release2
    • Confirm the image is signed and verify the signature
    • Confirm the image has a signed and verifiable attestation
    • For each "policy source group"3 defined in the ECP CRD config:
      • Download all defined policy (rego) sources
      • Download all defined data sources
      • Run Conftest against the image's attestation using those policies and data
  • Output results in JSON format showing details about failures, warnings or violations produced

The ec-cli also supports other related functions. For more information on ec-cli refer to the documentation and the code.

EC Task Definition

The EC Task Definition defines how the ec-cli command should be run in a Tekton task. It handles the task inputs and outputs and calls the ec-cli as needed to perform the EC validation.

The task is defined here.

EC Policy CRD

The ECP CRD defines a Kubernetes CR which is used to hold the configuration needed for running a specific instance of the Enterprise Contract. This includes the public key required to verify signatures, the list of policy and data sources, and any other required configuration.

You can view the source code for the ECP CRD here and see its documentation here. See also the related API Reference

EC Policies

The reference set of policy rules for HACBS is defined here and documented here. It includes rules for a range of different policies that are considered useful for HACBS.

There are Conftest bundles containing the latest version of these policies available in quay.io here.

Related Components

Tekton Chains

Tekton Chains is a dependency for EC since EC works by examining attestations created by Tekton Chains when HACBS build pipelines are running.

For more information on Tekton Chains refer to the documentation, and the GitOps configuration here.

The Release Pipeline

The HACBS Release Pipeline contains an instance of the EC Task which is used to gate the release. If the EC task fails the release should be blocked. This functionality is handled by the Release Pipeline.

For more information, see HACBS Release Bundles.

EC and Renovate Bot

To verify that tasks used in the build pipeline are from known and trusted Tekton bundles, EC requires a list of those bundles.

HACBS users can leverage the Renovate Bot service to keep such Tekton bundle lists up to date. The service can be configured to run periodically, and provide pull requests with updated references. Alternatively, users can run their own instance of Renovate either as a service or on-demand.

Additional Resources

Footnotes

  1. Not sure about the terminology here. Do we have a better term for requirements enforced by ec-cli that are not defined by rego rules? ↩

  2. The list of images in a release is defined in a Snapshot CRD. The input to EC is a JSON formatted representation of this image list, but a single image is also supported. ↩

  3. Not sure about this terminology either. Conceptually the "source group" consists of one or more policy sources and zero or more data sources. ↩