guaccollect
guaccollect is a command-line tool in the GUAC ecosystem designed for collecting and ingesting software bills of materials (SBOMs), attestations, and other metadata documents from various sources. This tool supports a wide range of data sources, including GitHub, S3, Google Cloud Storage (GCS), and OCI images.
Use Cases
guaccollect enables you to:
- Collect Metadata from GitHub: Fetch metadata documents from GitHub releases or workflows.
- Ingest from Cloud Storage: Support for S3, GCS, and other cloud storage solutions to ingest SBOMs and attestations.
- Download from OCI Images: Retrieve SBOMs and attestations embedded in OCI images.
- File System Collection: Collect documents directly from a specified file path on your system.
Usage
Commands
guaccollect supports the following commands:
| Command | Description |
|---|---|
| cd | Runs the Clearly Defined certifier |
| completion | Generate the autocompletion script for the specified shell |
| deps_dev | Runs the deps.dev certifier |
| files | Ingest a folder of files |
| gcs | Ingest SBOMs and attestations from a Google Cloud Storage bucket |
| github | Download metadata documents stored in GitHub releases or workflows |
| help | Help about any command |
| image | Ingests SBOMs and attestations stored in an OCI image |
| osv | Runs the OSV certifier |
| registry | Ingests SBOMs and attestations stored in an OCI registry |
| s3 | Ingests SBOMs and attestations from S3 compatible bucket |
| scorecard | Runs the OpenSSF Scorecard certifier |
Flags
guaccollect accepts the following flags. Subcommands have have additional flags.
| Flag | Description | Default |
|---|---|---|
--blob-addr string | gocloud connection string for blob store configured | “file:///tmp/blobstore?no_tmp_dir=true” |
--csub-addr string | Address to connect to collect-sub service | “localhost:2782” |
--csub-tls | Enable tls connection to the server | false |
--csub-tls-skip-verify | Skip verifying server certificate (e.g. for self-signed certificates) | false |
--enable-otel | Enable OpenTelemetry metrics and distributed tracing | false |
--enable-prometheus | Enable Prometheus metrics HTTP handler | false |
--gql-addr string | GraphQL server endpoint | “http://localhost:8080/query” |
-h, --help | Help for guaccollect | |
--label key=value | Attach HasMetadata labels to collected documents (repeatable) | none |
--prometheus-port int | Port to listen on for Prometheus metrics server | 9091 |
--publish-to-queue | Enable/disable message publish to queue | true |
--pubsub-addr string | gocloud connection string for pubsub configured | “nats://127.0.0.1:4222” |
--service-poll | Sets the collector or certifier to polling mode | true |
--use-csub | Use collectsub server for datasource | true |
-v, --version | Version for guaccollect |
Examples
guaccollect offers a modular design with separate commands for each data source.

GitHub
The GitHub collector fetches metadata documents, SBOMs, and attestations from GitHub releases or GitHub Action workflow runs.
It supports two modes:
- Release mode (
--github-mode release): Downloads release assets and attestations from specified GitHub release URLs. - Workflow mode (
--github-mode workflow): Ingests artifacts from the latest GitHub Actions workflow runs for a specified repository.
Workflow mode supports two additional filters:
| Flag | Description | Default |
|---|---|---|
--github-workflow-file string | Selects a workflow by its actual file name, such as ci.yaml, not by the workflow display name. If omitted, the collector checks all workflows in the repository. | empty |
--github-sbom string | Selects a GitHub Actions artifact by its artifact name. If omitted, the collector downloads all artifacts from the latest run of each selected workflow. | empty |
# Ingest from GitHub Releases
./guaccollect github --github-mode release https://github.com/owner/repo/releases/tag/v1.0.0
# Ingest artifacts from the latest run of every workflow in the repository
./guaccollect github --github-mode workflow owner/repo
# Ingest artifacts only from the workflow defined in .github/workflows/ci.yaml
./guaccollect github --github-mode workflow --github-workflow-file ci.yaml owner/repo
# Ingest only the artifact named sbom from that workflow's latest run
./guaccollect github --github-mode workflow --github-workflow-file ci.yaml --github-sbom sbom owner/repo
To authenticate against private repositories or avoid GitHub API rate limits, provide a GitHub Personal Access Token via GITHUB_TOKEN environment variable or --github-token flag:
export GITHUB_TOKEN=your_github_token
./guaccollect github --github-mode release https://github.com/owner/repo/releases/tag/v1.0.0
S3 Compatible Storage
./guaccollect s3 --s3-url <s3_url> --s3-bucket <bucket_name> --poll
Google Cloud Storage (GCS)
# Ingest from GCS using guaccollect
./guaccollect gcs <bucket_name> --gcp-credentials-path /path/to/credentials.json
# Ingest from GCS using guacone CLI
guacone collect gcs <bucket_name> --gcp-credentials-path /path/to/credentials.json
OCI Images and Registries
The OCI collector retrieves SBOMs and attestations attached to OCI container images or hosted inside OCI registries.
- OCI Image (
image): Collects attached metadata (such as Cosign attestations or embedded SBOM layers) from specific container image references. - OCI Registry (
registry): Ingests SBOMs and attestations directly from an OCI registry.
# Collect from OCI image(s) using guaccollect
./guaccollect image <image_ref1> <image_ref2>
# Collect from OCI registry using guaccollect
./guaccollect registry <registry_ref>
# Collect from OCI image using guacone CLI
guacone collect image <image_ref>
# Collect from OCI registry using guacone CLI
guacone collect registry <registry_ref>
Files
./guaccollect files <file_path>