nais · ybelMekk · Oct 14, 2024 · Oct 14, 2024
diff --git a/docs/assets/salsa-login.png b/docs/assets/salsa-login.png
diff --git a/docs/assets/salsa-team.png b/docs/assets/salsa-team.png
diff --git a/docs/vulnerabilities/.pages b/docs/vulnerabilities/.pages
@@ -0,0 +1,5 @@
+nav:
+- README.md
+- 💡 Explanations: explanations
+- 📚 Reference: reference
+- ...
diff --git a/docs/vulnerabilities/README.md b/docs/vulnerabilities/README.md
@@ -0,0 +1,42 @@
+---
+tags: [salsa, slsa, supply-chain, vulnerabilities, explanation]
+description: NAIS provides a set of services to help you secure your software supply chain and manage vulnerabilities in your workloads.
+---
+
+# Vulnerability insights and management
+
+NAIS provides a set of tools and services to help you secure your software supply chain and manage vulnerabilities in your workloads:
+
+<div class="grid cards" markdown>
+
+- [**Attestation**][Attestation] (nais/docker-build-push)
+
+    GitHub action that helps to secure a supply chain for software artifacts.
+
+- [**Vulnerability Insights**][Insights]
+
+    Tools to manage vulnerabilities in your workloads.
+
+</div>
+
+The NAIS [SLSA](explanations/README.md#slsa) is built on a security framework designed to prevent tampering, enhance integrity, and secure both packages and infrastructure within software projects.
+Se the different tools below and follow the links to the respective tool for more details.
+
+## Getting started with vulnerability insights
+
+The setup of vulnerability insights for an workload is straightforward and only requires you to add the [nais/docker-build-push][Attestation] action to your GitHub workflow.
+Once added, the action will automatically generate a signed attestation, including a [SBOM][SBOM]
+(Software Bill of Materials) for your container image and its dependencies.
+This is bundled as an [attestation](explanations/README.md#attestation) and pushed to your container registry along with your image and plays a key role in providing proof that the software supply chain follows secure processes.
+
+## Acknowledge vulnerabilities
+
+NAIS continuously monitors deployed container images in the cluster. 
+When a new image is detected, NAIS automatically uploads its [SBOM][SBOM] to [DependencyTrack][Insights] for vulnerability analysis.
+
+The results of the DependencyTrack analysis, including vulnerability insights, can then be viewed in the NAIS Console.
+The [NAIS Console][Insights] provides a platform for viewing and managing vulnerabilities at the team level.
+
+[Attestation]: attestation/README.md
+[Insights]: insights/README.md
+[SBOM]: explanations/README.md#software-bill-of-materials
diff --git a/docs/vulnerabilities/attestation/.pages b/docs/vulnerabilities/attestation/.pages
@@ -0,0 +1,5 @@
+title: Attestation
+nav:
+- README.md
+- 🎯 How-To: how-to
+- ...
diff --git a/docs/vulnerabilities/attestation/README.md b/docs/vulnerabilities/attestation/README.md
@@ -0,0 +1,12 @@
+---
+tags: [attestation, docker-build-push, explanation]
+---
+
+# Attestation with Docker Build Push
+
+NAIS provides a GitHub Action for building and pushing Docker images to the [Google Container Registry](https://cloud.google.com/artifact-registry/docs).
+The action automatically generates a signed attestation, including a [SBOM](../explanations/README.md#software-bill-of-materials) (Software Bill of Materials) for your container image and its dependencies.
+This SBOM is uploaded to your container registry along with your image.  
+The attestation is generated by the [Trivy](https://github.com/aquasecurity/trivy-action) and signed using [cosign](https://github.com/sigstore/cosign).
+
+:dart: [**Learn how to sign attestations**](how-to/attestation.md)
diff --git a/docs/vulnerabilities/attestation/how-to/attestation.md b/docs/vulnerabilities/attestation/how-to/attestation.md
@@ -0,0 +1,130 @@
+---
+tags: [attestation, docker-build-push, how-to]
+---
+
+# Docker Build Push
+
+Simply add [nais/docker-build-push](https://github.com/nais/docker-build-push) to your workflow.
+
+```yaml
+ - uses: nais/docker-build-push@v0
+   id: docker-push
+   with:
+     team: myteam # required
+     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
+```
+
+??? note Opt-out
+    Opt-out from salsa
+
+    If you want to opt-out from salsa you can set the salsa input to false
+
+    ```yaml
+    salsa: false
+    ```
+
+## Attest sign
+
+The `nais/docker-build-push` action default push to Google Container Registry (GAR).
+If you want to push to another registry, you can use the [nais/attest-sign](https://github.com/nais/attest-sign) to generate sbom and sign the attestation.
+
+```yaml
+ - uses: nais/attest-sign@v1
+   id: attest-sign
+   with:
+     image_ref: my-image@sha256:12345 # required
+     sbom: my-image.json # optional
+     # ... other options removed for readability
+```
+
+## Known limitations and alternatives
+
+Due to [Trivy](https://github.com/aquasecurity/trivy-action), you'll receive a simplified dependency graph, as Trivy 
+doesn't support Gradle or Maven's dependency resolution. However, the benefit is that it identifies both the image dependencies 
+and their associated vulnerabilities.
+
+Trivy directly parses the .jar files without access to full dependency resolution details.
+
+Gradle and Maven plugins provide a deeper graph of nested transitive dependencies, 
+but when using these plugins directly, you won't get vulnerabilities specific to the Docker container. 
+However, if you're using Distroless or Chainguard images, updates are managed and kept to a minimum.
+
+??? note Gradle Plugin
+
+    Add the following plugin to your `build.gradle*` file.
+
+    ```groovy
+        id("org.cyclonedx.bom") version "1.x.x"
+    ```
+
+    In your workflow you can generate a SBOM with the following gradle task command:
+
+    ```yaml
+        - name: Generate and output SBOM
+          run: ./gradlew cyclonedxBom
+    ```
+
+    The SBOM will be default located at `build/reports/bom.json`. Pass the SBOM to the `nais/docker-build-push` action with the following input:
+
+    ```yaml
+        uses: nais/docker-build-push@v0
+        with:
+          byosbom: build/reports/bom.json
+    ```
+
+    For `nais/attest-sign` action:
+
+        ```yaml
+            uses: nais/attest-sign@v1
+            with:
+                sbom: build/reports/bom.json
+        ```
+
+    For more info about settings check out the [CycloneDx Gradle Plugin](https://github.com/CycloneDX/cyclonedx-gradle-plugin)
+
+??? note Maven Plugin
+    Add the following to your `pom.xml` file.
+
+    ```xml
+        <plugins>
+            <plugin>
+                <groupId>org.cyclonedx</groupId>
+                <artifactId>cyclonedx-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>makeAggregateBom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    ```
+
+    In your workflow you can generate a SBOM with the following maven command:
+
+    ```yaml
+        - name: Generate and output SBOM
+          run: ./mvnw package
+    ```
+
+    The SBOM will be default located at `target/bom.json`. Pass the SBOM to the `nais/docker-build-push` action with the following input:
+
+    ```yaml
+        uses: nais/docker-build-push@v0
+        with:
+          byosbom: target/bom.json
+    ```
+
+    For `nais/attest-sign` action:
+
+        ```yaml
+            uses: nais/attest-sign@v1
+            with:
+                sbom: target/bom.json
+        ```
+    For more info about settings check out the [CycloneDx Maven Plugin](https://github.com/CycloneDX/cyclonedx-maven-plugin)
diff --git a/docs/vulnerabilities/explanations/README.md b/docs/vulnerabilities/explanations/README.md
@@ -0,0 +1,58 @@
+---
+tags: [ slsa, salsa, vulnerabilities, explanation ]
+---
+
+# Concepts surrounding vulnerability insights
+
+This page offers an overview of the concepts related to vulnerability insights and explains how NAIS helps secure your software supply chain.
+Much of the documentation revolves around these concepts, so having a basic understanding of them is helpful for navigating it effectively.
+
+
+## SLSA
+
+_Why is there so much focus on `Secure Supply Chain Levels for Software Artifacts`?_
+
+[Supply Chain Levels for Software Artifacts](https://slsa.dev/) is a framework that sets security standards for software development
+to protect against supply chain attacks. It defines different levels of security practices, from basic checks (like
+verifying code sources) to advanced measures (like cryptographically signing builds), helping ensure that software is
+built and delivered securely. The higher the level, the more secure the process, reducing risks like code tampering or
+dependency vulnerabilities
+
+### Supply Chain Attacks
+
+A supply chain attack is a type of cyberattack where hackers target vulnerabilities in an organization's supply chain rather than attacking the organization directly. In the context of software, this typically involves compromising third-party software, libraries, or services that a company relies on to build, deploy, or operate its own software.
+
+Attackers may inject malicious code into a software component, alter a tool in the development process, or compromise a service that handles software updates. Once the tampered component is distributed and integrated into other systems, it can lead to widespread damage, allowing attackers to breach multiple organizations at once.
+
+Examples of software supply chain attacks include:
+
+* Code tampering 🖥️: Inserting malware into open-source libraries or dependencies.
+* Compromising build tools 🔧: Targeting CI/CD pipelines or build systems to alter software during development.
+* Exploiting updates 🚨: Hijacking update mechanisms to distribute malicious updates.
+
+These attacks are especially dangerous because they can often go unnoticed 🔍, as organizations typically trust third-party components and automatically integrate them without thorough verification.
+
+### Attestation
+
+In the context of Supply Chain Levels for Software Artifacts,
+an attestation is a signed and verifiable statement that provides details about the software's build process and its integrity.
+It acts as a proof or certification that the software was built in a secure environment following specific security practices.
+Attestations typically include information such as:
+
+* 🧑‍💻 The source code used for the build
+* 🛠️ The build process, tools, and environment
+* 🔐 Verification that the software hasn’t been tampered with
+* 📦 Details about dependencies and their origins
+
+In SLSA, attestations are crucial because they allow organizations to trust the software they are using or distributing.
+These attestations can be checked to ensure that the software supply chain follows the necessary security standards and to reduce
+the risk of supply chain attacks.
+
+## Software Bill of Materials
+
+[A Software Bill of Materials](https://en.wikipedia.org/wiki/Software_supply_chain) (SBOM) is a detailed list of all the components, 
+libraries, and dependencies that make up a software application. It includes information about the versions, origins, and licenses of 
+these components. An SBOM is essential for understanding what's inside your software, helping to identify vulnerabilities, track updates, 
+and ensure compliance with licensing and security standards. It's like an ingredient list for software, providing transparency and control 
+over what is used in the development process.
+
diff --git a/docs/vulnerabilities/insights/.pages b/docs/vulnerabilities/insights/.pages
@@ -0,0 +1,5 @@
+title: Insights
+nav:
+- README.md
+- 🎯 How-To: how-to
+- ...
diff --git a/docs/vulnerabilities/insights/README.md b/docs/vulnerabilities/insights/README.md
@@ -0,0 +1,25 @@
+---
+tags: [slsa, salsa, console, vulnerabilities, how-to] 
+---
+
+# Vulnerability insights
+
+NAIS provides a set of tools and services to help you secure your software supply chain and manage vulnerabilities in your applications.
+
+## DependencyTrack
+
+DependencyTrack is an Component Analysis platform that allows you to identify and reduce risk in the software supply chain.
+[Dependency-Track](https://dependencytrack.org/) operates as a single instance that manages all clusters and stores both
+attestations and vulnerabilities for all signed attestations deployed.
+
+:dart: [**Explore DependencyTrack**](how-to/dependencytrack.md)
+
+## NAIS Console
+
+The NAIS Console is a web-based interface that provides developers and teams with tools to manage, monitor, and
+interact with their applications and resources deployed on the NAIS (NAV Application Infrastructure Services) platform. 
+It offers a centralized way to view and handle various aspects of workloads, such as:
+
+Vulnerability insights 🛡️: Access detailed reports about security vulnerabilities in deployed container images.
+
+:dart: [**Explore the Console**](how-to/console.md)
diff --git a/docs/vulnerabilities/insights/how-to/console.md b/docs/vulnerabilities/insights/how-to/console.md
@@ -0,0 +1,18 @@
+---
+tags: [ console, vulnerabilities, how-to ]
+---
+
+# Vulnerability insights in the NAIS Console 
+
+Teams can visit the Console to view their workload vulnerabilities, for example:
+
+https://console.[tenant].cloud.nais.io/team/[team]/vulnerabilities
+
+In the Console vulnerability overview, you can sort vulnerabilities by severity and cluster to get a better overview of the vulnerabilities in your workloads.
+
+You will get the status of the teams' total, like coverage, total critical or risk score ranking. 
+
+![NAIS Console](../../../assets/salsa-team.png)
+
+
+
diff --git a/docs/vulnerabilities/insights/how-to/dependencytrack.md b/docs/vulnerabilities/insights/how-to/dependencytrack.md
@@ -0,0 +1,37 @@
+---
+tags: [ dependencytrack, how-to ]
+---
+
+# Explore DependencyTrack
+
+You can access the DependencyTrack user interface through the following URL:
+
+https://salsa.[tenant].cloud.nais.io
+
+To sign in, click the OpenID button, which will redirect you to your organization's identity provider.
+
+![Dependency Login](../../../assets/salsa-login.png)
+
+In DependencyTrack, each image in a deployment or job is linked to its own project.
+A project can be associated with multiple workloads, teams, and clusters.
+The project name is based on the image name. For Google Artifact Registry (GAR),
+the project name follows this format: `europe-north1-docker.pkg.dev/nais-management-233d/[team]/[application]`,
+with the image version set as the project version.
+
+You can list projects your interested in using the following tag prefixes:
+
+* `team:`
+* `workload:`
+* `image:`
+
+Below is a screenshot of a project using the dependency graph within DependencyTrack:
+
+![Dependency Graph](../../../assets/salsa-graph.png)
+
+[DependencyTrack](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 dictated by Trivy](https://aquasecurity.github.io/trivy/v0.56/docs/scanner/vulnerability/#supported-languages).
diff --git a/docs/vulnerabilities/reference/README.md b/docs/vulnerabilities/reference/README.md
@@ -0,0 +1,9 @@
+---
+tags: [vulnerabilities, reference]
+---
+
+# Vulnerability reference
+
+## NAIS slsa-verde operator
+
+The operator watches workloads in k8s, verifies attestations and informs DependencyTrack with its current set of image state.   <https://github.com/nais/slsa-verde>