# Ratify Attestation Exploration

This document is evolving and will be updated as new discussions/information comes about.

## Sample Scenario

User has a CI/CD pipeline used for deploying container images to their cluster.

**Prerequisite steps**:

1. Image is built
2. Various CSSC workflows are applied (e.g signing, SBOM, vuln scanning, lifecycle metadata, provenance)
3. Image + artifact pushed to registry

**Deployment Pipeline**:

1. Ratify binary is installed on the CI/CD agent.
2. Ratify CLI is used to `verify` the deployment-candidate image. Ratify is configured with verifiers, stores, and Rego policy.
3. Ratify `attest` to the result of the verification. Attestation contains:
* Rego Policy applied
* Ratify configuration used
* Verifier Reports generated
* Overall verifier result
* Timestamp of attestation
* Attestation signature of the payload content defined above
4. Ratify pushes attestation as a referrer to the deployment-candidate image.

**Kubernetes Admission time**:

Verify attestation verifier:
1. Verify signature embedded in attestation (notary, cosign)
2. Check timestamp for 'freshness'
3. Check overall result is PASSED

TODO: **Kubernetes Audit**

TODO: Discuss re-attestation approach
The initial attestation needs to have an expiry date to trigger a re-attestation. In cluster, a Cron Job could be used?

TODO: Explore potential artifact tree hash as a snapshot. Hash all the digests of the artifacts attached to an image. On verification of the attestation, generate the same hash for the image at that point of time and make sure it is the same. This should guarantee no artifacts have been tampered with or added and the ratify verification is still applicable at that specific point in time.

TODO: How does attestation revocation work? ex: cert used for sig on an image is revoked. attestation already generated and shows as passed. now attestation is out of date.

## Attestation Details

Current investigation focuses on [in-toto](https://github.com/in-toto/attestation/blob/main/docs/README.md) attestation format.

### In-toto high-level overview


[DSSE](https://github.com/deislabs/ratify/tree/main/library) envelope contains the `payloadType`, `payload`, and `signature`. Signature has `keyid` and `sig`:

{
  "payload": "<Base64(SERIALIZED_BODY)>",
  "payloadType": "<PAYLOAD_TYPE>",
  "signatures": [{
    "keyid": "<KEYID>",
    "sig": "<Base64(SIGNATURE)>"
  }]
}

For in-toto, the statement is the payload, and the payload contains the subject which references the subject image the content is generated based off of. The `predicateType` is a well-known URI indicating the type of artifact encapsulated in the `predicate`.

> NOTE: the in-toto specification decoupled envelope type from the schema leaving the door open for other envelopes to be support (e.g COSE, JWS, etc.)

In-toto has different default predicate types. List can be found [here](https://github.com/in-toto/attestation/blob/main/spec/predicates/README.md#vetted-predicates).

### Should Ratify define a new predicate or use an existing one?

There a couple existing predicates (Test Result, VSA, SCAI) that may be potential candidates. There is a a new Deployment Attestation (DA) that may closer fit the use case.

#### Test Result

Read more details [here](https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md). This predicate is primarily meant for testing pipeline reports and does not fit exactly for deployment scenarios.

Test Result Sample format:

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{...}],
    "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
    "predicate": {
        "result": "PASSED|WARNED|FAILED",
        "configuration": ["<ResourceDescriptor>", ...],
        "url": "<URL>",
        "passedTests": ["<TEST_NAME>", ...],
        "warnedTests": ["<TEST_NAME>", ...],
        "failedTests": ["<TEST_NAME>", ...]
    }
}

Potential Ratify Attestation based on Test Result predicate:

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [
        {
            "digest": {
                "sha256": "abc123...."
            }
        }
    ],
    "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
    "predicate": {
        "result": "PASSED",
        "configuration": [{
            "policy": "<INSERT REGO POLICY>",
            "ratifyConfig": "<INSERT RATIFY CONFIG JSON>",
            "timestamp": "<VERIFICATION TIMESTAMP>"
        }],
        "url": "<INSERT DEPLOY PIPELINE RUN LINK>"
}

### VSA

### SCAI

### DA