Extending Witness Policies: Adding Support for Retained Attestations

[colek42]

Purpose

To enhance the Witness policy framework by incorporating a mechanism for handling attestations that are not tied to specific steps but are essential for validation throughout the lifecycle of an artifact.

Schema Extension

New Field: retainedAttestations

A new field, retainedAttestations, will be added to the policy schema. This field will specify attestations that should be retained and validated, even if they are not associated with a particular step.

Updated Policy Schema Example:

{
  "expires": "2024-12-31T23:59:59Z",
  "roots": {
    "rootKeyId": {
      "certificate": "base64 encoded certificate"
    }
  },
  "publickeys": {
    "publicKeyId": {
      "keyid": "publicKeyId",
      "key": "base64 encoded key"
    }
  },
  "steps": {
    "build": {
      "name": "build",
      "attestations": [
        {
          "type": "https://witness.dev/attestations/command-run/v0.1",
          "regopolicies": [
            {
              "name": "cmd-policy",
              "module": "base64 encoded rego module"
            }
          ]
        }
      ]
    }
  },
  "retainedAttestations": {
    "attestations": [
      {
        "type": "https://in-toto.io/attestation/vulns/v0.1",
        "regopolicies": [
          {
            "name": "vuln-policy",
            "module": "base64 encoded rego module"
          }
        ]
      }
    ],
    "functionaries": [
      {
        "type": "publickey",
        "publickeyid": "publicKeyId"
      }
    ]
  }
}

Field Descriptions

• retainedAttestations: Defines attestations to be validated outside of specific steps.
  • attestations: Lists attestation types and associated Rego policies.
    • type: Specifies the attestation type (e.g., "vulnerability").
    • regopolicies: Array of Rego policies to validate the attestation.
      • name: The name of the policy.
      • module: The base64 encoded Rego module.
  • functionaries: Lists trusted functionaries authorized to sign these attestations.

Implementation Steps

1. Update Policy Parsing:

   • Modify the policy parser to recognize and handle the retainedAttestations field, ensuring it correctly loads and validates the specified attestations and Rego policies.

2. Incorporate Validation Logic:

   • Extend the verification process to include validation of retained attestations according to the criteria set out in the policy. This should be integrated with existing validation workflows. We should inspect the subjects to ensure either the input hash, product, or a backref subject matches the subject on the retained attestation.

3. Revise Documentation and Tools:

   • Update documentation to reflect the new capabilities, providing clear examples and guidance on how to configure and use the retainedAttestations field.
   • Ensure that any tools or utilities used for policy management are updated to support the new field.

Example Use Case

Consider a scenario where vulnerability attestations are required for compliance but are not associated with specific steps such as "build" or "deploy." By defining these as retained attestations, they can be validated independently, ensuring consistent compliance checks throughout the artifact lifecycle.