= Policy Input

The policy input refers the variable `input` in rego. This page describes the structure of the input
available for policy evaluation when using the Conforma CLI. The input is different for
each subcommand as each subcommand has a different specialty.

== Validate Image

The input format for the `validate image` command describes all the information related to the image
being available. Not all information is available for all images. This is noted below in the
description of each attribute.

It is important to note that this command may proccess multiple images at the same time. In such
cases, a different input is generated for each image. In other words, policy rules only ever have
access to the information about a single image.

[,json]
----
{
    "attestations": [
        {
            "statement": {
                "_type": "https://in-toto.io/Statement/v0.1",
                "predicate": {...},
                "predicateType": "https://slsa.dev/provenance/v0.2",
                "subject": [...],
            },
            "signatures": [...#SignatureDescriptor]
        }
    ],
    "image": #ImageDescriptor
    "snapshot": #SnapshotDescriptor
}

#ImageDescriptor: {
    "config": {...},
    "parent": #ImageDescriptor,
    "ref": "<STRING>",
    "signatures": [...#SignatureDescriptor],
    "files": {...},
    "source": #SourceDescriptor
}

#SignatureDescriptor: {
    "keyid": "<STRING>",
    "sig": "<STRING>",
    "certificate": "<STRING>",
    "chain": [..."<STRING>"],
    "metadata": {...}
}

#SourceDescriptor: {
    "git": {
        "revision": "<STRING>",
        "url": "<STRING>"
    }
}

#SnapshotDescriptor: {
    "application": "<STRING>",
    "displayName": "<STRING>",
    "displayDescription": "<STRING>",
    "components": [..."#SnapshotComponentDescriptor"]
}

#SnapshotComponentDescriptor: {
    "name": "<STRING>",
    "containerImage": "<STRING>",
    "source": #SourceDescriptor"
}
----

`.attestations` is an array of objects. Each object contains the `.statement` and the `.signatures`
attributes. `.statement` represents a SLSA Provenance v0.2 statement. See
https://slsa.dev/provenance/v0.2#schema[schema] for details. `.signatures` contains information
about the signatures associated with the statement.

`.image` is an object representing the image being validated.

`.image.config` holds the OCI config for the image. It may contain various attributes, such as
`.Labels`, `Env`, and `Cmd`. The set of attributes available depends on what is set on the OCI image
config. See the https://github.com/opencontainers/image-spec/blob/main/config.md#properties[config property definition] for more details.

`.image.parent` is an ImageDescriptor for the parent image of the image being validated. This is
only present if the image being validated contains the
https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys[expected annotations]: `org.opencontainers.image.base.name` and
`org.opencontainers.image.base.digest`.

`.image.ref` is a string containing a reference to the image. A digest is always included, but a tag
is not.

`.image.signatures` is an array of signature descriptors associated with the image.

The contents of the SignatureDescriptor objects varies depending on the form of signature validation
used. `.keyid` holds the ID of the key used for signing. `sig` is the signature of the resource.
`.certificate` and `chain` holds PEM encoded certificates. These two are only available when
short-lived keys are used, aka keyless workflow.

NOTE: Use the `policy-input` output format to save the input object to a file, e.g. `ec validate
image ... --output=input.jsonl`.

`.image.files` is an object where each attribute represents the full path of a file within the image,
and the value is the content of such file converted to JSON format. Paths do *not* start with a
leading `/`. If the contents of a file cannot be converted to JSON format, that file is skipped.
Currently, there are two sets of files that may be included. First, if the image contains the label
`operators.operatorframework.io.bundle.manifests.v1`, all the files within the path specified by the
label are included. If the image contains the label `vendor` and its value is `Red Hat, Inc.`, then
all files under `root/buildinfo/content_manifests` are included.

`.image.source` contains information about the source code used to generate the image. Currently, the
only version control system supported is `git`. This information originates from the
ApplicationSnapshot provided to the `ec validate image` command. It is empty if the source
information is not given to the command.

The SourceDescriptor contains the single `git` attribute which holds an object with information
about a git repository. `.revision` is a string holding a git reference. This could be a commit ID,
branch, etc. `url` is the URL of the git repository.

The SnapshotDescriptor contains the information about the application snapshot provided to the `ec validate image` command. `.application` is a string holding the name of the application. `.displayName` is a string holding the display name of the application. `.displayDescription` is a string holding the display description of the application. `.components` is an array of SnapshotComponentDescriptor objects.

The SnapshotComponentDescriptor contains the information about the components of the application snapshot provided to the `ec validate image` command. `.name` is a string holding the name of the component. `.containerImage` is a string holding the container image of the component. `.source` is a SourceDescriptor object.
