Skip to main content

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

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 --name 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:

info

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.