SLSA

Announcing Container-based SLSA 3 Builder on GitHub Actions

2023-06-13T00:00:00+00:00

Following the recent launch of SLSA v1.0, we’re announcing a new, GitHub Actions workflow that achieves SLSA Build Track Level 3 for provenance generation. This lets users generate unforgeable provenance, allowing consumers to trust and verify how their software artifacts were built. The container-based SLSA 3 builder is the result of a collaboration between the Google Open Source Security Team (GOSST), the SLSA community, and Project Oak.

How it works

The new container-based SLSA 3 builder runs a containerised build in a secure environment and generates an unforgeable provenance statement of the execution, all in an ecosystem-agnostic way that’s easy to add to your GitHub CI.

To ensure unforgeability of provenance, the container-based SLSA 3 builder uses the same secure build mechanisms used in other SLSA builders and generators, relying on GitHub reusable workflows and ephemeral VM containers for isolation. For more details, see the technical design document. As before, we rely on OpenID Connect (OIDC) with Sigstore tooling to prove the identity of the workflow. These provide the workflow identity guarantees described in an earlier blog post that announced the generic SLSA 3 generator.

The builder allows a developer to run a custom command in a container in a secure environment, which gives the developer full control of the environment and customization of the container’s function. For example, the developer may choose to use the command to build a binary artifact, or produce metadata like OpenSSF’s Scorecard reports.

Enhanced provenance verification with the new workflow

The container-based SLSA 3 builder differs from earlier builders and generators in the content of the generated provenance statements, and therefore how they can be verified. Like all provenance generated by all SLSA 3 builders and generators, you can trace the binary to its source code and verify the builder’s identity—and now, you can additionally perform detailed verification of the build process.

For instance, the provenance produced by the generic SLSA 3 provenance generator minimally contains the source GitHub repository and a reference to the workflow file that built the artifact. This workflow may contain any operation, ranging from copying a pre-built binary from another resource to running a massive build script. Because the provenance does not include these details, verifiers need to audit the referenced workflow file to establish trust in the build process.

The container-based SLSA 3 builder simplifies and enhances provenance verification by including the build process directly inside the provenance. This is enabled by a Docker-based build tool used internally in the container-based SLSA 3 builder for building the binaries and the new SLSA v1.0 provenance format. In particular, it includes the builder image and command directly inside the build definition:

"buildDefinition":{
  "buildType":"https://slsa.dev/container-based-build/v0.1?draft",
  "externalParameters":{
    "source":{
      "uri":"git+https://github.com/slsa-framework/example-package@v0.1",
      "digest":{
        "sha1":"ca220e54c07b6fcdd758184a12c132ee3ae531f1"
      }
    },
    "builderImage":{
      "uri":"rust@sha256:74ad9d14ec89bc4e83bf2a3d007fd981513ee4b44279b40d3a90c001a6ca938c",
      "digest":{
        "sha256":"74ad9d14ec89bc4e83bf2a3d007fd981513ee4b44279b40d3a90c001a6ca938c"
      }
    },
    "configPath":".github/configs-docker/release-config.toml",
    "buildConfig":{
      "ArtifactPath":"target/release/my-rust-app",
      "Command":[
        "cargo", "build", "--release"
      ]
    }
  }
}

Next Steps

If your builds are already containerized, we encourage you to give the container-based SLSA 3 builder a try—see the step-by-step guide in our onboarding tutorial. Otherwise, we suggest containerizing your build, which also improves the reproducibility of your binaries, and adopting the container-based SLSA 3 builder.

Once you have generated a SLSA provenance with the container-based SLSA 3 builder, the next step to complete the lifecycle is to provide instructions to verify the artifacts, including using the slsa-verifier to verify the provenance. If you are using these artifacts in your own build pipeline, consider threat modeling your software supply chain and building expectations for your build origins and process.

Please share your success stories with us by creating a pull request to add your project to the list of container-based SLSA 3 users. Feel free to create issues on the repository if you have noticed any issues, or are missing features you need. We look forward to fulfilling new requests and accepting new contributors to create even more useful features going forward.

Bringing Improved Supply Chain Security to the Node.js Ecosystem

2023-05-11T00:00:00+00:00

It has been a big month for supply chain security! GitHub recently announced the public beta for npm package provenance. This adds new functionality to npmjs.com and the npm CLI that allows package maintainers to generate and upload SLSA Build Level 2 provenance along with their packages. Integration with Sigstore enables verification of signature and certificate metadata so users know that the package came from the expected source repository.

The SLSA Tooling SIG has been collaborating with GitHub to give npm package authors more options to further harden builds. As part of this collaboration, we are announcing the beta of the SLSA3 Node.js builder for GitHub Actions. The Node.js builder provides a GitHub Actions reusable workflow that can be called to perform the build, generate SLSA Build L3 compliant provenance, and publish it to the npm registry along with the package.

Given that Node.js is one of the largest open source ecosystems, we believe these announcements go a long way towards improving supply chain security for open source overall. As packages adopt SLSA provenance, we hope that npm can serve as a model for more open source ecosystems in the future.

Major Steps in Securing the OSS Supply Chain

GitHub’s first-class support for package provenance in npm is a major step forward in Open Source supply chain security for a number of reasons.

First, it provides a way for package maintainers to generate provenance for their packages with minimal changes to their development workflows. This allows busy Open Source developers to get large supply chain security gains with only a small time investment.

Second, it provides a natural way to host provenance along with the package itself. This takes advantage of existing package tooling to transparently distribute provenance to users so it can be verified easily.

Third, verification can be incorporated into the user’s normal workflow via the npm audit signatures command. Provenance adds the most value if it can be verified before install. Support for verification in the npm CLI makes this much easier.

With this new support the provenance generated by npm projects achieves SLSA Build Level 2. SLSA Build L2 gives projects a huge boost to software supply chain integrity of npm packages. It prevents tampering after the build with digital signatures, reduces the attack surface to one that can be more easily audited and hardened, and allows for easier migration to more hardened SLSA Build levels in the future.

Going Further with SLSA on GitHub Actions

SLSA Build L3 improves upon SLSA Build L2 with additional requirements. These include further hardening the build process by preventing build runs from influencing one another, and preventing secret material used to sign the provenance from being accessible to the build steps. The benefits of the new requirements include preventing tampering during the build, and reducing the impact of compromised registry credentials.

These advantages are important because package installs and builds can run untrusted and potentially compromised code from dependencies and other sources. This in turn could allow attackers to leak private keys, modify provenance or generate provenance for other artifacts. As we have seen in the past, open source packages are not immune to these targeted attacks.

The Node.js builder, built in collaboration with GitHub, does this by executing the build, generation, and signing of provenance in separate jobs separated by a virtual machine (VM) security boundary provided by GitHub-hosted runners.

Using the Node.js builder is as easy as making a GitHub Actions reusable workflow call. Most packages can slot this into their workflows fairly seamlessly.

jobs:
  build:
    permissions:
      id-token: write # For signing
      contents: read  # For repo checkout.
      actions: read   # For getting workflow run info.
    if: startsWith(github.ref, 'refs/tags/')
    uses: slsa-framework/slsa-github-generator/.github/workflows/builder_nodejs_slsa3.yml@v1.6.0
    with:
      run-scripts: "ci, build"

Learn more about Node.js builder in the documentation.

Exploring and monitoring the npm package security landscape

In addition to the direct security benefits provided by SLSA, provenance provides more information on packages, improving their trustworthiness. The SLSA Tooling SIG has collaborated with Google Open Source Insights (deps.dev) to support exploration of provenance metadata for npm packages. This new feature will support both npm package provenance and provenance generated by the SLSA3 Node.js builder and can be used in conjunction with the npm official registry.

Explore some packages that generate provenance today:

The value of cooperation

Support for SLSA provenance in the npm public registry is a great step forward for improving the supply chain security of open-source projects. As we move forward, improved support for supply chain security and cooperation with programming language ecosystems is vital and we are looking forward to working with more ecosystems in the future.

Please try out the new Node.js builder and let us know what you think by opening an issue on GitHub. You can also ask a question in the #slsa-tooling channel in the OpenSSF community slack. We would love to hear from you! You can follow along with the development of the Node.js builder’s GA release via our development milestone.

See you soon!

in-toto and SLSA

2023-05-02T00:00:00+00:00

As an adopter of SLSA, you have likely encountered the in-toto project. in-toto attestations are part of SLSA’s recommended suite for expressing software supply chain claims. As in-toto maintainers, we’ve interacted with a number of people who know of in-toto through SLSA but don’t fully understand the project. For example, some were surprised to learn that “in-toto isn’t just a format of attestations”, and that the framework also defines verification workflows that make use of attestations that are not SLSA Provenance. So, we decided to author this post as a quick primer on in-toto, how SLSA uses in-toto, and how other attestations can be used to complement SLSA.

in-toto Primer

The in-toto Attestation Framework defines a fixed, lightweight “Statement” that communicates some information about the execution of a software supply chain, such as if the source was reviewed, or if it went through a SLSA conformant build process. The information is communicated as a “Predicate” using a context-specific schema identified by a “Predicate Type”, and applies to one or more software supply chain “Subjects”. SLSA Provenance is one such predicate type.

in-toto models the software supply chain as a series of “steps”. Supply chain owners, i.e. project owners or maintainers, define the set of actors authorized to perform each step and rules that govern the artifacts used and produced by the step. They can also include other arbitrary checks called “inspections” to be performed during the verification workflow. These policies are recorded in a piece of metadata called a supply chain “Layout”, which is cryptographically signed by the supply chain owners. As each step is performed, one or more attestations are generated recording various aspects of the process, and during verification, in-toto applies the policies in the layout against the set of attestations produced during the execution of the supply chain.

What SLSA gets from in-toto?

SLSA v1 is focused on the build aspects of the software supply chain. It defines the Provenance predicate to record the build characteristics of the produced artifacts. The specification describes how to verify Provenance as well as lays out other requirements that are to be verified separately. The SLSA community has also indicated a future source track focused on the security posture of how source is stored and developed prior to being fed into a build process.

This is where other in-toto predicate types can complement SLSA. in-toto allows for defining use case specific predicates that contain contextual information. Apart from SLSA Provenance, the framework currently lists definitions for in-toto Links, results of runtime traces, Software Bill of Materials (SBOM) specifications such as SPDX and CycloneDX, the Software Supply Chain Attribute Integrity (SCAI) specification, and SLSA Verification Summary Attestations. in-toto also has a process for members of the community to propose new predicate types. Proposals are reviewed by the maintainers of the project who are supply chain security stakeholders at Google, Verizon, Intel, Kusari, and TestifySec. This ensures that predicate types are of high quality, useful to different organizations and their specific use cases, and, most importantly, consistent so that attestations are usable beyond organization boundaries.

With the upcoming enhancements to in-toto layouts, supply chain owners can define granular policies for all of the different predicates they generate during the execution of their software supply chain. For example, they can embed SLSA Provenance specific checks alongside others that verify best practices such as two party code reviews, successful test runs, and so on were adhered to. Taken together, a bundle of in-toto attestations and a layout can be used to comprehensively verify a software supply chain’s security posture.

End-to-end attestations for your software supply chain

Let’s take a look at how other in-toto attestations can complement SLSA Provenance. Here are a series of attestations (truncated where necessary) for the execution of a supply chain. For the sake of this example, the attestations are presented without their outer signing layer; in the real world, they’d all be signed by the actors performing the corresponding operations.

Check out the source code

First, the source repository is checked out and its Git commit is recorded using an in-toto link.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "foo",
        "digest": {
            "gitCommit": "abcdef123456"
        }
    }],
    "predicateType": "https://in-toto.io/attestation/link/v0.3",
    "predicate": {
      "name": "checkout",
      "command": "git clone https://git.example.com/foo.git",
      "materials": {},
      "byproducts": {},
      "environment": {}
    }
}

Is the code reviewed?

The attestation bundle includes a code review for the commit that was checked out.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "foo",
        "digest": {
            "gitCommit": "abcdef123456"
        }
    }],
    "predicateType": "https://in-toto.io/attestation/human-review/v0.1",
    "predicate": {
        "result": "PASSED",
        "reviewLink": "https://cr.example.com/foo/abcdef123456",
        "timestamp": "2023-04-02T12:34:23Z"
    }
}

Run tests

Prior to actually executing the build, the source’s tests are run. This test run and its results are recorded as a standalone attestation.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "foo",
        "digest": {
            "gitCommit": "abcdef123456"
        }
    }],
    "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
    "predicate": {
        "result": "PASSED",
        "configuration": [{
            "name": "foo/test.yml",
            "digest": {
                "gitBlob": "123456abcd"
            }
        }],
        "url": "https://ci.example.com/23048",
        "passedTests": ["(test.yml, ubuntu-latest)", "(test.yml, windows-latest)"],
        "warnedTests": [],
        "failedTests": []
    }
}

Build the final product

The build service performs the actual build itself and records SLSA Provenance of the resulting artifact.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "bin/foo-v1.1",
        "digest": {
            "sha256": "ff332109abdd"
        }
    }],
    "predicateType": "https://slsa.dev/provenance/v1",
    "predicate": {
        "buildDefinition": {
            "buildType": "<buildType>",
            "externalParameters": {
                "repository": "https://git.example.com/foo.git",
                "ref": "refs/heads/main"
            },
            "resolvedDependencies": [{
                "name": "foo",
                "uri": "git+https://git.example.com/foo@refs/heads/main",
                "digest": {
                    "gitCommit": "abcdef123456"
                }
            }],
        },
        "runDetails": {
            "builder": {
                "id": "https://ci.example.com/",
            },
        }
    }
}

Runtime trace results of the build

In addition to recording provenance, the bundle includes the results of a runtime trace of the build process.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "bin/foo-v1.1",
        "digest": {
            "sha256": "ff332109abdd"
        }
    }],
    "predicateType": "https://in-toto.io/attestation/runtime-trace/v0.1",
    "predicate": {
        "monitor": {
            "type": "https://github.com/cilium/tetragon/v0.8.4",
            "tracePolicy": {
                "policies": [{
                    "name": "connect",
                    "config": ""
                }]
            }
        },
        "monitoredProcess": {
            "hostID": "https://ci.example.com",
            "type": "custom",
            "event": "https://ci.example.com/23055"
        },
        "monitorLog": {
            "process": [],
            "network": [],
            "fileAccess": [{
                "name": "foo/Makefile",
                "digest": {
                    "sha256": "1209abcd56"
                }
            }, ...]
        }
    }
}

Build compiler configuration attributes

Finally, the bundle has a Software Supply Chain Attribute Integrity (SCAI) attestation that records some attributes of the build tool. Specifically, the attestation indicates the build step used GCC with stack protection enabled.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "bin/foo-v1.1",
        "digest": { "sha256": "ff332109abdd" }
    }],
    "predicateType": "https://in-toto.io/attestation/scai/attribute-report/v0.2",
    "predicate": {
        "attributes": [{
            "attribute": "WITH_STACK_PROTECTION",
            "conditions": { "flags": "-fstack-protector*" },
        }],
        "producer": {
            "uri": "file:///usr/bin/gcc",
            "name": "gcc9.3.0",
            "digest": {
                "sha256": "78ab6a8..."
            }
        }
    }
}

Verification

This set of metadata can be submitted to in-toto’s verification workflow using a layout conforming to the new, under-development schema. Successful verification would result in a Verification Summary Attestation.

{
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{
        "name": "foo-v1.1",
        "digest": {
            "sha256": "ff332109abdd"
        }
    }],
    "predicateType": "https://slsa.dev/verification_summary/v1",
    "predicate": {
        "verifier": {
            "id": "https://example.com/publication_verifier"
        },
        "timeVerified": "2023-04-12T23:20:50.52Z",
        "resourceUri": "https://download.example.com/foo-v1.1",
        "policy": {
            "uri": "https://example.com/foo.layout",
            "digest": {"sha256": "dabc8907fa"}
        },
        "inputAttestations": [{
            "uri": "https://example.com/foo-v1.1.intoto.jsonl",
            "digest": {"sha256": "7843adcf34"}
        }],
        "verificationResult": "PASSED",
        "verifiedLevels": ["SLSA_LEVEL_3"],
        "slsaVersion": "1.0"
    }
}

Get Involved

There are a number of exciting developments underway in in-toto such as the new layouts, several new predicate specifications, and improvements to our tooling. Come say hello at an in-toto community meeting and on #in-toto on the CNCF Slack workspace.

SLSA v1.0 is now final!

2023-04-19T00:00:00+00:00

After almost two years since SLSA’s initial preview release, we are pleased to announce our first official stable version, SLSA v1.0! The full announcement can be found at the OpenSSF press release, and a description of changes can be found at What’s new in v1.0. Thank you to all members of the SLSA community who made this possible through your feedback, suggestions, discussions, and pull requests!

But SLSA doesn’t stop here. We intend to continue working through the backlog of editorial feedback we received from RC1 and RC2 and updating the specification on a rolling basis. Further down the road, our plans include expanding the depth and breadth of the specification.

As always, we welcome contributions from all. Please see the Community page for ways to participate.

Changes since RC2

There is one breaking change since RC2: the provenance field systemParameters was renamed to internalParameters to highlight the contrast from externalParameters.

Announcing SLSA v1.0 Release Candidate 2

2023-04-04T00:00:00+00:00

We’re excited to announce SLSA v1.0 Release Candidate 2 (RC2) following the valuable feedback we received on the first release candidate. This is intended to be the final release candidate before marking v1.0 as an Approved Specification.

We ask that all community members review the full specification and raise any significant concerns as a GitHub issue by April 17, 2023. While we always appreciate clarity or editorial feedback, during this review period we are specifically looking to identify significant problems that would require a breaking change—and thus a new version—to address. (We plan to continue to addressing clarity issues via editorial changes after the v1.0 release, particularly the backlog of editorial feedback from RC1 that we have not yet addressed.)

Assuming there are no significant objections, we plan to mark this candidate as an Approved Specification on April 19.

We appreciate the continued support and engagement from the SLSA community and all early adopters who have provided valuable feedback on the previous release candidate. Thank you for your contributions to the project!

Summary of changes since RC1

There have been no major changes to requirements since RC1. Most of the changes have been editorial in nature. The following is a summary of the most significant changes:

Added Distributing provenance page
Renamed “non-forgeable” to “unforgeable”
Updated VSA for v1.0
Updated Threats & mitigations for v1.0 and relabeled the diagram (swapped labels “D” and “E”)
Resolved various inconsistencies, simplified terminology, and added more introductory material

The Breadth and Depth of SLSA

2023-04-03T00:00:00+00:00

Interested in getting involved? Now’s the chance to provide your feedback on the foundational v1 release of the SLSA framework.

“Software Supply chain security is more than just the build” is a common response when folks learn about SLSA. This is true. SLSA 1.0 is entirely focused on generating build provenance and assurance around that provenance due to the security capabilities of the build system and security properties of a particular running build. Software Supply Chain Security is the cybersecurity practice of extending left into System Delivery Lifecycle or Software Delivery Lifecycle and the SDLC is more than just the build.

If the SDLC is more than the build, why is the SLSA community only focused on that one aspect? We’re not. We’re just starting with the build. The initial focus on the build track is a strategic decision made due to its significance in the overall process. The build serves as the bridge between various inputs, such as source code and dependencies, and the final product, which is the software package or artifact intended to run in production environments or be used as a dependency to downstream consumers.

The build process plays a vital role in ensuring the quality, safety, and security of the final software. This is because it performs actions like compilation, linking and packaging the code while applying various testing, linting, optimization, and security measures. It’s the stage where all the source and dependency components come together to form the final product. It is also often one of the hardest to introspect on because it is taking arbitrary source code and transforming it into non-human readable binaries. Consequently, vulnerabilities or misconfigurations in the build system or in the build itself can compromise the security of the software. Similarly, direct attacks on the build system or build itself can introduce malicious behavior in any and all output artifacts.

Focusing on the build process and the provenance of the build artifacts enables the build systems to develop a solid foundation for Software Supply Chain Security. By establishing secure, traceable, and auditable build processes, SLSA aims to minimize the risks associated with compromised or malicious components that end up impacting or being included with the build artifacts.

While the build process is crucial, the SLSA contributors and maintainers recognize that Software Supply Chain Security is a multi-faceted problem that extends beyond this stage. As the framework evolves, it will expand its scope to include other critical aspects of the SDLC, such as secure source code management and dependency ingestion. For instance, future iterations of SLSA will introduce more stringent requirements for source code management in a source track that might include code reviews, vulnerability scanning, and secure coding practices. These measures will ensure that the source code ingested into a build is secure and free of common vulnerabilities. Similarly, SLSA may also explore ways to ensure that dependencies, such as third-party libraries, are following security standards, up-to-date, and free from known security issues in a dependency track.

Ultimately, SLSA aims to create a comprehensive, adaptable framework that addresses critical pieces of Software Supply Chain Security. By starting with the build track, SLSA establishes a robust foundation on which to build and expand the framework to address other critical aspects of the SDLC. This approach will help end users, whether they are open source project maintainers or stakeholders in a corporation, better understand and mitigate the risks associated with software supply chains, and ultimately develop more secure and reliable software.

For more information visit the SLSA website, give feedback on the SLSA v1.0 release candidate and get involved with the SLSA community.

Announcing SLSA v1.0 Release Candidate

2023-02-24T00:00:00+00:00

Today, we are excited to announce the important milestone of a release candidate (RC) SLSA Specification. This is the first major update to SLSA since its v0.1 release in June 2021, and the RC finalizes multiple revisions to the SLSA specifications and requirements. We’re grateful for the huge community engagement that went into shaping this work.

We’re requesting community feedback on the SLSA v1.0 RC1 Specification by March 24, 2023, with a view towards releasing a 1.0 Stable revision at the end of March.

What’s changed

We reworked the SLSA specification in response to ongoing feedback, filed issues, suggestions for course corrections, and other input from the SLSA community and early adopters. The most significant changes are:

the division of SLSA into multiple SLSA tracks, which are separate sets of levels that measure a particular aspect of software supply chain security
many simplifications and clarifications throughout the specification
new guidance on provenance verification
clarification of the build model and provenance schema, with an accompanying v1 provenance format

Tracks

A significant conceptual change is the division of SLSA’s level requirements into multiple tracks. Previously, each SLSA level encompassed requirements across multiple software supply chain aspects: there were source, build, provenance, and common requirements. To reach a particular level, adopters needed to meet all requirements in each of the four areas. Organizing the specification in that way made adoption cumbersome, since requirements were split across unrelated domains—improvements in one area were not recognized until improvements were made in all areas.

Now, the requirements are divided into SLSA tracks that each focus on one area of the software supply chain. We anticipate this division will make SLSA adoption easier for users. Division into tracks also benefits the SLSA community: developers contributing to SLSA can parallelize work on multiple tracks without blocking each other, and members of the community can contribute specifically to their areas of expertise.

SLSA v1.0 RC defines the SLSA Build Track to begin this separation of requirements, with other tracks to come in future versions. The new SLSA Build Track Levels 1-3 roughly correspond to Levels 1-3 of v0.1, minus the Source requirements. We anticipate future versions of the specification to continue building on requirements without changing the existing requirements defined in v1.0. The specification will likely expand to incorporate both new tracks and additional levels for existing tracks. We currently have plans for Build Level 4 and a Source Track.

The v1.0 RC also defines the principles behind SLSA track requirements, which will guide future track additions. For more information about the rationale for tracks, see the proposal.

Simplifications and clarifications

We’ve organized the Build track requirements to be more user friendly by better reflecting the division of labor across the software supply chain: producing artifacts, verifying build systems, and verifying artifacts.

Producing artifacts explains requirements for the software producer and the build system. It corresponds to v0.1’s Build and Provenance requirements. We’ve renamed some requirements to be more intuitive and have merged others, but the content is largely the same. The only substantive difference is that we’ve removed the requirements that were part of v0.1 L4 and the “build as code” requirement.

Verifying build systems provides a list of prompts for evaluating a build system’s SLSA conformance. Some content comes from v0.1’s Common requirements; the rest is new to v1.0.

Verifying artifacts provides guidance to package ecosystems and consumers for how to verify provenance and compare it to expectations. It is discussed more in the following section.

Verification

Another significant change in the v1.0 RC is documenting the need for provenance verification.

SLSA v0.1 specified guidance for how to produce provenance but not how to verify it. This left a large gap—most threats targeted by SLSA are only mitigated by verifying provenance and comparing it to expectations.

SLSA v1.0 RC addresses this gap by providing more explicit guidance on how to verify provenance. This is split between establishing trust in build systems themselves versus establishing trust in artifacts produced by those build systems. Build systems implement the requirements around isolation and provenance generation, and consumers choose whether to trust those build systems. Once that trust is established, consumers or package managers can verify artifacts by comparing the provenance to expectations for the package in question.

Ecosystems are already creating verification tooling, such as npm’s forthcoming SLSA support. Tooling for organizations that need to protect first-party software is also available, such as slsa-verifier.

Provenance format

The SLSA v1.0 RC simplifies SLSA’s build model and makes corresponding changes to the specification and provenance format.

A major source of confusion for SLSA v0.1 was how to model a build and represent it in provenance. The v0.1 spec and v0.x provenance formats were overly rigid about a build’s inputs, differentiating between “source”, “build config”, “entry point”, and so on. Many implementers found that their build systems did not clearly fit into this model, and the intent of each field was not clear. Furthermore, provenance requirements were described both abstractly in the SLSA specification and concretely in the provenance format, using different language. Implementers needed to jump back and forth and mentally map one concept to another.

SLSA v1.0 and the accompanying provenance v1 format attempt to address this confusion by simplifying the model and aligning terminology between the two. The main change is to represent all “external parameters” that are exposed to the build system’s users, instead of differentiating between various inputs. Now, you can represent arbitrary parameters, as long as it is possible to compare these parameters to expectations. Other parts of the provenance format were renamed, though conceptually most concepts translate from the old format to the new format. For a detailed list of changes, see provenance change history.

Request for feedback

Please open an issue to discuss feedback on the RC by March 24, 2023. We particularly welcome comments in response to the following questions:

Does the new specification clarify SLSA’s benefits for supply chain security?
Is the specification unambiguous on how to carry out requirements?
Is there feedback on the provenance verification guidance?
Are there suggestions to improve the division into multiple tracks?
Are the updated build model and provenance format easily understood?
Is there any remaining feedback on what may be missing?

We appreciate everyone who has contributed to the project and all the early adopters who have provided valuable feedback. Thank you to the SLSA community!

General availability of SLSA 3 Container Generator for GitHub Actions

2023-02-01T00:00:00+00:00

Today, we are announcing the general availability of the SLSA 3 Container Generator for GitHub Actions starting with v1.4.0. This free tool allows any GitHub project to produce SLSA level 3 compliant provenance statements so users can verify the origin of container images they use. While previous tools allowed users to generate provenance for file artifacts, the Container Generator is able to support container ecosystems. It does this by allowing provenance statements to be distributed alongside your images in a container registry and integrating directly with Sigstore-compatible tooling for inspection and verification.

In only a few short years since container management platforms like Docker and Kubernetes were released, container images have become one of the most popular ways to deploy software. Containers allow their users to deploy software in a more flexible way without depending on language specific packaging or deployment mechanisms. Many public repositories of container images, like Docker Hub, allow you to upload pre-packaged images that can be used out of the box or customized by users as base images.

However, it can be a huge challenge for users to verify the provenance of your images. Various reports from Aqua Security’s Team Nautilus and the Sysdig Threat Research Team show that container images which include malicious payloads are common. How can users of your image be confident of how the images you use were built? How can they be sure they haven’t been modified to include malicious payloads?

One solution is including SLSA provenance with your container image. SLSA provenance is metadata about your build that includes information that strongly links your artifacts to the build system and source code that was used. SLSA provenance can build trust in your images by helping your users verify that the images come from you and your source repositories.

The Container Generator’s reusable workflow can help you to achieve SLSA level 3 for your project by automatically generating provenance from your existing GitHub Actions workflows to generate images. This can be done by simply adding a new job step to call the generator’s reusable workflow, which generates and signs the provenance in an isolated job separate from your image’s build step for added security. Popular projects like Kyverno are already using this workflow to generate provenance for their container image releases.

Generating Provenance

Under the hood, the Container Generator’s reusable workflow uses Sigstore’s cosign to sign the provenance. This provenance is combined with the cryptographic signature into something called an attestation. This attestation is then uploaded to the container registry. Using cosign to sign the provenance allows the generated attestation to integrate well with Sigstore’s ecosystem of tools for discovery and verification.

However, unlike simply signing your container directly with cosign, using the Container Generator as a GitHub Actions reusable workflow generates the signed provenance in an isolated build job. This protects the provenance from being modified by malicious code in the build itself and enables you to meet the Non-Falsifiable requirements for SLSA level 3. You can find out more about the specifics in our Technical Design.

The following is an example of how to generate provenance using the Container Generator. You can read more details in the documentation.

Step 1: Build and push your container image

You can first build and push your image as you would normally using Docker’s build-push-action. You can find a full example in the documentation.

build:
  # ...
  steps:
    # ...
    - name: Build and push Docker image
      uses: docker/build-push-action@e551b19e49efd4e98792db7592c17c09b89db8d8 # v3.0.0
      id: build
      with:
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}
    # ...

Step 2: Call the Container Generator to generate and upload SLSA provenance

With the outputs from image generation you can call the Container Generator reusable workflow. This step calls the container workflow to generate provenance, sign it, and push the resulting attestation to the container registry. An example looks like this:

provenance:
  needs: [build]
  permissions:
    actions: read # for detecting the Github Actions environment.
    id-token: write # for creating OIDC tokens for signing.
    packages: write # for uploading attestations.
  uses: slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0
  with:
    image: ${{ needs.build.outputs.image }}
    # The image digest is used to prevent TOCTOU issues.
    # This is an output of the docker/build-push-action
    # See: https://github.com/slsa-framework/slsa-verifier#toctou-attacks
    digest: ${{ needs.build.outputs.digest }}
    registry-username: ${{ github.actor }}
  secrets:
    registry-password: ${{ secrets.GITHUB_TOKEN }}

Step 3: Inspection

You can validate that the attestation has been uploaded to the repository using cosign. Here we use the cosign tree command to display the SLSA provenance attestation associated with our image.

$ cosign tree ghcr.io/ianlewis/actions-test:v0.0.86@sha256:70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35
📦 Supply Chain Security Related artifacts for an image: ghcr.io/ianlewis/actions-test:v0.0.86@sha256:70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35
└── 💾 Attestations for an image tag: ghcr.io/ianlewis/actions-test:sha256-70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35.att
   └── 🍒 sha256:1f7571f8ca4e22229ae6fb53fdc1282cd3c251cd121e61fb035cce55bc227070

You can also inspect the uploaded provenance payload using the cosign download attestation command. The attestation is stored in a DSSE envelope, which includes the cryptographic signature and encoded provenance payload in base64. Use the following command to retrieve the payload in human readable format:

$ cosign download attestation ghcr.io/ianlewis/actions-test:v0.0.86@sha256:70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35 | jq -r '.payload' | base64 -d | jq
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "ghcr.io/ianlewis/actions-test",
      "digest": {
        "sha256": "70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35"
      }
    }
...

See the Container Generator’s documentation and the SLSA documentation for more information about the provenance’s JSON format.

Step 4: Verification

To verify your image’s provenance, use the slsa-verifier tool on the command line. This tool will verify the provenance’s signature and check the expected source repository and builder ID.

$ slsa-verifier verify-image ghcr.io/ianlewis/actions-test:v0.0.86@sha256:70205a915e3288e71b48e794e4789bf28ae4c0660c4ce340f2c48ed356b68d35 \
    --source-uri github.com/ianlewis/actions-test \
    --source-tag v0.0.86 \
    --builder-id https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v1.4.0
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v1.4.0 at commit d9be953dd17e7f20c7a234ada668f9c8c4aaafc3
PASSED: Verified SLSA provenance

You can also use Kyverno or sigstore’s policy-controller for verification in Kubernetes environments. See the documentation for more examples of verifying SLSA provenance.

No more weak links

Tackling supply chain security can be a daunting task for large organizations and open source ecosystems. The Container Generator allows any project on GitHub that generates container images to generate provenance using GitHub Actions.

Our work on SLSA tooling is just getting started. You can follow along with our project roadmap on our milestones page.

SLSA generation and verification is also only a small part of what we need to do to improve supply chain security. Connect with us via the SLSA community on Slack, discuss ideas with us in the #slsa-tooling channel, and join our SLSA Tooling working group meetings to help us prioritize future work. We welcome any contributions you can make. See you there!

Safeguarding builds on Google Cloud Build with SLSA

2022-12-05T00:00:00+00:00

Earlier this year, Google Cloud Build (GCB) announced support for Level 3 assurance of Supply-chain Levels for Software Artifacts (SLSA) for container images. Users can now automatically generate verifiable provenance documents (build records) of builds that take place in Cloud Build. Provenance can be used to provide assurance that a trusted builder (in this case, GCB) produced the resulting image through some declared process with trusted source material. To make verification effortless, we are announcing support for verifying the provenance document in the open-source slsa-verifier CLI tool, which previously only had support for GitHub Actions. With the slsa-verifier, everyone — not just the container authors — can verify the SLSA provenance document.

SLSA’s series of levels provide progressively stronger guarantees about the integrity of a software artifact. Requirements in each level are grouped by components, so projects receive separate sub-ratings for build level and provenance level. GCB users may already be familiar with SLSA build levels: Software Delivery Shield’s security insights in-console panel displays the SLSA build levels of artifacts. GCB already reaches Level 3 build requirements by performing builds in isolated and ephemeral environments. Now, GCB also meets the Level 3 provenance requirements by recording the “entry point” (or command) that was used to define the build and all user-controlled parameters. These details are in addition to the verifiable information the provenance already contained, such as the digests of the built images, the input sources, the build arguments, and the build recipe. To learn more about GCB provenance, see Safeguard builds.

As we’ll see below, this new provenance information can be used to validate that builds were generated from a specific version-controlled build pipeline, and to maintain a record of the parameters used to generate the container image for policy evaluation or reproducibility.

GCB Provenance at SLSA Level 3

At SLSA Level 3, users have assurance that the metadata content is authentic, tamper-proof, and not altered by the project maintainers. The build definition and configuration is verifiably derived from definitions stored in versioned source control systems (known as “build-as-code”). So in order to describe the full top-level build instructions, GCB now identifies the build configuration stored in git, the entrypoint, often named cloudbuild.yaml. A record of all user-controlled parameters (substitutions) to the build is also provided in the provenance’s recipe.

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.1",
  "predicate": {
    "builder": {
      "id": "https://cloudbuild.googleapis.com/GoogleHostedWorker@v0.3"
    },
    "materials": [
      {
        "digest": {
          "sha1": "01ce393d04eb6df2a7b2b3e95d4126e687afb7ae"
        },
        "uri": "https://github.com/ORG/REPO"
      }
    ],
    "metadata": {...},
    "recipe": {
      "arguments": {
        "sourceProvenance": {...},
        "steps": [...],
        "substitutions": {
          "_IMAGE_NAME": "PROJECT_ID/REPOSITORY/IMAGE_NAME:TAG"
        }
      },
      "definedInMaterial": "1",
      "entryPoint": "cloudbuild.yaml",
      "type": "https://cloudbuild.googleapis.com/CloudBuildSteps@v0.1"
    }
  },
  "subject": [
    {
      "digest": {
        "sha256": "29e5d68bdb6b95cbcb456953ae5981f9dca6a50c3621c01beb9a75869bc79bec"
      },
      "name": "https://us-LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME:TAG"
    },
  ]
}

A user can view a container’s provenance by following the viewing instructions. Next, we’ll discuss how you can use our SLSA tools to easily verify its authenticity, integrity and properties.

Verification

Validating SLSA Level 3 provenance can help to both verify that a build was produced by an expected source and build system and also identify whether any code was injected via an untrusted source location or build system. At SLSA Level 3, the provenance is service-generated (by GCB), verifiable for authenticity and integrity, and non-forgeable—meaning that a user cannot tamper with the provenance metadata.

Our SLSA verification CLI tool now supports GCB provenance verification for container images. Not only does slsa-verifier verify the signature over the provenance and the human-readable provenance summary, but it also automatically handles verification key management and allows end-users to validate that the container image was generated from the trusted Cloud Build builder and trusted source location.

To start verifying provenance, you must provide a container image name that is immutable by providing its digest (rather than, say, a mutable image tag). This avoids “Time-of-check-to-time-of-use” (TOCTTOU) attacks, described in this overview. A user can retrieve the digest of the container using the crane command:

UNVERIFIED_IMAGE="us-LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME:TAG"
IMMUTABLE_IMAGE="${UNVERIFIED_IMAGE%:*}@$(crane digest ${UNVERIFIED_IMAGE})"

Then, retrieve the provenance using the gcloud CLI utility. (Note: You must be authenticated to GCP to retrieve information about the image and configure docker authentication.)

gcloud artifacts docker images describe "${IMMUTABLE_IMAGE}" \
  --format json --show-provenance \
  > unverified-provenance.json

Verify the image using the slsa-verifier CLI tool (installation instructions) against the downloaded provenance via the --provenance-path flag. The --source-uri flag specifies the version-controlled source repository that was expected to be used to build the image. The --builder-id flag specifies the expected builder identity; in this case, we specify GCB’s builders: https://cloudbuild.googleapis.com/GoogleHostedWorker.

slsa-verifier verify-image "${IMMUTABLE_IMAGE}" \
  --provenance-path unverified-provenance.json \
  --source-uri github.com/laurentsimon/gcb-tests \
  --builder-id=https://cloudbuild.googleapis.com/GoogleHostedWorker \
  --print-provenance > verified-provenance.json # PASSED: Verified SLSA provenance

Using the --print-provenance flag will print the validated provenance JSON to allow piping into a policy engine. If verification succeeds, $IMMUTABLE_IMAGE is verified.

To run the verified container image, use the $IMMUTABLE_IMAGE (not $UNVERIFIED_IMAGE):

docker run "${IMMUTABLE_IMAGE}"

Use-Cases

In previous posts (1, 2), we described how consumers can use information found in non-forgeable SLSA Level 3 build provenance to evaluate policies that may prevent certain classes of supply chain attacks.

In particular, with the new information provided in GCB’s provenance, users may validate that a predefined set of workflows created the artifacts. For example, an organization may use a certain build configuration to generate a base image for building a final artifact. Before executing the image to create their releases, they can verify the SLSA provenance like above and then validate that the base image was generated from the authorized configuration. The GCB provenance exposes the metadata in the build recipe:

jq -r '.predicate.recipe.entryPoint' verified-provenance.json # cloudbuild.yaml

Conclusion

Reaching SLSA Level 3 with GCB is a major step in making provenance available to even more consumers. This is important to provide build transparency and security in your own or your end-users’ supply-chain. We encourage you to enable build provenance in your container image builds on GCB and to use our verification tools to start validating provenance for policy evaluation. We welcome all types of feedback and contributions to our verifier.

In the future, we’re looking to move towards more seamless SLSA provenance verification and also enable policy evaluation on images. We’re also hoping to add build provenance verification for other artifact types to slsa-verifier as support for provenance generation expands.

If you are interested in working with us to grow the ecosystem of SLSA tooling, we invite you to the SLSA Working Group and the SLSA Tooling special interest group.

Executive Order on Secure Supply Chain — in Plain English

2022-09-26T00:00:00+00:00

You may have heard about EO 14028, the “Executive Order on Improving the Nation’s Cybersecurity”, which mandates the establishment of minimum supply chain security standards for all software consumed by the US government. On September 14th the White House Office of Management and Budget (OMB) issued a memorandum setting firm and aggressive timelines for implementation of guidelines stemming from the EO, and you might reasonably be wondering what it all means. If so, this post is for you. We’re going to try to lay it out in plain English and share steps to help you get ready to meet the timelines

Background

First, a little history.

In May 2021, President Biden’s White House published Executive Order (EO) 14028 on Improving the Nation’s Cybersecurity, recognizing “persistent and increasingly sophisticated malicious cyber campaigns that threaten the public sector, the private sector, and ultimately the American people’s security and privacy”. The Executive Order directed the US Secretary of Commerce acting through the Director of NIST to “issue guidance identifying practices that enhance the security of the software supply chain”.

After a request for comments in June 2021, the US Department of Commerce issued in July 2021 a report Minimum Elements for an SBOM, as part of establishing new baseline security standards for development of software used by the US Federal Government. We published a blog post on SLSA and SBOMs a little while ago.

In February 2022, in accordance with with EO, the US National Institute of Standards and Technology (NIST) issued two documents with further standards, now collectively known as the “NIST Guidance”:

Secure Software Development Framework (SSDF), SP 800-218 [link]
Software Supply Chain Security Guidance [link]

We covered the SSDF briefly in a previous slsa.dev blog post, and noted how SLSA could form a ready on-ramp to successful SSDF conformance.

What’s new

In September 2022 the White House Office of Management and Budget (OMB) issued a memorandum requiring every Federal agency to comply with the NIST Guidance “when using third-party software on the agency’s information systems or otherwise affecting the agency’s information”.

In June 2023, compliance with the NIST Guidance will be required for all “critical software” used by Federal agencies.

In September 2023, compliance with the NIST Guidance will be required for all third-party software used by Federal agencies.

What it means

If your software is sold to, or used by, the US Federal government then your ears should be pricking up about now. Starting next year you will be expected, for each major version of each software product you supply, to provide:

A self-attestation that the product was built in conformance with NIST’s Secure Software Development Framework (SSDF). NIST has published online a handy matrix of SSDF requirements.
On request, a Software Bill of Materials (SBOM) for the product. The NTIA report Minimum Elements of an SBOM is a useful starting point for understanding what’s required.
On request, other artifacts substantiating SSDF conformance, e.g., output of vulnerability scanners, software provenance metadata, etc.
On request, evidence of participation in a Vulnerability Disclosure Program.

Even if your software is not in scope today, you might nonetheless find your customers asking for the same things before long, as the new US Federal Government standards raise the bar across the industry.

What’s in scope

Notably, the OMB memo extends to software used by agencies, not merely software procured by agencies. That brings into scope products which haven’t previously had to work with government compliance standards, such as free or liberally licensed ones.

The OMB dictates that agencies will themselves by December 2022 generate a software inventory listing which products will need to meet the new requirements next year; and of those which are considered “critical” and will need to comply by June 2023, ahead of the September 2023 deadline for everything else. The agencies will use NIST’s definition to determine criticality.

What now?

First, don’t panic!

Instead, you can get started right away with some immediate concrete steps:

Review the OMB memorandum itself. This blog post provides a plain English summary but omits some details such as how exceptions are handled, how remediation plans work, how self-attestations are made in practice, and so on. It’s worthwhile reading the original text to get the full skinny.
Familiarize yourself with the practices and tasks of the Secure Software Development Framework (SSDF), and begin to develop a sense of how your own software development processes map onto NIST’s set. Take note of any glaring gaps you see.
Read up on SBOMs. A 2019-era NTIA whitepaper “Roles and Benefits for SBOM Across the Supply Chain” includes a comprehensive catalog of potential benefits offered by SBOMs, and the companion document Minimum Elements of an SBOM lays out a pragmatic starting point.
Review NIST’s definition of “critical software” to understand if your products fall into this category. If so, your conformance with the new standards is expected by June next year, rather than September.
See how SLSA can help! Read the previous posts SBOM + SLSA: Accelerating SBOM success with the help of SLSA and SLSA for Success: Using SLSA to help achieve NIST’s SSDF.