tejolote

A highly configurable build executor and observer designed to generate signed SLSA provenance attestations about build runs.

What Does That Mean!?

If you are not familiar with provenance attestations, think of them as non-falsifiable documents that inform you users how software was built, mainly:

What went in → What was done to the source code (and by who) → what came out.

A provenance attestation provides users with full transparency to the build process of the software they consume, allowing them to know where it came from, how it was built and by who.

Key Features

Tejolote is designed to observe build systems as they run to gather data about transformations done to software as it goes through the build process. It features a pluggable model to add more build systems and artifact storage as the need arises.

• Support for multiple build systems (currently Google Cloud Build, Github Actions, Prow coming soon).
• Support for gathering attestation data in multiple stages or observing a build while it runs.
• Collection of artifacts from different sources (build system native, directories, OCI registries, Google Cloud Storage buckets).
• Attestation signing using sigstore
• Attaching attestations to container images as cosign

Operational Model

Tejolote watches your build system build (or transform) your software project. It treats your build as a black box and makes no assumptions as to the security of the build itself.

It will trust the inputs you tell it to consider and the artifacts your build produces by looking a the location you instruct it too look for them.

flowchart LR

 subgraph Build System
   direction LR
   clone("Clone Repository") --> build(Run Build) --> publish(Publish Artifacts)
   fetch("Fetch Materials") --> build
   publish --> oci(Container Registry)
   publish --> gcs(GCS Bucket)
   publish --> file(Filesystem)
end
subgraph Tejolote
  direction LR
  watch(Watch Build System) --> attest(Attest) --> sign(Sign)
watch-. RECORD .-o clone
watch-. RECORD .-o fetch
watch-. CONTINOUSLY OBSERVE .-o build
watch-. COLLECT .-o publish
end

Loading

While build systems can themselves provide information about the artifacts produced after a run, Tejolote sits one level above and will expect artifacts to appear in the storage location(s) you tell it to monitor.

GitHub Actions artifacts

When attesting a GitHub Actions run, Tejolote collects the run's uploaded artifacts automatically. Because the Actions API serves each artifact as a zip archive, Tejolote unpacks them by default and records one subject per contained file, hashed by its content and named by its path within the zip. Pass --expand-artifacts=false to attest each archive as a single subject instead.

If you pass one or more --artifacts sources, Tejolote collects only from those and skips the run's native artifacts — so you can point it at a directory of files you prepared yourself instead of the automatically-collected artifacts.

--artifacts-filter limits what gets attested from the artifacts source: pass one or more globs (path.Match syntax) matched against each artifact's base name (the last element of its path). Any artifacts matching any of the globs are attested (added to the statement's subject). Repeat the flag or pass a comma-separated list. For GitHub Actions, the match is applied to the artifact name before download; for all other sources, it is applied to the collected artifact names:

tejolote attest github://my-org/my-repo/12345 \
   --artifacts-filter='release-*' \
   --artifacts-filter='*.sbom'

Example

Let's say for example you want to attest a Cloud Build job that produces a bunch of binaries in a GCS bucket. In this case, the gcb project is example-project and artifacts are uploaded to the bucket test-bucket in the directory /test:

tejolote attest \
   gcb://kubernetes-release-test/3190d867-f2e5-4969-aafd-0117b6c8ed12 \
   --artifacts=gs://ulabs-cloud-tests/test/

These are made up examples, but Tejolote would produce an attestation similar to this:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "gs://ulabs-cloud-tests/test/bom-windows-amd64.exe",
      "digest": {
        "sha256": "c03c50f220b095bf52a0ca496989a6c07f198d03cb8aad19834df143625ee821"
      }
    }
  ],
  "predicate": {
    "builder": {
      "id": ""
    },
    "buildType": "https://cloudbuild.googleapis.com/CloudBuildYaml@v1",
    "invocation": {
      "configSource": {}
    },
    "buildConfig": {
      "steps": [
        {
          "image": "gcr.io/cloud-builders/git",
          "arguments": [
            "clone",
            "https://github.com/kubernetes/release"
          ]
        },
...

Both build system runs and artifact repositories are specified by using spec urls that point to the specific runs and storage location. Check out the

What's with the name?

Tejolote /ˌteɪhəˈloʊteɪ/ : From the nahua word texolotl.

A tejolote is the handle of the molcajete, the prehispanic mortar used to make salsa.

So, the idea is to use tejolote to get some salsa out of your project :)