Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(guac): add video to guide #215

Merged
merged 2 commits into from
Jul 4, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 38 additions & 13 deletions app/controlplane/plugins/core/guac/v1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,37 @@

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
You can see a demo of this integration in action in the following video:

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)
<a href="http://www.youtube.com/watch?feature=player_embedded&v=XEeMeyC9ZJs" target="_blank">
<img src="http://img.youtube.com/vi/XEeMeyC9ZJs/0.jpg" alt="Use Guac with Chainloop" width="100%" height="500" border="10" />
</a>

## Configure Integration in Chainloop

### Chainloop setup
#### Using Google Cloud Platform
There are two steps involved to enable this integration:

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.

Expand All @@ -34,21 +43,37 @@ $ 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.

```sh
$ 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

Expand Down