# Predicate type: Software Supply Chain Attribute Integrity (SCAI)

Type URI: https://in-toto.io/attestation/scai

Version: 0.3

Author: Marcela Melara ([@marcelamelara](https://github.com/marcelamelara))

## Purpose

The Software Supply Chain Attribute Integrity, or SCAI (pronounced "sky"),
specification proposes a data format for capturing functional attribute and
integrity information about software artifacts and their supply chain. SCAI
data can be associated with executable binaries, statically- or dynamically-
linked libraries, software packages, container images, software toolchains,
and compute environments.

Existing supply chain data formats do not capture any information about the
security functionality or behavior of the resulting software artifact, nor
do they provide sufficient evidence to support any claims of integrity of
the supply chain processes they describe. The SCAI data format is designed
to bridge this gap.

For more details, see the [SCAI specification] document.

## Use Cases

We highlight three core use cases of SCAI, although there may be others.

### Fine-grained software attributes

A producer seeks to make assertions about fine-grained code-level attributes
of the attestation `subject`. Examples of such code-level attributes include
include cases like code features instrumented by a compiler, or properties
tested via static analysis.

See an example for [attested binary attributes](#attestation-for-binary-attributes-with-evidence) below.

### Producer compute platform attributes

A producer seeks to assert certain properties about its underlying compute
platform, which produced the `subject`. Examples of compute platform
attributes include properties like secure boot enablement or trusted
execution enablement. Since these types of attributes are often accompanied
by an attestation document, these hardware attestations serve as evidence
for the asserted attributes.

See an example for a [build on attested hardware](#attestation-for-build-on-intelr-sgx-hardware) below.

### Evidence collection

A producer seeks to assert that a collection of evidence or attestations
applies to the `subject`. In essence, this use case serves to bind multiple
attestations to a single `subject`. For example, the asserted attributes
may correspond to specific attestation types.

See an example for an [evidence collection](#attestation-for-evidence-collection) below.

## Prerequisites

In addition to the in-toto Attestation Framework, SCAI assumes that
implementers have appropriate processes and tooling in place for capturing
other types of software supply chain metadata, which can be extended to add
support for SCAI.

## Model

SCAI metadata, referred to as an Attribute Assertion, describes functional
attributes of a software artifact and its supply chain, capable of covering
the full software stack of the toolchain that produced the artifact down to
the hardware platform. SCAI Attribute Assertions include information about
the conditions under which certain functional attributes arise, as well as
(authenticated) evidence for the asserted attributes.

The set of Assertions about a subject artifact and its producer is referred
to as the **Attribute Report**. Similarly, SCAI Attribute Reports about the
producer of a subject artifact can be generated separately, with the
attestation subject indicating an artifact producer.

We emphasize that this predicate does not dictate the types of attributes
that can be attested, nor does it prescribe any format to the evidence for an
assertion.

SCAI is intended to be implemented as part of an existing software supply
chain attestation framework by software development tools or services (e.g.,
builders, CI/CD pipelines, software analysis tools) seeking to capture more
granular information about the attributes and behavior of the software
artifacts they produce.

As such, we envision SCAI metadata being explictly bound to, or included
within, other metadata objects; we recommend an in-toto [attestation Bundle]
for this purpose.

## Schema

The core metadata in SCAI is the Attribute Assertion. A collection of
Attribute Assertions for a specific supply chain step or operation are issued
together in a SCAI Attribute Report predicate.

```jsonc
{
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "<ATTRIBUTE>",
            "target": { [ResourceDescriptor] }, // optional
            "conditions": { /* object */ }, // optional
            "evidence": { [ResourceDescriptor] } // optional
        }],
        "producer": { [ResourceDescriptor] } // optional
    }
}
```

This predicate has been adapted from the [SCAI specification] for greater
interoperability.

### Parsing Rules

At a high-level, Attribute Reports MUST allow humans and programs to easily
parse the asserted attributes. Additional fields MUST enable program-based
consumers to automatically parse and evaluate the given information.

The following parsing rules apply in addition:

-   Consumers MUST ignore unrecognized fields.
-   Producers SHOULD omit _optional_ fields when unused to avoid ambiguity.
-   Acceptable formats of the `attribute` and `conditions` fields are up to
    the producer and consumer.
-   Because consumers evaluate this predicate against a policy, the semantics
    SHOULD be consistent and monotonic between attestations (see in-toto
    Attestation Framework [parsing rules]).

### Fields

`predicateType` _string ([TypeURI]), required_

> Identifier for the schema of the Attribute Report. Always
> `https://in-toto.io/attestation/scai/v0.3` for this version of the
> spec.

`predicate.attributes` _array of objects, required_

> An array of one or more SCAI Attribute Assertions about the subject.

`predicate.attributes[*].attribute` _string, required_

> A string describing a specific functional feature of the attestation
> subject or producer.
>
> Attributes are expected to be domain- or application-specific.

`predicate.attributes[*].target` _object ([ResourceDescriptor]), optional_

> An object reference to a specific artifact or metadata object to which the
> `attribute` field applies.
>
> The producer and consumer SHOULD agree on the ResourceDescriptor fields
> needed for identification and validation of the target.

`predicate.attributes[*].conditions` _object, optional_

> An object representing specific conditions under which the associated
> attribute arises.

`predicate.attributes[*].evidence` _object ([ResourceDescriptor]), optional_

> A description of (authenticated) evidence for the asserted `attribute`.
>
> If the evidence object is generated by the producer in conjunction with the
> SCAI predicate the producer MAY include the attestation for the evidence
> object in the same in-toto [attestation Bundle],
>
> The producer and consumer SHOULD agree on the ResourceDescriptor fields
> needed for identification and validation of the evidence.
>
> When `evidence` is omitted, a consumer MAY choose to evaluate the
> atestation on the basis of the producer's identity.

`predicate.producer` _object, ([ResourceDescriptor]) optional_

> A description of the producer of the attestation subject, if applicable.
>
> The producer and consumer SHOULD agree on the ResourceDescriptor fields
> needed for identification and validation of the producer.

## Examples

### Attestation for binary attributes

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "my-app",
        "digest": { "sha256": "78ab6a8..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "WITH_STACK_PROTECTION",
            "conditions": { "flags": "-fstack-protector*" },
        }],
        "producer": {
            "uri": "file:///usr/bin/gcc",
            "name": "gcc9.3.0",
            "digest": {
                "sha256": "78ab6a8..."
            },
            "downloadLocation": "http://us.archive.ubuntu.com/ubuntu/pool/main/g/gcc-defaults/gcc_9.3.0-1ubuntu2_amd64.deb"
        }
    }
}
```

### Attestation for gcc compiler attributes

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "gcc9.3.0",
        "digest": { "sha256": "78ab6a8..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "WITH_STACK_PROTECTION",
            "conditions": { "flags": "-fstack-protector*" }
        },
        {
            "attribute": "REPRODUCIBLE",
            "evidence": {
                "name": "gcc_9.3.0-1ubuntu2_amd64.json",
                "digest": { "sha256": "abcdabcde..." },
                "uri": "http://example.com/rebuilderd-instance/gcc_9.3.0-1ubuntu2_amd64.json",
                "mediaType": "application/x.dsse+json"
            }
        }]
    }
}
```

### Attestation for binary attributes with evidence

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "my-app",
        "digest": { "sha256": "78ab6a8..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "WITH_STACK_PROTECTION",
            "conditions": { "flags": "-fstack-protector*" },
            "evidence": {
                "name": "gcc9.3.0-attribute-report.json",
                "digest": { "sha256": "abcdabcde..." },
                "mediaType": "application/x.dsse+json"
            }
        }],
        "producer": {
            "uri": "file:///usr/bin/gcc",
            "name": "gcc9.3.0",
            "digest": {
                "sha256": "78ab6a8..."
            },
            "downloadLocation": "http://us.archive.ubuntu.com/ubuntu/pool/main/g/gcc-defaults/gcc_9.3.0-1ubuntu2_amd64.deb"
        }
    }
}
```

### Attestation for binary with attested dependencies

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "my-app",
        "digest": { "sha256": "78ab6a8..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "ATTESTED_DEPENDENCIES",
            "target": {
                "name": "my-rsa-lib.so",
                "digest": { "sha256": "ebebebe..." },
                "uri": "http://example.com/libraries/my-rsa-lib.so"
            }
            "evidence": {
                "name": "rsa-lib-attribute-report.json",
                "digest": { "sha256": "0987654..." },
                "mediaType": "application/x.dsse+json"
            }
        }],
        "producer": {
            "uri": "https://example.com/my-github-actions-runner",
        }
    }
}
```

### Attestation for build on Intel(R) SGX hardware

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "my-sgx-builder",
        "digest": { "sha256": "78ab6a8..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3"
    "predicate": {
        "attributes": [{
            "attribute": "VALID_ENCLAVE",
            "target": {
                "name": "enclave.signed.so",
                "digest": { "sha256": "e3b0c44..." },
                "uri": "http://example.com/enclaves/enclave.signed.so",
            },
            "evidence": {
                "name": "my-sgx-builder.json",
                "digest": { "sha256": "0987654..." },
                "downloadLocation": "http://example.com/sgx-attestations/my-sgx-builder.json",
                "mediaType": "application/x.sgx.dcap1.14+json"
            }
       }]
    }
}
```

### Attestation for evidence collection

```jsonc
{
    // Standard attestation fields
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "app-evidence-collection",
        "digest": { "sha256": "88888888..." }
    }],
        
    "predicateType": "https://in-toto.io/attestation/scai/v0.3",
    "predicate": {
        "attributes": [{
            "attribute": "attestation-1",
            "evidence": {
                "uri": "https://example.com/attestations/attestation-1"
                "digest": { "sha256": "abcdabcd..." },
                "mediaType": "application/x.dsse+json"
            }
        },
        {
            "attribute": "attestation-2",
            "evidence": {
                "uri": "https://example.com/attestations/attestation-2"
                "digest": { "sha256": "01234567..." },
                "mediaType": "application/x.dsse+json"
            }
        },
        {
            "attribute": "attestation-3",
            "evidence": {
                "uri": "https://example.com/attestations/attestation-3"
                "digest": { "sha256": "deadbeef..." },
                "mediaType": "application/x.dsse+json"
            }
        }],
        "producer": { "uri": "https://my-sw-attestor" }
    }
}
```

## Changelog and Migrations

### New in v0.3

-   Simplify the predicate `TypeURI` suffix from `/scai/attribute-report` to `/scai` per the latest [predicate naming convention].

### New in v0.2

-   Change the `target` and `evidence` field type of a SCAI Attribute
    Assertion to [ResourceDescriptor].
-   Simplify the `producer` field: remove the `type` sub-field, and change
    the field type to [ResourceDescriptor].

[ResourceDescriptor]: ../v1/resource_descriptor.md
[SCAI specification]: https://arxiv.org/pdf/2210.05813.pdf
[TypeURI]: ../v1/field_types.md#typeuri
[attestation Bundle]: ../v1/bundle.md
[parsing rules]: ../v1#parsing-rules
[predicate naming convention]: ../../docs/new_predicate_guidelines.md#vetting-process
