GUAC Tutorial: Features, Use Cases, How It Works

TL;DR, What is GUAC?

GUAC provides a unified graph for understanding software supply chain security. DevSecOps teams often struggle with security data from separate tools like SBOM generators and vulnerability scanners. GUAC (Graph for Understanding Artifact Composition) solves that problem by collecting metadata, including SBOMs and SLSA attestations, into a single, queryable graph. The graph turns isolated data into useful intelligence, helping you correlate findings, understand dependencies, and see the real impact of vulnerabilities. As an incubating OpenSSF project, GUAC helps you make informed decisions by connecting raw security data to the bigger picture.

Software Supply Chain Security [Cheat Sheet]

Learn how to secure the software supply chain end-to-end – from managing third-party dependencies and open-source libraries to protecting build pipelines.

Your work email here

Download

At-A-Glance

• GitHub: https://github.com/guacsec/guac

• License: Apache-2.0

• Primary Language: Go

• Stars: 1.4k ⭐

• Last Release: v0.6.0 (August 15, 2024)

• Topics/Tags: software-supply-chain, security, sbom, slsa, vex, graph-database, security-management

Common use cases

1. Vulnerability impact analysis: When a new vulnerability is disclosed, you can query GUAC to instantly find every affected application. The tool helps you quickly assess the scope of the problem, prioritize fixes, and reduce your window of exposure.

2. Automated policy enforcement: You can integrate GUAC into CI/CD pipelines as a security gate. Before deployment, GUAC verifies that software meets your policies, like requiring a certain SLSA level or having no critical vulnerabilities. Using GUAC helps automate compliance and prevent insecure deployments.

3. Third-party dependency vetting: Before using a new open-source library, you can query GUAC to check its risk profile. By combining data like OpenSSF Scorecards and vulnerability history, GUAC helps you make informed decisions to avoid adding high-risk components to your supply chain.

4. Software provenance and auditing: For compliance and audits, GUAC provides a clear history for any software artifact. You can trace a component from source code to its final deployment, establishing a chain of custody that meets regulatory standards.

5. Incident response and forensics: During a security incident, your team can use GUAC for forensic analysis. You can trace a compromised artifact's origin, find other affected deployments, and discover related dependencies at risk, giving you the context needed to understand a breach's scope.

Catch code risks before you deploy

Learn how Wiz Code scans IaC, containers, and pipelines to stop misconfigurations and vulnerabilities before they hit your cloud.

Work Email*

First Name*

Last Name*

Country

Phone Number*

Company*

Keep me updated about Wiz product releases, industry news, and events (You can unsubscribe at any time)

Subscribe me to the Wiz blog digest emails

Submit

For information about how Wiz handles your personal data, please see our Privacy Policy.

Your work email here

Get a demo

How does GUAC work?

GUAC uses an asynchronous, microservices-based pipeline to collect and normalize software supply chain metadata. The process begins by gathering documents from different sources. Next, GUAC processes and transforms the documents into a unified graph model. The resulting graph shows the relationships between software artifacts, vulnerabilities, and build processes. You can then query the data through a GraphQL API to get security and dependency insights, no matter which storage backend you use.

• Data ingestion: Specialized collectors pull data from sources like Git repositories, cloud storage, and third-party APIs (e.g., deps.dev). The data then flows through a messaging system to create a resilient pipeline.

• Normalization and assembly: An ingestor component parses document formats like SPDX, CycloneDX, and SLSA and transforms them into GUAC’s data model. An assembler then saves these objects into a graph database.

• Flexible storage and querying: GUAC separates the storage layer, so it can support multiple backends like PostgreSQL and ArangoDB. A GraphQL server provides a consistent interface for querying supply chain relationships.

wiz academy

Software Supply Chain Best Practices [Step by Step Guide]

In this blog post, we’ll take a deep dive into software supply chains and discuss effective strategies for reducing security risks.

Read more

Core Capabilities:

1. Unified metadata ingestion: GUAC works as an SBOM aggregation tool, collecting security metadata in formats like SPDX, CycloneDX, SLSA attestations, and OSV vulnerability reports. The tool automatically normalizes the data into a single model. The normalization process resolves identity conflicts between data sources and establishes clear relationships. You can integrate your existing security tools without vendor lock-in and create one source of truth for your software supply chain.

2. Graph-based relationship mapping: GUAC uses a graph database to build a detailed software supply chain security graph. The graph model maps relationships between packages, dependencies, vulnerabilities, and build artifacts. Unlike traditional databases, the graph structure lets you run complex queries. You can track a component’s origin or find the full impact of a vulnerability across your software portfolio, gaining deep contextual insights.

3. Flexible GraphQL query API: GUAC provides its data through a flexible GraphQL API. The interface allows your teams to run specific and efficient queries against the software supply chain graph. The API is designed for both targeted analysis and large-scale data extraction, with filtering and pagination to maintain performance.

4. Pluggable storage architecture: GUAC is designed with a modular architecture that supports multiple storage backends, including in-memory stores, relational databases like PostgreSQL, and graph databases like ArangoDB. The flexibility allows you to deploy GUAC on your existing infrastructure and choose a backend that fits your scale and performance needs.

5. Automated data enrichment and certification: GUAC includes a "certifier" framework for automated analysis and data enrichment. Certifiers monitor the graph for new software artifacts and automatically attach additional information, such as policy compliance checks or security scores. The feature lets you codify your security policies, turning GUAC from a data repository into an active system that offers proactive insights and continuous verification.

Limitations

1. High initial configuration overhead: Setting up GUAC requires significant initial effort. You need specialized expertise to integrate data sources, choose and tune a storage backend, and deploy the system's components. The setup complexity can be a barrier for smaller teams without dedicated platform engineers.

2. Dependent on quality of input data: GUAC's insights are only as good as the metadata it receives. Inaccurate or incomplete SBOMs, attestations, and vulnerability reports will create an unreliable graph. The "garbage in, garbage out" problem means GUAC's effectiveness depends on a mature, high-quality security toolchain.

3. Steep learning curve for querying: The GraphQL API requires users to learn its specific syntax and the GUAC data model. Unlike tools with a simple UI, your team must become good at writing graph queries to get the most out of GUAC, which can be a challenge for those unfamiliar with GraphQL.

4. Focus on metadata, not code: GUAC is a metadata aggregation tool, not a code scanner. GUAC can identify a vulnerable library but cannot tell you if the vulnerable code is actually reachable or exploitable.

5. Operational complexity at scale: Managing GUAC at a large scale can be challenging. You need to maintain database performance, keep data pipelines running smoothly, and handle a rapidly growing graph. These tasks require ongoing maintenance and can lead to issues with query speed and storage costs.

Getting Started:

Step 1: Install Docker and Docker Compose if you do not have them already installed.

Step 2: Clone the GUAC repository:

git clone https://github.com/guacsec/guac.git

cd guac

Step 3: Start the GUAC services using Docker Compose:

docker-compose up

Step 4: Once the services are running, access the GUAC UI or APIs as outlined in the documentation at https://docs.guac.sh/.

FAQ:

Alternatives