Document HashiCorp Vault Integration

docs/software-supply-chain-assurance/sbom-policies/enforce-sbom-policies.md

@@ -6,6 +6,9 @@ redirect_from:
   - /docs/software-supply-chain-assurance/ssca-policies/enforce-ssca-policies
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Enforce SBOM policies in the CI and CD stages of your Harness pipelines to ensure that your artifacts only contain approved components.
 
 ## Requirements
@@ -33,13 +36,28 @@ SBOM Orchestration and Enforcement steps in deploy stage can only be used in the
 The **SBOM Policy Enforcement** step has the following settings:
 
 * **Name:** Enter a name for the step.
-* **Source:** Set the source, which can be DockerHub, ECR, GCR, ACR or Repository. Depending on your selection, a unique set of fields will appear, each specific to the source you've chosen. Address these fields as required, this is similar to configuring the source in **SBOM Orchestration step**. For more details of what each field entails, please refer to the [documentation on SBOM Orchestration](/docs/software-supply-chain-assurance/sbom/generate-sbom#add-the-sbom-orchestration-step). If you are using DockerHub, you can follow along. 
-* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the Docker-compliant container registry where your artifact is stored. Given that this step is to verify the attestation, read-level permissions should be adequate.
-* **Image:** Enter the name of your image with tag, such as `my-docker-org/repo-name:tag`.
-* **Public Key:** Select the [Harness file secret](/docs/platform/secrets/add-file-secrets) containing the public key to use to verify the authenticity of the attestation.
-* **Policy Sets:** Select the policy set that you want to use for enforcement. You can select multiple policy sets from Account, Org or Project.
 
-<DocImage path={require('./static/sbom-policy-enforcement-step.png')} width="50%" height="50%" />
+* **Source**: Select the Source by choosing either a supported container registry from the list or Repository.
+
+import ArtifactSource from '/docs/software-supply-chain-assurance/shared/artifact-source.md';
+
+<ArtifactSource />
+
+### Verify the SBOM Attestation
+To verify the SBOM attestation, in addition to the above configuration, you need to enable the Verify SBOM Attestation checkbox in the SBOM Policy Enforcement step. Enabling this is optional and not required for SBOM policy enforcement.
+
+The attestation verification process requires the corresponding **public key** of the private key used for SBOM attestation. You can perform the verification by providing the public key through the **Cosign** option or **Cosign with Secret Manager**.
+
+import CosignVerificationOptions from '/docs/software-supply-chain-assurance/shared/cosign-verification-options.md';
+
+<CosignVerificationOptions />
+
+
+### Policy Configuration
+You can configure the step to enforce policies on the SBOM by selecting the appropriate policy set.
+
+- **Policy Sets:** Choose the policy sets you want to use for enforcement. You can select multiple policy sets from the **Account**, **Org**, or **Project** levels. For more details, refer to [Creating SBOM Policies](/docs/software-supply-chain-assurance/sbom-policies/create-sbom-policies) and [Writing SBOM Policy Definitions](/docs/software-supply-chain-assurance/sbom-policies/define-sbom-policies).
+
 
 ## Run the pipeline
 

docs/software-supply-chain-assurance/shared/artifact-source.md

@@ -0,0 +1,77 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="dockerhub" label="DockerHub" default>
+
+* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the DockerHub container registry where the artifact is stored.
+
+* **Image:** Enter the name of your image with tag, such as `repo-name:tag`.
+
+</TabItem>
+
+<TabItem value="ecr" label="ECR" default>
+
+* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the Elastic container registry where the artifact is stored.
+
+* **Image:** Enter the name of your image with tag for the image for which you're generating an SBOM, such as `my-docker-repo/my-artifact:latest`.
+
+* **Region:** The geographical location of your ECR repository.
+
+* **Account ID:** The unique identifier associated with your AWS account.
+
+</TabItem>
+
+<TabItem value="gcr" label="GCR" default>
+
+* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the Google container registry where the artifact is stored.
+
+* **Image:** Enter the name of your image with tag for which you're generating the SBOM, example `docker-image:tag`.
+
+* **Host:** Enter your GCR Host name. The Host name is regional-based. For instance, a common Host name is `gcr.io`, which serves as a multi-regional hostname for the United States. 
+
+* **Project ID:** Enter the unique identifier of your Google Cloud Project. The Project-ID is a distinctive string that identifies your project across Google Cloud services. example: `my-gcp-project`
+
+</TabItem>
+
+<TabItem value="gar" label="GAR" default>
+
+* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the Google artifact registry where the artifact is stored.
+
+* **Image:** Enter the name of your image with tag for which you're generating the SBOM, example `repository-name/image:tag`.
+
+* **Host:** Enter your GAR Host name. The Host name is regional-based. For example, `us-east1-docker.pkg.dev`.
+
+* **Project ID:** Enter the unique identifier of your Google Cloud Project. The Project-ID is a distinctive string that identifies your project across Google Cloud services. example: `my-gcp-project`
+
+</TabItem>
+
+<TabItem value="acr" label="ACR" default>
+
+* **Container Registry:** Select the [Docker Registry connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) that is configured for the Azure container registry where the artifact is stored.
+
+* **Image:** Enter your image details in the format `<registry-login-server>/<repository>:<tag>`. The `<registry-login-server>` is a fully qualified name of your Azure Container Registry. It typically follows the format `<registry-name>.azurecr.io`, where   `<registry-name>` is the name you have given to your container registry instance in Azure. Example input: `automate.azurecr.io/acr:test`
+
+* **Subscription Id:** Enter the unique identifier that is associated with your Azure subscription. 
+
+</TabItem>
+
+  <TabItem value="Repository" label="Repository">
+
+    :::info
+
+    The **Repository** option requires that your repository is cloned into the stage workspace before the SBOM Orchestration step runs. There are several ways you can do this:
+    * Clone the codebase by default, such as a [Build stage's default codebase](/docs/continuous-integration/use-ci/codebase-configuration/create-and-configure-a-codebase).
+    * Add a [Git Clone step](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/containerized-steps/git-clone-step/) or [Run step](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/containerized-steps/run-step/) to the Deploy stage.
+    * Add a [Git Clone step or Run step to a Build stage](/docs/continuous-integration/use-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline).
+
+    :::
+* **Repository URL:** The Repository URL you've configured for cloning into the workspace.
+* **Source Path:** Leave blank or enter a path (in the repository) for which you want to generate SBOM. Use this setting to generate SBOM for a specific section of your code repo, rather than your entire repo. The path must start with `/`.
+   For example, if your repository URL is `https://github.com/username/repo`, and you want to generate SBOM for `https://github.com/username/repo/service-core/source`, then enter `/service-core/source` for **Source Path**.
+   To generate an SBOM for the entire repository, leave this field empty.
+* **Git Branch:** The branch of the repository for which you want to generate the SBOM.
+* **Workspace:** If you cloned the codebase to a different directory than the root workspace directory (`/harness`), enter the path to the subdirectory using the format `/harness/PATH/TO/SUBDIRECTORY`. Leave this field empty if you cloned your codebase into the default directory (`/harness`). Usually, your codebase is only cloned into a non-default directory if you are [cloning multiple codebases](/docs/continuous-integration/use-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline) into a pipeline.
+
+</TabItem>
+</Tabs>

docs/software-supply-chain-assurance/shared/cosign-attestation-options.md

@@ -0,0 +1,44 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import CosignKeyGeneration from '/docs/software-supply-chain-assurance/shared/generate-cosign-key-pair.md';
+
+<Tabs>
+  <TabItem value="Cosign" label="Cosign">
+
+  To perform attestation with **Cosign** selected, you need a key pair. Follow the instructions below to generate the key pair.
+
+  <details>
+  <summary>Generate key pairs using Cosign for SBOM attestation</summary>
+
+  <CosignKeyGeneration />
+
+  </details>
+
+  - **Private Key**: Input your Private key from the [Harness file secret](/docs/platform/secrets/add-file-secrets).
+  - **Password**: Input your Password for the Private key from the [Harness file secret](/docs/platform/secrets/add-file-secrets).
+
+  </TabItem>
+
+  <TabItem value="Cosign with Secret Manager" label="Cosign with Secret Manager">
+
+In this mode, you can pass your **Cosign keys** using a **Secret Manager**. Currently, SCS supports only the **HashiCorp Vault** secret manager. You can connect your Vault with Harness using the [Harness HashiCorp Vault connector](/docs/platform/secrets/secrets-management/add-hashicorp-vault/). Here are the key points to consider when connecting your Vault:
+
+1. **Enable the Transit Secrets Engine** on your HashiCorp Vault. This is essential for key management and cryptographic operations.
+2. Configure your HashiCorp Vault connector using the following authentication methods [**AppRole**](/docs/platform/secrets/secrets-management/add-hashicorp-vault/#option-app-role), [**Token**](/docs/platform/secrets/secrets-management/add-hashicorp-vault/#option-token), [**Vault Agent**](/docs/platform/secrets/secrets-management/add-hashicorp-vault/#option-vault-agent)  
+3. Create a Cosign key pair of type `ecdsa-p256` in the Transit Secrets Engine. You can do this in two ways:  
+   - **CLI**: Run the command:  
+     ```bash
+     vault write -f <transit_name>/<key_name> type=ecdsa-p256
+     ```  
+   - **Vault UI**: Create the key pair directly from the Vault interface.
+4. Ensure the Vault token generated has the **[required policy](https://docs.sigstore.dev/cosign/key_management/overview/#hashicorp-vault)** applied for Cosign to perform attestation operations.
+
+Configure the following fields in the step to perform the attestation
+
+- **Connector**: Select the HashiCorp Vault connector.  
+- **Key**: Enter the path to the Transit Secrets Engine in your HashiCorp Vault where the keys are stored.
+
+</TabItem>
+
+</Tabs>

docs/software-supply-chain-assurance/shared/cosign-verification-options.md

@@ -0,0 +1,21 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="Cosign" label="Cosign">
+
+  To perform the attestation verification with Cosign selected, you need to pass the key from the Harness Secret Manager
+  - **Public Key**: Input your Public key from the [Harness file secret](/docs/platform/secrets/add-file-secrets).
+
+  </TabItem>
+
+  <TabItem value="Cosign with Secret Manager" label="Cosign with Secret Manager">
+
+  If you used **HashiCorp Vault** as your Secret Manager for attestation, you can also use it for verifying the attestation.
+
+  - **Connector**: Select the same HashiCorp Vault connector that was used during the attestation process.
+  - **Key**: Enter the path to the Transit Secrets Engine in your HashiCorp Vault where your **public key** is stored. This should be the same path used for the attestation process. Note that **HashiCorp Vault** does not allow viewing the public key directly.
+
+  </TabItem>
+
+</Tabs>

docs/software-supply-chain-assurance/shared/generate-cosign-key-pair.md

@@ -2,5 +2,5 @@ To perform the attestation process, you need to input the private key and passwo
 
 1. [Install Cosign](https://docs.sigstore.dev/system_config/installation/)
 2. Run the command `cosign generate-key-pair` to generate the key pairs.
-3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
+3. Make sure to note the password used for generating the key pairs. This password is needed along with the private key for performing the attestation.
 4. This command will generate a private key as a `.key` file and a public key as a `.pub` file. To securely store these files, use [Harness file secret](/docs/platform/secrets/add-file-secrets).

docs/software-supply-chain-assurance/slsa/generate-slsa.md

@@ -48,8 +48,6 @@ Follow the instructions below to configure the **SLSA Generation** step.
 
 * **Artifact Digest:** Specify the digest of your artifact. After building your image using the [Build and Push](#slsa-generation-step-configuration-with-build-and-push-step) step or a [Run](#slsa-generation-step-configuration-with-run-step) step, save the digest in a variable. You can then reference it here using an [Harness Expressions](/docs/platform/variables-and-expressions/harness-variables/). Refer to the workflows described below for detailed guidance.
 
-<!-- <DocImage path={require('../slsa/static/slsa-ver-dockerhub.png')} width="50%" height="50%" title="Click to view full size image" /> -->
-
 </TabItem>
 
 <TabItem value="ecr" label="ECR" default>
@@ -65,10 +63,6 @@ Follow the instructions below to configure the **SLSA Generation** step.
 * **Account ID:** The unique identifier associated with your AWS account.
 
 
-
-<!-- <DocImage path={require('../slsa/static/slsa-ver-ecr.png')} width="50%" height="50%" title="Click to view full size image" />  -->
-
-
 </TabItem>
 
 <TabItem value="gcr" label="GCR" default>
@@ -84,9 +78,6 @@ Follow the instructions below to configure the **SLSA Generation** step.
 * **Project ID:** Enter the unique identifier of your Google Cloud Project. The Project-ID is a distinctive string that identifies your project across Google Cloud services. example: `my-gcp-project`
 
 
-<!-- <DocImage path={require('../slsa/static/slsa-ver-gcr.png')} width="50%" height="50%" title="Click to view full size image" /> -->
-
-
 </TabItem>
 
 <TabItem value="acr" label="ACR" default>
@@ -99,9 +90,6 @@ Follow the instructions below to configure the **SLSA Generation** step.
 
 * **Subscription Id:** Enter the unique identifier that is associated with your Azure subscription. 
 
-
-<!-- <DocImage path={require('../slsa/static/slsa-ver-acr.png')} width="50%" height="50%" title="Click to view full size image" /> -->
-
 </TabItem>
 
 <TabItem value="gar" label="GAR" default>
@@ -116,37 +104,29 @@ Follow the instructions below to configure the **SLSA Generation** step.
 
 * **Project ID:** Enter the unique identifier of your Google Cloud Project. The Project-ID is a distinctive string that identifies your project across Google Cloud services. example: `my-gcp-project`
 
-
-<!-- <DocImage path={require('../slsa/static/slsa-ver-gar.png')} width="50%" height="50%" title="Click to view full size image" /> -->
-
 </TabItem>
 
 
 </Tabs>
 
 With this configuration, the step generates the SLSA Provenance and stores it in the [Artifact section](../artifact-view.md) of SCS. To attest to the generated provenance, follow the instructions in the section below.
 
-#### Attest SLSA Provenance
+### Attest SLSA Provenance
 
 To configure attestation, along with the [above configuration](#slsa-generation-step-configuration) you should enable the **SLSA Attestation** checkbox in the **SLSA Generation** step. This requires a key pair generated using **Cosign**.
 
-<details>
-<summary>Generate key pairs using Cosign for SLSA provenance attestation</summary>
-
-<CosignKeyGeneration />
-
-</details>
+You can perform the attestation with **Cosign** or **Cosign with Secret Manager**
 
-Using the **Cosign** option, set your **Private Key** from the key pair along with the associated **Password**. Ensure that your **Public Key** is stored securely, as it will be needed for verifying the provenance attestation. For more details, refer to [SLSA Verification](#slsa-verification).
+import CosignAttestationOptions from '/docs/software-supply-chain-assurance/shared/cosign-attestation-options.md';
 
-<DocImage path={require('./static/slsa-generation-step.png')} width="50%" height="50%" />
+<CosignAttestationOptions />
 
 
 ## SLSA Generation step configuration with Build and Push step
 When using the Harness CI **Build and Push** step for the image-building process, you can configure the **SLSA Generation** step to generate and attest to the Provenance. Follow the [SLSA Generation step configuration](#slsa-generation-step-configuration), for the **Artifact Digest** field, you can use [Harness Expressions](/docs/platform/variables-and-expressions/harness-variables/) to dynamically populate the digest of the image built during the **Build and Push** step.  
 
 For example, the expression could look like:  
-`<+pipeline.stages.<YOUR_STEP_NAME>.spec.execution.steps.<YOUR_BUILD_AND_PUSH_STEP_NAME>.output.outputVariables.digest>`  
+`<+pipeline.stages.<YOUR_STAGE_NAME>.spec.execution.steps.<YOUR_BUILD_AND_PUSH_STEP_NAME>.output.outputVariables.digest>`  
 
 If you have already executed the **Build and Push** step, navigate to the execution details, open the **Output Variables** tab, and copy the expression for the digest from the **Input Name** column.