DOCSEARCHbyAlgolia
Submit Docs

GUAC (Graph for Understanding Artifact Composition)

repository·main·Indexed 23 days ago

https://github.com/guacsec/guac

An aggregation and synthesis layer for the software supply chain that normalizes and maps software security metadata into a high-fidelity graph database. GUAC includes a GraphQL server (guacgql), a REST API interface (guacrest), and various binaries for ingestion and collection such as guacone, guaccollect, guacingest, and guaccsub. It supports multiple database backends including Neo4j, ArangoDB, and Ent.

Tokens
27.6K
Snippets
25
Records
200
Agent score
81%

What's inside GUAC

  1. What is the guacrest API?

    main
    guacrest is an experimental component of the GUAC project that provides a REST API interface to the underlying GUAC GraphQL services. It is designed for clients that prefer or require a RESTful endpoint instead of interacting with GraphQL directly.

  2. Implement a custom GUAC Assembler backend

    main

    To create a new backend for the GUAC Assembler GraphQL server, you must implement two interfaces defined in backends.go:

    1. A resolver interface: This interface contains the implementation for every required resolver. Implementing this ensures that your backend provides all the functionality expected by the GraphQL server.
    2. A creation interface: An empty interface used to define the specific arguments required to initialize your backend (e.g., connection strings, credentials).

    Note: The backend implementation is currently in an experimental state and is subject to change.

  3. Understand the difference between guacone and guaccollect

    main

    GUAC distinguishes between user-facing tools and service-oriented components through two primary binaries:

    1. guacone (User-facing):

      • Used by users or testers to accomplish specific tasks.
      • Acts as an all-in-one processor/ingestor/assembler.
      • Dependency: Only requires the GraphQL backend (guacgql) to be running.
      • Behavior: Typically runs once by default.

    2. guaccollect (Service):

      • Used as part of a standard GUAC deployment (e.g., in a container or as a systemd service).
      • Dependency: Requires the NATS ingestion pipeline to be running.
      • Behavior: Designed to run continuously (polling, watching, etc.).

  4. How the GitHub Collector works

    main

    The GitHub Collector is a GUAC component that downloads metadata documents from GitHub releases or workflow artifacts. It operates in two distinct modes:

    1. Release Mode: Targets specific GitHub releases to collect assets that match predefined suffixes.
    2. Workflow Mode: Targets artifacts generated by GitHub Actions workflows within a specific repository.

    The collector uses a GitHub client to interact with the GitHub API and stores the collected documents in a blob store. To function, the collector requires guacIngest to be running, along with a pubsub system and a blob store.

  5. Understand GUAC GraphQL backends

    main

    GUAC provides a consistent GraphQL API regardless of the underlying storage backend. Backends are categorized by support status, completeness, and optimization level.

    Recommended for Beginners

    • keyvalue: A non-persistent, in-memory backend. It requires no additional infrastructure and serves as a conformance backend for API implementations. Use this to start quickly.

    Production/Persistent Backends

    • ent with PostgreSQL: A persistent backend based on Entity Framework for Go. Note: GUAC only supports ent with PostgreSQL; other SQL backends like MySQL or SQLite are unsupported.

    Other Available Backends

    BackendStatusCompletenessOptimization
    arangoDBUnsupportedIncompleteOptimized
    neo4j/openCypherUnsupportedIncompleteN/A
    keyvalue: RedisExperimentalCompleteN/A
    keyvalue: TiKVExperimentalCompleteN/A

  6. Use the correct structs for GraphQL client operations

    main

    When writing code that interacts with the GUAC Assembler via GraphQL, do not use structs defined in assembler/graphql directly. Those structs are intended for server-side use and are regenerated whenever the GraphQL schema changes.

    Instead, use the structs defined in pkg/assembler/clients (or other specialized client utility packages). These structs are specifically generated based on the query documents sent to the server, ensuring compatibility with the intended operations.

  8. Enable OpenTelemetry (Otel) metrics in GUAC CLIs

    main

    GUAC uses OpenTelemetry instrumented libraries for several core components (HTTP GQL server, SQL library, and various HTTP/GRPC clients). Any CLI tool that utilizes these components provides an --enable-otel option.

    When enabled, the CLI sets up default metric and trace providers configured to connect to an OpenTelemetry collector via gRPC. Configuration is handled via the following environment variables:

    • OTEL_EXPORTER_OTLP_ENDPOINT: The address of the Otel collector.
    • OTEL_EXPORTER_OTLP_INSECURE: Set to true to disable TLS (useful for local collectors).
    • OTEL_SERVICE_NAME: The name of the service to be attached to the metrics.

  9. Collect Kubescape SBOMs using guacone

    main

    The Kubescape GUAC Collector connects to the Kubernetes API server to retrieve sbomsyfts or sbomsyftfiltereds objects, extracts the SBOMs, and ingests them into GUAC.

    Depending on your configuration, you can perform a one-time collection or enable polling to watch for new objects. The collector must run within a Kubernetes cluster and use a ServiceAccount with appropriate RBAC permissions.

  10. Implement GraphQL resolvers in GUAC

    main

    When extending or modifying the GraphQL server, you will interact with several key components:

    • resolvers/: Contains the logic for GraphQL queries. These must be updated whenever the schema changes.
    • resolvers/resolver.go: The root resolver definition. It links the GraphQL interface to the underlying backends via the Backend field.
    • model/nodes.go: Contains Go structures that map directly to GraphQL interface types.

    Important: While model/nodes.go is used within resolvers, it is not recommended to depend on these structures from other parts of the GUAC codebase. Instead, use the client GraphQL interface to interact with the data.

  11. Run the GitHub Collector in Workflow Mode

    main

    Use Workflow Mode to collect artifacts generated by a specific GitHub Actions workflow file within a repository.

    Prerequisites:

    • A valid GitHub token must be set in the GITHUB_TOKEN environment variable.
    • guacIngest, a pubsub, and a blob store must be available.

    Command Syntax:

    guaccollect github --github-mode=workflow --github-workflow-file=<WORKFLOW_FILE_NAME> [flags] <OWNER>/<REPO>

  12. Run Atlas migrations for ENT via Docker

    main

    You can use a specialized Docker image to run Atlas migrations for the ENT backend. This requires building the image locally first and then running it with the appropriate PostgreSQL environment variables.

    1. Build the image

    docker build . -t atlas-migration

    2. Run the migration

    Depending on your database location, use one of the following commands:

    Local Server

    If the database is running on your host machine, use host.docker.internal as the PGHOST:

    docker run -e PGHOST=host.docker.internal \
           -e PGPORT=5432 \
           -e PGDATABASE=guac \
           -e PGUSER=guac \
           -e PGPASSWORD=guac \
           --network bridge \
           atlas-migration

    Remote Server

    For remote databases, provide the specific connection details via environment variables:

    docker run -e PGHOST=your_host \
           -e PGPORT=your_port \
           -e PGDATABASE=your_database \
           -e PGUSER=your_user \
           -e PGPASSWORD=your_password \
           atlas-migration
    docker build . -t atlas-migration