GUAC Graph Setup, Backends, and Ingestion Constraints
GUAC aggregates software security metadata into a high fidelity graph database.
At a glance
- What is it?
- GUAC combines software supply-chain metadata in a queryable graph for audit, policy, risk analysis, and developer assistance. Its strongest documented path is a Docker-based service stack backed by in-memory keyvalue storage or PostgreSQL.
- Who is it for?
- GUAC suits teams that need a shared relationship model across CycloneDX, SPDX, SLSA, VEX, and related security documents, especially when PostgreSQL persistence and a multi-service deployment are acceptable. It is a poor fit for a user who only wants to scan one SBOM, retain metadata in an existing application database without a graph layer, or avoid any ingestion ambiguity.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Why GUAC Exists in a Supply-Chain Security Stack
GUAC addresses a data integration problem: SBOMs, vulnerability records, attestations, provenance, and VEX documents describe overlapping software entities through different identifiers and formats. Searching each source independently can show that a package or artifact is mentioned, but it does not necessarily establish how the records belong together. GUAC places aggregation and synthesis between those source documents and downstream organizational decisions.
The README identifies audit, policy, risk management, and developer assistance as intended outcomes of querying the graph. This positioning makes GUAC relevant to platform-security teams, software supply-chain teams, and organizations that already produce or consume attestations and machine-readable security metadata. It is less suitable as a standalone scanner. GUAC does not replace the systems that create SBOMs, fetch vulnerability data, or enforce policy. Its role is to normalize identities and expose relationships so that clients can ask broader questions.
That distinction matters operationally. A source document can be syntactically valid while still lacking the identifiers needed for reliable linkage. The documentation is direct about this: GUAC uses software identifier standards, but those identifiers are not always present, so GUAC sometimes applies heuristics. Consequently, a graph query does not automatically prove that two records represent the same component merely because an ingestion heuristic connected them.
How GUAC Normalizes and Connects Security Metadata
Based on the repository layout and README, GUAC separates collection, ingestion, API access, and storage behind a GraphQL abstraction. The Docker Compose stack includes `guac-collectsub`, `guac-ingestor`, an OCI collector, a `depsdev-collector`, NATS, GraphQL, and REST services. The ingestor consumes metadata events and writes normalized entities and relationships into the selected backend. The collectsub service and NATS provide the path between collectors and ingestion rather than requiring every source adapter to write directly to storage.
The supported document list includes CycloneDX, SPDX, CycloneDX-adjacent SBOM material identified by the repository topics, Dead Simple Signing Envelope, In-toto ITE6, SLSA, OSV, Deps.dev, OpenSSF Scorecard, CSAF and CSAF VEX, and OpenVEX. GUAC first resolves software identities and then maps standard relationships among them. Clients query the normalized graph through GraphQL, while the REST API is exposed separately in the development stack.
The GraphQL interface is intended to remain constant when the backend changes. That abstraction allows clients to avoid depending on a particular database query language. It does not remove backend differences. Unsupported or incomplete databases may lack mandatory API behavior or ongoing maintenance, so backend interchangeability is strongest within the two documented Supported, Complete, and Optimized choices.
Starting the Dev Container Stack for a First Query
The README does not print a complete shell command for launching the Docker Compose quickstart. It directs readers to `https://docs.guac.sh/setup/` for setup instructions, so reproducing an unstated `docker compose` invocation here would add an unsupported step. The repository does provide a more explicit path for developers: open the project in VS Code with the Dev Containers extension and select `Reopen in Container`.
The repository's `.devcontainer/devcontainer.json` configuration starts the full local stack, including GraphQL, REST, collectsub, ingestor, NATS, and the `deps_dev`, `osv`, and ClearlyDefined collectors. It uses the published GUAC release image and Docker. The GraphQL playground connects to port `8080`, while the REST API uses port `8081`. The same setup is documented as working with JetBrains Gateway and DevPod.
For a first real use, open the repository in the supported development environment and wait for the documented stack to start. Confirm that port `8080` serves the GraphQL playground and that port `8081` serves the REST API. Those are concrete readiness checks defined by the README. The README does not provide a sample GraphQL query or a named health endpoint for GUAC itself, so it would be misleading to invent either. The linked documentation and demo use cases are the stated next locations for querying ingested metadata.
If the container environment is unsuitable, the Compose quickstart is the repository's documented alternative, but its exact invocation and prerequisites belong to the linked setup documentation rather than the README excerpt.
Choosing keyvalue or PostgreSQL for the GUAC Graph
GUAC currently documents two backends as Supported, Complete, and Optimized. The `keyvalue` backend is non-persistent, runs in memory, and requires no additional database infrastructure. It also serves as the conformance backend for API implementations. The README recommends it for people starting with GUAC, which makes it a sensible way to inspect API behavior or run disposable local experiments.
The `ent` backend provides persistent storage through PostgreSQL and uses Entity Framework for Go. This is the documented path when accumulated graph data must survive service restarts. It also fits deployments that already operate PostgreSQL. GUAC explicitly supports `ent` only with PostgreSQL. MySQL and SQLite are named as unsupported `ent` backends and should not be treated as interchangeable production choices.
Other options have clear boundaries. ArangoDB is described as unsupported and incomplete, although optimized. Neo4j/openCypher is also unsupported and incomplete. Redis and TiKV appear under the keyvalue storage family as experimental and complete. Those labels do not mean GUAC recommends them for a new production deployment. They mean community contributions may be accepted even though the project does not actively maintain or support the corresponding configuration to the same degree as the primary backends.
A backend decision therefore changes more than storage cost. It changes persistence guarantees, infrastructure needs, API completeness, optimization status, and the maintainer's commitment to support. For an initial evaluation, `keyvalue` reduces operational work. For a persistent deployment, the documented choice is `ent` with PostgreSQL.
Where GUAC Ingestion Can Fail on Ambiguous Identities
The most important limitation is not the number of supported formats. It is the possibility that supported metadata cannot be joined reliably. The README states that software identifiers are not always available and that heuristics may be needed. Those heuristics can encounter edge cases and cause ingestion errors. The project asks users to report ingestion and data-quality problems through its issue template.
This creates a practical validation requirement. Source documents should be assessed for identifier coverage before results are treated as a complete relationship map. CycloneDX or SPDX records may describe components, but the README does not promise that every available record can be normalized to the same identity. Vulnerability data and attestations can also arrive through separate paths. The graph may contain useful nodes even when some expected relationships remain unresolved, so successful ingestion alone is not equivalent to complete linkage.
GUAC is also the wrong tool when the required question can be answered more cheaply inside an existing artifact catalog or vulnerability database. The service stack includes multiple long-running components and, for persistent use, PostgreSQL. A team with a single SBOM and no need for cross-source graph exploration may gain little from deploying it.
There is another boundary around decision-making. The README says graph queries can drive audit, policy, risk management, and developer assistance, but it does not claim that GUAC itself executes those policies or assigns risk scores. Clients consume the graph. Existing policy engines, audit workflows, and developer systems still need to interpret query results.
GUAC Compared with Keeping Security Documents Separate
The real alternative is not another graph database. It is retaining SBOMs, VEX records, provenance documents, and vulnerability findings in separate stores and resolving relationships inside individual applications. That approach can be simpler when one team owns one format and questions remain narrow. Its weakness appears when the same query must cross package, vulnerability, build, and attestation boundaries, because each application must implement identity matching and relationship handling again.
GUAC centralizes that work behind GraphQL and a shared software entity model. It accepts several established formats and turns their content into graph entities and relationships. This approach is more appropriate for organization-wide supply-chain analysis because the graph becomes a shared query surface instead of a collection format-specific search paths.
The trade-off is operational and semantic. A graph requires infrastructure, ingestion logic, and confidence in identity resolution. A collection of original documents may also be necessary for evidence retention, but GUAC's normalized view cannot compensate for missing identifiers in those inputs. Conversely, keeping documents separate avoids assuming that all records fit a common graph model. GUAC wins when cross-document relationship exploration is the primary requirement; separate stores remain simpler when it is not.
GUAC Release, License, and Upgrade Considerations
The repository uses the Apache-2.0 license. That permits use and modification under the license's stated conditions, including preservation of applicable notices. This is a factual description of the repository license, not legal advice. Organizations should review the actual `LICENSE` file when handling distribution or compliance obligations.
The documented release history includes `v1.0.0` on 2025-06-12, `v1.0.1` on 2025-09-24, and `v1.1.0` on 2026-03-13. The repository was last pushed on 2026-10-15. Its current development state is also described in the README, which calls GUAC under active development and links `CONTRIBUTING.md` for contributors. The repository is not archived.
An upgrade can affect more than the GUAC image because the stack combines GUAC services, NATS, collectors, and potentially PostgreSQL. The module file declares Go `1.27.0` for source builds, while the Dev Container path is documented as using the published release image. Upgrade planning should therefore compare the selected release's deployment documentation and backend configuration rather than treating a GUAC version change as an isolated binary replacement. The README does not document a rollback procedure for a partially completed upgrade.
Editorial conclusion
GUAC suits teams that need a shared relationship model across CycloneDX, SPDX, SLSA, VEX, and related security documents, especially when PostgreSQL persistence and a multi-service deployment are acceptable. It is a poor fit for a user who only wants to scan one SBOM, retain metadata in an existing application database without a graph layer, or avoid any ingestion ambiguity. Before adoption, verify that the source documents contain usable software identifiers, run representative ingestion samples against the intended backend, and confirm that the GraphQL queries required by audit, policy, and risk workflows produce the expected graph relationships.
Frequently asked questions
Which storage backends does GUAC actively support?
GUAC identifies `keyvalue` and `ent` with PostgreSQL as Supported, Complete, and Optimized backends. `keyvalue` is in-memory and non-persistent, while the supported persistent `ent` configuration uses PostgreSQL.
How do I run GUAC locally for a first query?
The README points to the Docker Compose quickstart in the setup documentation. For a development environment, it also describes opening the repository in VS Code and selecting `Reopen in Container`, then checking the GraphQL playground on port `8080` and REST API on port `8081`.
Why can GUAC fail to connect metadata for the same software artifact?
Software identifier standards help GUAC link records, but the README says those identifiers are not always available. When GUAC relies on heuristics, unhandled edge cases and ingestion errors can occur.
Does GUAC enforce security policy by itself?
The README says graph queries can drive audit, policy, risk management, and developer assistance. It does not state that GUAC performs policy enforcement or risk scoring itself, so those actions require separate clients or workflows.
Can GUAC use MySQL or SQLite instead of PostgreSQL?
No supported configuration is documented for either database. GUAC supports its `ent` backend with PostgreSQL and explicitly lists MySQL and SQLite as unsupported `ent` backends.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/guacsec-guac)Was this useful?