# SLSA Provenance {#provenance}

各イメージには、[SLSA](https://slsa.dev/) 形式の Provenance ステートメントが、署名付き attestation として付属します。
これは、ビルドに使った入力、つまりどのソースリビジョンを、どのワークフローの実行でビルドしたかを記録したものです。
そのため検証では、イメージの中身だけでなく、それがどこから来たビルドなのかも確認できます。

:::info
Takumi Images は現在ベータ版です。
仕様や挙動が予告なく変更される可能性があります。
:::

## 記録する内容 {#contents}

predicate には、ビルドの呼び出しと、その入力になった **materials**（ビルドに使ったソースリビジョンなど）、そしてビルドを実行した builder の identity（ワークフローのパスと ref）が記録されます。
predicate type は SLSA v1 の `slsaprovenance1` です。
これらはすべて、リリースワークフローが実行時に持っていた情報そのものであり、後から書き加えたものではありません。

構造は次のとおりです（一部を省略しています）。

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "takumi/curl",
      "digest": { "sha256": "<イメージ tar の sha256>" }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "externalParameters": {
        "image": "takumi/curl",
        "arch": "arm64",
        "nixpkgs": {
          "uri": "https://github.com/NixOS/nixpkgs/archive/<rev>.tar.gz",
          "sha256": "<sha256>"
        }
      },
      "resolvedDependencies": ["（イメージの直接入力になった導出の一覧）"]
    }
  }
}
```

`subject` の digest は、リリース時に検証している非圧縮 tar のハッシュです。
`externalParameters` には、ビルドを完全に決める pin（nixpkgs のリビジョンとハッシュ）が入ります。
つまりこの predicate は、「どの入力とどのワークフローから、このハッシュのイメージが作られたか」を後から確認するための記録です。

## 再現可能ビルドとの関係 {#reproducibility}

Provenance が記す入力は、それだけでは主張にとどまります。
この記述を裏づけているのが、再現可能ビルドです。
各イメージは、宣言した入力だけで結果が決まる Nix の式としてビルドしており、同じ入力から同じイメージをビルドし直すと、ビット単位で一致することを CI が検証しています。
利用者は、この Provenance と署名を検証することで、公開されたイメージがどの入力とリリースワークフローに紐づくものかを確認できます。
ビルドがどのように再現可能な結果を生んでいるかは、[ビルドパイプラインの概要](/docs/ja/t/images/architecture/build-pipeline)を参照してください。

## 検証方法 {#verify}

Provenance はアーキテクチャごとに内容が変わるので、SBOM と同じく、アーキテクチャごとのイメージに添付します。
まず index から目的のアーキテクチャの子 digest を取り出し、その Provenance を `--type slsaprovenance1` で検証します。

```bash
CHILD_DIGEST=$(crane manifest images.flatt.tech/takumi/busybox:latest \
  | jq -r '.manifests[] | select(.platform.architecture=="amd64").digest')

cosign verify-attestation \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github.com/flatt-security/takumi-images/.github/workflows/release.yml@.*' \
  --type slsaprovenance1 \
  "images.flatt.tech/takumi/busybox@${CHILD_DIGEST}" \
  | jq -r '.payload' | base64 -d | jq '.predicate'
```

この attestation を信頼できるものにしている署名の仕組みは、[Attestation](/docs/ja/t/images/features/attestations/#verify-attestation) を参照してください。