GUAC: Graph for Understanding Artifact Composition

Note: GUAC is under active development - if you are interested in contributing, please look at contributor guide.

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.

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

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

The following are GraphQL backends that are implemented for GUAC. The backends are categorized into:

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

The enumerated backends 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!

• arangoDB (supported, incomplete, optimized): a persistent backend based on ArangoDB

• ent (supported, incomplete): a persistent backend based on ent that can run on various SQL backends such as PostgreSQL, MySQL and SQLite.

• 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

• 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 can be found here.