From b030dee1be24fc4c1592d92272abf957b97551f6 Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Mon, 3 Jul 2023 18:22:01 +0200 Subject: [PATCH 1/2] feat(guac): add video to guide Signed-off-by: Miguel Martinez Trivino --- .../plugins/core/guac/v1/README.md | 49 ++++++++++++++----- 1 file changed, 36 insertions(+), 13 deletions(-) diff --git a/app/controlplane/plugins/core/guac/v1/README.md b/app/controlplane/plugins/core/guac/v1/README.md index 436026290..94b364d73 100644 --- a/app/controlplane/plugins/core/guac/v1/README.md +++ b/app/controlplane/plugins/core/guac/v1/README.md @@ -2,28 +2,35 @@ Graph for Understanding Artifact Composition ([GUAC](https://github.com/guacsec/guac)) aggregates software security metadata into a high fidelity graph database—normalizing entity identities and mapping standard relationships between them. Querying this graph can drive higher-level organizational outcomes such as audit, policy, risk management, and even developer assistance. -This integration allows Chainloop users to automatically send attestation (DSSE envelopes / in-toto statements) and CycloneDX/SPDX Software Bill Of Materials (SBOMs) to a cloud storage bucket staging area. From there, GUAC can be configured to continuously monitor and inject that data. Compatible with Guac v0.1.0 beta or newer. +Chainloop users can **automatically send signed [in-toto](https://in-toto.io/) attestations and both [CycloneDX](https://cyclonedx.org/) and [SPDX](https://spdx.dev/) Software Bill Of Materials (SBOMs)** to a cloud storage bucket. From there, GUAC can be configured to continuously monitor and inject that data. ![GUAC integration](./img/overview.png) +## Demo -## How to use it + + Use Guac with Chainloop + -Currently, this integration only supports [Google Cloud Storage](https://cloud.google.com/storage) (GCS) as a storage provider with more to come in the future. If you are interested in a specific provider, please [let us know](https://github.com/chainloop-dev/chainloop/issues/new) +## Configure Integration in Chainloop +There are two steps involved to enable this integration: -### Chainloop setup -#### Using Google Cloud Platform +1. Register a Guac integration in your Chainloop account +2. Attach this integration to your workflow + +### Registration + +Currently, this integration only supports [Google Cloud Storage](https://cloud.google.com/storage) (GCS) as a storage provider, with more to come in the future. If you are interested in a specific provider, please [let us know](https://github.com/chainloop-dev/chainloop/issues/new) + +#### Using Google Cloud Storage (GCS) **Prerequisites** - A Google Cloud Platform (GCP) account - A GCP project with a GCS bucket - A GCP service account with write access to the bucket. See [Creating and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) for more information. -- Once create, download the service account [JSON credentials file](https://developers.google.com/workspace/guides/create-credentials#create_credentials_for_a_service_account) - - -**Registration** +- Once created, download the service account [JSON credentials file](https://developers.google.com/workspace/guides/create-credentials#create_credentials_for_a_service_account) To get started, you need to register the plugin in your Chainloop organization. @@ -34,7 +41,7 @@ $ chainloop integration registered add guac --opt bucket=[my-bucket-name] --opt $ chainloop integration registered add guac --opt bucket=test-guac --opt credentials="$(cat ./service-account-devel.json)" --opt provider=gcs ``` -**Attachment** +### Attachment Then, in order to use the integration, you need to attach it to a workflow by providing the IDs of the workflow and integration you just registered. @@ -42,13 +49,29 @@ Then, in order to use the integration, you need to attach it to a workflow by pr $ chainloop integration attached add --workflow $WID --integration $ID ``` -That's all on the Chainloop side. Now all new attestation and SBOM metadata files will get uploaded to Google Cloud Storage. +That's all on the Chainloop side. Now all new attestation and SBOM metadata files will get uploaded to your Google Cloud Storage bucket. +## Configure Guac +Next, we need to configure Guac to pick up the files from the bucket and inject them into the graph. Please refer to [guacsec/guac](https://docs.guac.sh) documentation to learn more. -### GUAC setup +But in a nutshell, you need to: -Refer to https://github.com/guacsec/guac documentation to learn how to setup GUAC to import from a GCS-based collector. +- [Have a Guac instance up and running](https://docs.guac.sh/setup) +- Ingest the data from the bucket into the graph + +> NOTE: Currently, importing GCS data into Guac requires manually running a `collect` command. The community [is discussing](https://github.com/guacsec/guac/issues/1005) how to run this process periodically and automatically. + + +```bash +# Build the guacone CLI +git clone https://github.com/guacsec/guac.git +cd guac && make build + +# Ingest the data +guacone collect gcs test-guac --gcp-credentials-path service-account-devel.json +``` +That's all, now the data is available in the graph and you can query or visualize it. ## Registration Input Schema From aa730faf7897702db1eb1dd4ea09f0c0686caa6f Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Mon, 3 Jul 2023 18:23:33 +0200 Subject: [PATCH 2/2] feat(guac): add video to guide Signed-off-by: Miguel Martinez Trivino --- app/controlplane/plugins/core/guac/v1/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/controlplane/plugins/core/guac/v1/README.md b/app/controlplane/plugins/core/guac/v1/README.md index 94b364d73..414e09460 100644 --- a/app/controlplane/plugins/core/guac/v1/README.md +++ b/app/controlplane/plugins/core/guac/v1/README.md @@ -8,6 +8,8 @@ Chainloop users can **automatically send signed [in-toto](https://in-toto.io/) a ## Demo +You can see a demo of this integration in action in the following video: + Use Guac with Chainloop