diff --git a/docs/security/salsa/salsa.md b/docs/security/salsa/salsa.md index bdef4fd36..bcd87bb74 100644 --- a/docs/security/salsa/salsa.md +++ b/docs/security/salsa/salsa.md @@ -4,28 +4,27 @@ description: Github action that helps to secure supply chain for software artifa # Salsa -!!! info "Status: Beta" - This feature is only in a beta. - - **Experimental**: users report that this component is working, but it needs a broader audience to be battle-tested properly. - - Report any issues to the #nais channel on Slack. - ## What is SLSA [SLSA](https://slsa.dev/) is short for _Supply chain Levels for Software Artifacts_ pronounced `salsa`. -It’s a security framework, a check-list of standards and controls to prevent tampering, improve integrity, and secure -packages and infrastructure in our projects. +It is a security framework, essentially a checklist comprising standards and controls aimed at preventing tampering, +enhancing integrity, and securing both packages and infrastructure within our projects. ## SLSA in NAIS -If you use the [nais/docker-build-push](https://github.com/nais/docker-build-push) action to build and push your container image, you will automatically get a signed -attestation/SBOM (Software Bill of Materials) of your container image and its dependencies. The SBOM will be uploaded to your container -registry alongside your image. The attestation is generated by the [Trivy](https://github.com/aquasecurity/trivy-action) github action and signed using [cosign](https://github.com/sigstore/cosign). +If you utilize the [nais/docker-build-push](https://github.com/nais/docker-build-push) action for building and pushing +your container image, you will automatically +receive a signed attestation/SBOM (Software Bill of Materials) for your container image and its dependencies. This SBOM +will be uploaded to your container registry along with your image. The attestation is generated by +the [Trivy](https://github.com/aquasecurity/trivy-action) GitHub +action and signed using [cosign](https://github.com/sigstore/cosign). -When you deploy your image to NAIS the attestation will be verified by the NAIS platform ([picante](https://github.com/nais/picante)) and uploaded to a SBOM analysis plattform -called [Dependency-Track](https://dependencytrack.org/). In Dependency-Track you can see the attestation and the vulnerabilities in your image and its dependencies. +Upon deploying your image to NAIS, the attestation will undergo verification by the NAIS +platform ([picante](https://github.com/nais/picante)) and will be +uploaded to an SBOM analysis platform known as [Dependency-Track](https://dependencytrack.org/). In Dependency-Track, +you can examine the attestation as +well as the vulnerabilities present in your image and its dependencies. ### Usage @@ -39,8 +38,8 @@ Simply add [nais/docker-build-push](https://github.com/nais/docker-build-push) t salsa: true # optional, defaults to true project_id: ${{ vars.NAIS_MANAGEMENT_PROJECT_ID }} # required, but is defined as an organization variable identity_provider: ${{ secrets.NAIS_WORKLOAD_IDENTITY_PROVIDER }} # required, but is defined as an organization secret - # ... other options removed for readability - + # ... other options removed for readability + ``` !!! Opt-out @@ -54,46 +53,48 @@ Simply add [nais/docker-build-push](https://github.com/nais/docker-build-push) t See [nais/docker-build-push](https://github.com/nais/docker-build-push) for more options. - ### View and analyze dependencies -[Dependency-Track](https://dependencytrack.org/) is deployed to each NAIS cluster (GCP only) and contains attestations and vulnerabilities for all images deployed to the cluster (which have not opted out from salsa). - -You can access the Dependency-Track UI at the following URL: - -* https://salsa.[clustername].[tenantname].cloud.nais.io +[Dependency-Track](https://dependencytrack.org/) has a single instance that controls all clusters, and it contains both +attestations and vulnerabilities for all signed attestations deployed, except those that have chosen to opt out +from salsa. You can access the Dependency-Track user interface through the following URL: -**Example**: [https://salsa.prod-gcp.nav.cloud.nais.io](https://salsa.prod-gcp.nav.cloud.nais.io) +https://salsa.[tenantname].cloud.nais.io +For instance, you can visit [nav-salsa](https://salsa.nav.cloud.nais.io) as an example. -You must login using the **OpenID** button which will redirect you to your organizations identity provider. +To log in, use the OpenID button, which will redirect you to your organization's identity provider. -Each container in a deployment will have its own project in Dependency-Track. The project name consist of the team name, application name and the container image name. -You can search in projects with the following tags: +In Dependency-Track, each container in a deployment will have its own project. The project's name is a combination of +the cluster, team name, application name, and the container image name. You can search within projects using the +following tags: - * team - * application - * image +* Team +* Application +* Image -Here is a screenshot of a project using the dependency graph in Dependency-Track: +Below is a screenshot of a project utilizing the dependency graph within Dependency-Track: ![Dependency Graph](../../assets/salsa-graph.png) -[Dependency-Track](https://dependencytrack.org/) has a ton of features so check out the [documentation](https://docs.dependencytrack.org/) for more information. +[Dependency-Track](https://dependencytrack.org/) has a ton of features so check out +the [documentation](https://docs.dependencytrack.org/) for more information. ### Language support -SBOM generation for different [languages/build tools are dictated by Trivy](https://aquasecurity.github.io/trivy/v0.40/docs/scanner/vulnerability/language/) +SBOM generation for +different [languages/build tools are dictated by Trivy](https://aquasecurity.github.io/trivy/v0.40/docs/scanner/vulnerability/language/) #### Known limitations and alternatives -Due to Trivy, you will get a flat graph of dependencies. This is because Trivy does not support Gradle's or Maven dependency resolution. +Due to Trivy, you will get a flat graph of dependencies. This is because Trivy does not support Gradle's or Maven +dependency resolution. Trivy parses the .jar files directly and does not have access to the dependency resolution information. Here is 2 alternatives: -Alternative 1, GitHub workflow for Gradle users. +Alternative 1, GitHub workflow for Gradle users. No need to add any plugins to your build file. You will get a deep graph of nested transitive dependencies. -The generated sbom will be located in the ` dependency-graph-reports` directory. +The generated sbom will be located in the ` dependency-graph-reports` directory. The action requires `contents: write` permission. Gradle and Maven plugins for a deep graph of nested transitive dependencies.