Send SBOMs to Guac

Graph for Understanding Artifact Composition (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.

Chainloop users can automatically send signed in-toto attestations and both CycloneDX and SPDX Software Bill Of Materials (SBOMs) to a cloud storage bucket. From there, GUAC can be configured to continuously monitor and inject that data.

Demo

Configure Workflow

By default, attestations generated by a Chainloop Workflow will be picked up by this integration. In addition to that, any material of type SBOM_CYCLONEDX_JSON or SBOM_SPDX_JSON defined in your workflow contract will be taken as well.

example.yaml

schemaVersion: v1
materials:
  # Software Bill Of Materials (SBOMs) will be uploaded 
  # to your artifact registry and referenced by digest in the attestation
  # Both SPDX
  - type: SBOM_SPDX_JSON
    name: skynet-sbom
  # and CYCLONEDX SBOMs are supported
  - type: SBOM_CYCLONEDX_JSON
    name: skynet-sbom-cyclonedx

So the first step is to make sure you have a workflow that describes and attest Software Bill Of Materials. Learn more on how to set it up here.

Proceed to the next step once you have a workflow.

Configure Integration

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 (GCS) as a storage provider, with more to come in the future. If you are interested in a specific provider, please let us know

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 for more information.
• Once created, download the service account JSON credentials file

To get started, you need to register the integration in your Chainloop organization. To know what parameters are accepted, you can use the chainloop integration available describe command.

$ chainloop integration available describe --id guac                              
┌──────┬─────────┬─────────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ID   │ VERSION │ MATERIAL REQUIREMENT                │ DESCRIPTION                                                                                    │
├──────┼─────────┼─────────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────┤
│ guac │ 1.0     │ SBOM_CYCLONEDX_JSON, SBOM_SPDX_JSON │ Export Attestation and SBOMs metadata to a blob storage backend so guacsec/guac can consume it │
└──────┴─────────┴─────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────┐
│ Registration inputs                                                        │
├─────────────┬────────┬──────────┬──────────────────────────────────────────┤
│ FIELD       │ TYPE   │ REQUIRED │ DESCRIPTION                              │
├─────────────┼────────┼──────────┼──────────────────────────────────────────┤
│ bucket      │ string │ yes      │ Bucket name where to store the artifacts │
│ credentials │ string │ yes      │ Credentials to access the bucket         │
│ provider    │ string │ no       │ Blob storage provider: default gcs       │
└─────────────┴────────┴──────────┴──────────────────────────────────────────┘

Only bucket and credentials are required, let's register our integration by running chainloop integration registered add guac [opts]

$ chainloop integration registered add guac --name [my-registration] --opt bucket=[my-bucket-name] --opt credentials=[credentials-content] --opt provider=gcs

# Example
$ chainloop integration registered add guac --name [my-registration] --opt bucket=test-guac --opt credentials="$(cat ./service-account-devel.json)" --opt provider=gcs

┌──────────────────────────────────────┬──────────────────────────────────────┬─────────────────┬──────────────────────────────────────────┬─────────────────────┐
│ ID                                   │ DESCRIPTION                          │ KIND            │ CONFIG                                   │ CREATED AT          │
├──────────────────────────────────────┼──────────────────────────────────────┼─────────────────┼──────────────────────────────────────────┼─────────────────────┤
│ d4b9cec4-d79c-420f-aa63-cbc1cf9e8bdf │ Send to production GCS               │ guac            │ bucket: guac-prod                        │ 29 Jun 23 14:28 UTC │
│                                      │                                      │                 │ provider: gcs                            │                     │
└──────────────────────────────────────┴──────────────────────────────────────┴─────────────────┴──────────────────────────────────────────┴─────────────────────┘

Attachment

Then, in order to use the integration, you need to attach it to a workflow. That way, its attestation metadata and any associated SBOMs are routed to the configured storage backend.

To do so, just run the integration attached add and provide the IDs of the workflow and integration you just registered.

$ chainloop integration attached add --workflow $WID --integration $IID

# Example
$ chainloop integration attached add --workflow deadbeef --integration d4b9cec4-d79c-420f-aa63-cbc1cf9e8bdf
Integrations attached to workflows
┌──────────────────────────────────────┬─────────────────┬──────────────────────────────────────────┬─────────────────────┬─────────────────┐
│ ID                                   │ KIND            │ CONFIG                                   │ ATTACHED AT         │ WORKFLOW        │
├──────────────────────────────────────┼─────────────────┼──────────────────────────────────────────┼─────────────────────┼─────────────────┤
│ fa970e9c-3716-4d70-b76c-d6716a5f46b1 │ guac            │ bucket: guac-prod                        │ 29 Jun 23 20:48 UTC │ docs/release    │
│                                      │                 │ provider: gcs                            │                     │                 │
└──────────────────────────────────────┴─────────────────┴──────────────────────────────────────────┴─────────────────────┴─────────────────┘

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 documentation to learn more.

But in a nutshell, you need to:

• Have a Guac instance up and running
• Ingest the data from the bucket into the graph

Currently, importing GCS data into Guac requires manually running a collect command. The community is discussing how to run this process periodically and automatically.

# 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.