diff --git a/assets/images/guaccollectGraph.png b/assets/images/guaccollectGraph.png new file mode 100644 index 0000000..ab8fde1 Binary files /dev/null and b/assets/images/guaccollectGraph.png differ diff --git a/guaccollect.md b/guaccollect.md new file mode 100644 index 0000000..1b69f4a --- /dev/null +++ b/guaccollect.md @@ -0,0 +1,94 @@ +--- +layout: page +title: Ingesting data with GUACCollect +permalink: /guaccollect/ +parent: GUAC demos +grand_parent: Getting started with GUAC +nav_order: 2 +--- + +# Ingesting data with GUACCollect + +GUACCollect is a command-line tool within the GUAC ecosystem designed for collecting and ingesting software bill 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, making it a versatile choice for enhancing the visibility and security of your software supply chain. + +## Requirements + +- A fresh copy of the [GUAC service infrastructure through Docker Compose]({{ + site.baseurl }}{%link setup.md %}). Including the `guacone` binary in your path + and [GUAC Data](https://github.com/guacsec/guac-data/archive/refs/heads/main.zip) + extracted to `guac-data-main`. +- Access to data sources: Depending on what sources you're collecting from, S3, GitHub, GCS, or OCI images. + +## Use Cases + +GUACCollect enables users 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 + +GUACCollect offers a modular design with separate commands for each data source. Here are some examples: + +### GitHub + +```bash +./guaccollect github --github-mode release +./guaccollect github --github-mode workflow / +``` + +### S3 Compatible Storage + +```bash +./guaccollect s3 --s3-url --s3-bucket --poll +``` + +### Google Cloud Storage (GCS) + +```bash +./guaccollect gcs --gcs-credentials-path /path/to/credentials.json +``` + +### OCI Images + +```bash +./guaccollect image +``` + +### Files + +```bash +./guaccollect files +``` + +![guaccollect graph](assets/images/guaccollectGraph.png) + +## Configuration + +GUACCollect supports various configuration flags for advanced usage. Use the `--help` flag to explore all options: + +```bash +./guaccollect --help +``` + +## Demo + +To collect metadata from GitHub using GUACCollect, you'll need to specify the mode of collection release or workflow and provide the necessary GitHub URLs or repository details. Here's a step-by-step example for the workflow mode: + +### Collecting from GitHub Workflows + +To collect metadata from GitHub workflows, use the `github` command with the `--github-mode workflow` flag. Specify the owner and repository name in the format `/`. For example: + +```bash +./guaccollect github --github-mode=workflow guacsec/guac-test +``` + +This command collects metadata from the workflows of the specified GitHub repository. + +## Conclusion + +GUACCollect is a key tool in the GUAC ecosystem for collecting and ingesting metadata documents, enhancing the visibility and security of your software supply chain. With its support for multiple data sources and flexible configuration, GUACCollect simplifies the process of building a comprehensive view of your software artifacts and their associated metadata. + +For more detailed information, refer to the official [GUAC documentation](https://docs.guac.sh/). \ No newline at end of file diff --git a/known-and-unknown.md b/known-and-unknown.md index e4e5067..efbdcbd 100644 --- a/known-and-unknown.md +++ b/known-and-unknown.md @@ -4,7 +4,7 @@ title: What is Known and Unknown about your software supply chain? permalink: /known-and-unknown/ parent: GUAC demos grand_parent: Getting started with GUAC -nav_order: 2 +nav_order: 3 --- # What is Known and Unknown about your Software Supply Chain diff --git a/patch-cli.md b/patch-cli.md index 1aa662e..122c592 100644 --- a/patch-cli.md +++ b/patch-cli.md @@ -4,7 +4,7 @@ title: Querying for a patch plan via CLI permalink: /patch-plan/ parent: GUAC demos grand_parent: Getting started with GUAC -nav_order: 5 +nav_order: 6 --- # Query for a patch plan via CLI Demo diff --git a/querying-via-cli.md b/querying-via-cli.md index 558b978..5031f93 100644 --- a/querying-via-cli.md +++ b/querying-via-cli.md @@ -4,7 +4,7 @@ title: Querying vulnerabilities via CLI permalink: /querying-via-cli/ parent: GUAC demos grand_parent: Getting started with GUAC -nav_order: 3 +nav_order: 4 --- # Query Vulnerability via CLI Demo diff --git a/supply-chain.md b/supply-chain.md index 9fb140b..311cefb 100644 --- a/supply-chain.md +++ b/supply-chain.md @@ -4,7 +4,7 @@ title: Reacting to a supply chain incident permalink: /supply-chain/ parent: GUAC demos grand_parent: Getting started with GUAC -nav_order: 4 +nav_order: 5 --- # Reacting to a supply chain incident