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:
For an in-depth view and explanation of components of the GUAC Beta, please refer to how GUAC works.
Supported input documents
- CycloneDX
- Dead Simple Signing Envelope
- Deps.dev API
- In-toto ITE6
- OpenSSF Scorecard
- OSV
- SLSA
- SPDX
- CSAF/CSAF VEX
- OpenVEX
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
- Complete/Incomplete: Complete backends support all mandatory GraphQL
- Optimized: The backend has gone through a level of optimization to help
The two backend that are Supported, Complete, and Optimized are:
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! 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:
optimized): a persistent backend based on ArangoDB incomplete): a persistent backend based on neo4j and openCypher. This backend should work with any database that supported openCypher queries. default keyvalue backend, but using Redis as storage. default keyvalue backend, but using TiKV as storage.Additional References
- GUAC use cases
- GUAC presentation at OSS NA 2023
- GUAC 2023 Q1 Maintainer Summit Notes
- GUAC presentation at KubeCon NA 2022
- GUAC Intro Slides
- GUAC Design Doc
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.