Repository files navigation

This action is deprecated in favour of using Trivy and CycloneDX. Seehttps://doc.nais.io/security/salsa/ for more information.

nais SLSA Provenance Action

This is a GitHub Action for generating signedprovenance about a build and itsrelated artifacts. Provenance is an attestation (a "software bill of materials") about a software artifact or collectionof artifacts, documenting how an artifact was produced - all in a common format.

Supply chain Levels for Software Artifacts, orSLSA (pronounced:salsa), is a security framework (standards, guidelines etc.) to prevent tampering, improve integrity, and secure packages and infrastructure in yourprojects, businesses or enterprises.

The action implements thelevel 3 requirements oftheSLSA Framework (as long as it is run in an ephemeral environment)producing a signed softwareattestation ofyour build and dependencies. The attestation is signed and uploaded to your container registryusingCosignand can be verified by the salsa cli (also provided in this repo) or using thecosign verify-attestation command.

Signing attestation with KMS (Key Management Service), verification requires access to the corresponding public keys.

• The keys for thenavikt andnaisorganizations can be found at our website (for now), if you use this action at otherorganizations you need to host your keys somewhere appropriate.

Signing attestation with Cosign Keyless, verification do not require access to the corresponding public keys.

cosign verify-attestation --type=slsaprovenance image:tag

Disclaimer:This is not an official GitHub Action maintained by the SLSA team. It is created by thenais.io team for the purpose of securing supply chains inNAV. However, we encourage other organizations/users to use it and even contribute as it is built with open source in mind.

golang
Cosign
GitHub Actions

Statement type:in-toto v0.1
Signing envelope:DSSE
Predicate type:Provenance v0.2

This actions creates attestations withmaterials based on both runtime andtransitive dependencies, using a supported build tool.

gradle
maven

yarn
npm

golang
php (withknownlimitation: there is no digest overdependencies)

• How to use
  • Requirements
  • Key Management
    • Setup
    • Other KMS providers
    • Workflow
  • Keyless
    • Workload identity
    • Workflow
• Customizing
  • Inputs
    • Access Private Repositories
    • GitHub context
    • Runner context
  • Outputs
• Release
  • Checksums
  • Verify signature

Thenais salsa action supportsKMS providers orCosign Keyless for signing and/or upload of the attestation to theregistry.

An authentication step in the Workflow must be set up explicit before thenais salsa action. ConfigureaKMS provider or a Workload Identity Federation before thenais salsa is run.

In the workflow examples we usegoogle-github-actions/authto authenticate with Google KMS or with a Workload identity.

actions/checkout is required prior to using this action asnais salsamust have access to yourbuild manifest to digest over dependencies.

Thenais salsa action useCosign with supportofKMS to sign and verify the attestation. Cosignsupports all the standardkey management systems.

KMS with Cosign requires some setup at the provider.

KMS is enabled in your Google project:

• create a keyring
• create key:Elliptic Curve P-256 key SHA256 Digest

Service account in project has roles:

• Cloud KMS CryptoKey signer/verifier
• Cloud KMS viewer Role

It is possible to use other KMS providers (this will probably require another GitHub action to be configured).Read theCosign KMS documentation for more information aboutproviders, their specific setup and key URI formats.

name:cion:push:branches:      -'main'env:IMAGE:ttl.sh/nais/salsa-test:1hKEY:gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSIONjobs:provenance:runs-on:ubuntu-20.04steps:      -name:Checkout Codeuses:actions/checkout@v3      -name:Build and pushuses:docker/build-push-action@v3with:push:truetags:${{ env.IMAGE }}      -name:Authenticate to Google Clouduses:google-github-actions/auth@v0.8.1with:credentials_json:${{ secrets.GCP_CREDENTIALS }}      -name:Provenance, upload and sign attestationuses:nais/salsa@v0.xwith:key:${{ env.KEY }}

with.credentials_json is theGitHub serviceaccount json key.

with.key is the keyURI format for Google KMS.Format:gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION

nais salsa supportsCosign Keyless Signatures signing andverification of attestations.

Note: Cosign Keyless this is an experimental feature and is not recommended for production use.

Pre-requisites before using Keyless Signatures:

Create a Workload Identity Federation andfollowsteps to configureworkload identity federation. This can be done with commands using the Googlegcloud cli or in thebrowserGoogle Console.

name:slsa keyless signatureson:push:branches:      -'main'env:IMAGE:ttl.sh/nais/salsa-keyless-test:1hjobs:keyless:permissions:contents:'read'id-token:'write'runs-on:ubuntu-20.04steps:      -name:Checkout Codeuses:actions/checkout@v3      -name:Build and pushuses:docker/build-push-action@v3with:context:integration-testpush:truetags:${{ env.IMAGE }}      -name:Authenticate to Google Clouduses:google-github-actions/auth@v0.8.1id:googlewith:workload_identity_provider:${{ secrets.SLSA_WORKLOAD_IDENTITY_PROVIDER }}service_account:name@project-id.iam.gserviceaccount.comtoken_format:"id_token"id_token_audience:sigstoreid_token_include_email:true      -name:Generate provenance, sign and upload imageuses:nais/salsa@v0.xwith:identity_token:${{ steps.google.outputs.id_token }}env:COSIGN_EXPERIMENTAL:"true"

The describedwith fields is required to enable Federation with workload identity andCosign keyless signatures.

with.workload_identity_provider is the workload identity provider. The value is retrieved from the Federationinstance created. Format:projects/$PROJECT/locations/$LOCATION/workloadIdentityPools/$POOL/providers/$PROVIDER

with.service_account is the service account to use for the workload identity. The value is retrieved from theservice account created. Format:name@project-id.iam.gserviceaccount.com

with.token_format is the token format to use. Cosign expects "id_token".

with.id_token_audience is the audience to use for theid_token. Cosign expectssigstore.sigstore audiencemust be added to the workload identity provider as an allowed audience.

with.id_token_include_email Cosign expects the email to be included in the token.

The describedwith fields is required fornais salsa.

with.identity_token is the outputidentity_token from the Google Auth Action.Format:steps.steps-id.outputs.id_token

with.env.COSIGN_EXPERIMENTAL is required to be set totrue for Cosign to enable keyless signatures.

Cosign defaults to store signatures in the same repo as the image it is signing.It is possible to specify a different repo for signatures, you can set theCOSIGN_REPOSITORY environment variable tostore the cosign signatures and attestations, see more specification inthecosign docs

-name:Generate provenance, sign and upload imageuses:nais/salsa@v0.xwith:key:${{ secrets.SALSA_KMS_KEY }}env:COSIGN_REPOSITORY:"registry.io/signatures"

Actor must be sure thatwith.github_token has access to the signature repository.

Salsa builds your application to retrieve running dependencies, when the build configuration contains private packages,the build needs a token with the properaccess.Mavenandgradlebuild tool can authenticate with aPAT. Use thewith.github_token field to authenticate with the registry.

with.token_key_pattern can be used to specify a key pattern, other than defaultGITHUB_TOKEN.

with.mvn_opts - (optional) additional maven options in a comma-delimited string.

When specified, the options are separated by, and appended to the maven command line.Options with arguments like--settings must be seperated with a= sign and not space, forexample:--settings=.mvn/settings.xml. Double--flag options can not be mixed with single-flag.

Useful when your project depends on a custom maven settings file or use dependencies from a private repository.If project depends on dependencies from a private repository, actor need to set GitHubprivate token with proper access right.

 -name:Generate provenance, sign and upload imageuses:nais/salsa@v0.xwith:mvn_opts:"-s .mvn/settings.xml"github_token:${{ secrets.PAT }}

with.github_context - (required) default totrue to include the github context in the provenance.

The github context contains information about the workflow run and the event that triggered the run. By default, thisaction uses theGitHub context.

with.runner_context - (required) default totrue to include the runner context in the provenance.

The runner context contains information about the runner that is executing the current job. By default, this action usestheRunner context.

The Following inputs can be used asstep.with keys

• provenance_file_pathSLSA provenance
• raw_file_pathSigned Cosign dsse attestation

We generate achecksums.txt file and upload it with the release, so users can validate if the downloaded files arecorrect. All files are by default digested with algorithmsha256.

The releaseartifacts are signed with Cosignand can be verified by using thepublic signing key.

cosign verify-blob --key cosign.pub --signature salsa.tar.gz.sig salsa.tar.gz

Verified OK