guac: Open Source ERP & Operations

What is guac?

What it is

GUAC is an OpenSSF incubating project under the Supply Chain Integrity WG that aggregates software security metadata into a high fidelity graph database. It is written in Go, released under Apache-2.0, and positioned in the software supply chain security ecosystem as the aggregation and synthesis layer of the supply chain transparency model.

The concrete problem it addresses is that security metadata arrives in many standards and sources, including SBOMs, attestations, vulnerability feeds, and package metadata. GUAC normalizes entity identities and maps standard relationships between them, so users can query one graph for audit, policy, risk management, and developer assistance instead of reconciling each artifact format separately.

Key capabilities

GUAC aggregates software security metadata into a high fidelity graph database.
It normalizes entity identities and maps standard relationships between them.
It ingests CycloneDX and SPDX SBOM inputs, including cyclonedx-sbom and spdx-sbom topics.
It ingests attestation and signing formats such as In-toto ITE6, SLSA, and Dead Simple Signing Envelope.
It ingests vulnerability and risk sources including OSV, OpenSSF Scorecard, CSAF/CSAF VEX, and OpenVEX.
It ingests package metadata from the Deps.dev API.
It exposes collected data through GraphQL and REST services, with a GraphQL playground and REST API in the development container.

Who uses it and how

Users responsible for audit, policy, and risk management query the normalized graph to support those outcomes.
Supply chain transparency programs use GUAC at the aggregation and synthesis layer, after collecting metadata from multiple standards and sources.
Developers use the graph for developer assistance, according to the documented use cases.
Teams run the full local GUAC stack with collectsub, ingestor, NATS, and collectors for deps_dev, osv, and ClearlyDefined.
Contributors and evaluators can open the repository in a Dev Container, Docker Compose quickstart, or documentation demos to inspect architecture and workflows.

Getting started

Typical startup methods are the Docker Compose quickstart and the repository Dev Container, which brings up the full GUAC stack on Docker using the published GUAC release image. Opening the repository in VS Code, JetBrains Gateway, or DevPod exposes the GraphQL playground on port 8080 and the REST API on port 8081.

When to use it — and when not to

GUAC fits when teams need to combine SBOMs, attestations, vulnerability data, and package metadata into one queryable graph for supply chain security work. It may not fit when teams need a fully stable product, because the README states it is under active development, the repository has 89 open issues, and ingestion can encounter unhandled edge cases and errors. A self-hoster must operate the Docker-based services, including NATS, collectsub, ingestor, collectors, GraphQL, and REST APIs, while relying on heuristics when software identifiers are unavailable.

project readme (upstream, from github) — read inline

GUAC: Graph for Understanding Artifact Composition

Note: GUAC is under active development - if you are interested in contributing, please look at contributor guide. GUAC is an OpenSSF incubating project under the Supply Chain Integrity WG.

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.

Conceptually, GUAC occupies the “aggregation and synthesis” layer of the software supply chain transparency logical model:

A few examples of questions answered by GUAC include:

Quickstart

Our documentation is a good place to get started.

We have various demos use cases that you can take a look.

Starting the GUAC services with our docker compose quickstart.

Try in a Dev Container

The repo ships a .devcontainer config that brings up the full GUAC stack (GraphQL, REST, collectsub, ingestor, NATS, and the deps_dev / osv / ClearlyDefined collectors) locally on Docker, backed by the published GUAC release image. Open the repo in VS Code with the Dev Containers extension and select "Reopen in Container" -- the GraphQL playground forwards to port 8080 and the REST API to 8081. Also works with JetBrains Gateway and DevPod.

Docs

All documentation for GUAC lives on docs.guac.sh, backed by the following docs github repository.

Architecture

Here is an overview of the architecture of GUAC:

guac_api

For an in-depth view and explanation of components of the GUAC Beta, please refer to how GUAC works.

Supported input documents

Note that GUAC uses software identifiers standards to help link metadata together. However, these identifiers are not always available and heuristics need to be used to link them. Therefore, there may be unhandled edge cases and errors occurring when ingesting data. We appreciate it if you could create a data quality issue if you encounter any errors or bugs with ingestion.

GraphQL backends

GUAC supports multiple backends behind a software abstraction layer. The GraphQL API is always the same and clients should be unaffected by which backend is in use. The backends are categorized into:

Supported/Unsupported: Supported backends are those which the GUAC project is committed to actively maintain. Unsupported backends are not actively maintained but will accept community contributions.
Complete/Incomplete: Complete backends support all mandatory GraphQL APIs. Incomplete backends support a subset of those APIs and may not be feature complete.
Optimized: The backend has gone through a level of optimization to help improve performance.

The two backend that are Supported, Complete, and Optimized are:

keyvalue (supported, complete, optimized): a non-persistent in-memory backend that doesn't require any additional infrastructure. Also acts as a conformance backend for API implementations. We recommend starting with this if you're just starting with GUAC!
ent (supported, complete optimized) with PostgreSQL: a persistent backend based on Entity Framework for Go that can run on various SQL backends. GUAC only supports ent with PostgreSQL. Other ent backends such as MySQL and SQLite are unsupported.

The other backends are:

arangoDB (unsupported, incomplete, optimized): a persistent backend based on ArangoDB
neo4j/openCypher (unsupported, incomplete): a persistent backend based on neo4j and openCypher. This backend should work with any database that supported openCypher queries.
keyvalue: Redis (experimental, complete): The default keyvalue backend, but using Redis as storage.
keyvalue: TiKV (experimental, complete): The default keyvalue backend, but using TiKV as storage.

Additional References

Communication

For more information on how to get involved in the community, mailing lists and meetings, please refer to our community page

For security issues or code of conduct concerns, an e-mail should be sent to [email protected].

Governance

Information about governance, including the project charter, can be found in the guacsec/governance repo.

Frequently asked questions

Is guac free to use?

guac is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does guac do?

GUAC aggregates software security metadata into a high fidelity graph database.

What is guac written in?

guac is primarily written in Go. Its source is publicly available at https://github.com/guacsec/guac, and it has 1,540 GitHub stars.