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 | |
--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 workflow run artifacts containing metadata for a specified repository.
# Ingest from GitHub Releases
./guaccollect github --github-mode release https://github.com/owner/repo/releases/tag/v1.0.0
# Ingest from GitHub Workflows
./guaccollect github --github-mode workflow 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>