README
¶
SDK
This repository contains the public gRPC protos supporting our services, plus packages to ease integration with the Chainguard platform.
Updating *.proto files
After updating a *.proto you'll need to update the corresponding generated go
code.
Using Docker (recommended)
Run codegen in an ephemeral container with all dependencies pre-installed:
./hack/update-codegen-docker.sh
This requires Docker but no local installation of protoc or its plugins.
Running locally
./hack/update-codegen.sh
Prerequisites
Install protoc v34.1: https://grpc.io/docs/protoc-installation/
We currently require protoc v34.1.
Install protoc codegen dependencies:
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@v2.22.0
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@v2.22.0
Argos Platform Services
The proto/platform/argos/v1 package exposes two gRPC services over the
platform endpoint.
ArgosDocuments
ArgosDocuments manages organization-scoped, client-side-encrypted documents.
Callers require one of CAP_ARGOS_DOCUMENTS_CREATE, CAP_ARGOS_DOCUMENTS_LIST,
or CAP_ARGOS_DOCUMENTS_DELETE depending on the operation. Documents are
encrypted client-side before upload; the server never holds plaintext.
ArgosOSV
ArgosOSV provides OSV-format vulnerability query access to the Private OSV
shared corpus. All Argos members holding CAP_ARGOS_OSV_READ see the same
record set — there is no per-organisation filtering. The service exposes three
RPCs:
| RPC | HTTP | Description |
|---|---|---|
Query |
POST /argos/v1/osv/query |
Query vulnerabilities affecting a package at a version |
QueryBatch |
POST /argos/v1/osv/querybatch |
Batch form of Query |
GetVuln |
GET /argos/v1/osv/vulns/{id} |
Fetch a single OSV record by ID |
Records are returned in OSV schema format.
Breaking Changes
While we make every effort to maintain backward compatibility and avoid breaking changes, we cannot guarantee that future updates to this SDK will be entirely non-breaking. As our platform evolves and new features are added, some modifications to the API surface may be necessary. We recommend pinning to specific versions in production environments and thoroughly testing updates before deployment.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides gRPC credential helpers for authenticating Chainguard API requests using OIDC tokens, file-based tokens, or tokens stored in context values.
|
Package auth provides gRPC credential helpers for authenticating Chainguard API requests using OIDC tokens, file-based tokens, or tokens stored in context values. |
|
aws
Package aws provides utilities for generating and verifying Chainguard tokens backed by AWS identity credentials via the AWS STS GetCallerIdentity API.
|
Package aws provides utilities for generating and verifying Chainguard tokens backed by AWS identity credentials via the AWS STS GetCallerIdentity API. |
|
deviceflow
Package deviceflow implements the OAuth 2.0 Device Authorization Grant (RFC 8628) for obtaining OIDC identity tokens in headless or constrained-input environments.
|
Package deviceflow implements the OAuth 2.0 Device Authorization Grant (RFC 8628) for obtaining OIDC identity tokens in headless or constrained-input environments. |
|
ggcr
Package ggcr provides authentication integration between Chainguard identity tokens and the go-containerregistry library for accessing the cgr.dev container registry.
|
Package ggcr provides authentication integration between Chainguard identity tokens and the go-containerregistry library for accessing the cgr.dev container registry. |
|
headless
Package headless provides ECDH-based encryption utilities for the Chainguard headless login flow, enabling secure delivery of OIDC identity tokens to CLI clients without a browser redirect.
|
Package headless provides ECDH-based encryption utilities for the Chainguard headless login flow, enabling secure delivery of OIDC identity tokens to CLI clients without a browser redirect. |
|
login
Package login implements browser-based and headless OIDC login flows for Chainguard clients, returning access and refresh tokens.
|
Package login implements browser-based and headless OIDC login flows for Chainguard clients, returning access and refresh tokens. |
|
token
Package token manages the on-disk cache of Chainguard OIDC access and refresh tokens, organized by audience and optional alias.
|
Package token manages the on-disk cache of Chainguard OIDC access and refresh tokens, organized by audience and optional alias. |
|
Package civil implements types for civil time, a time-zone-independent representation of time that follows the rules of the proleptic Gregorian calendar with exactly 24-hour days, 60-minute hours, and 60-second minutes.
|
Package civil implements types for civil time, a time-zone-independent representation of time that follows the rules of the proleptic Gregorian calendar with exactly 24-hour days, 60-minute hours, and 60-second minutes. |
|
Package events defines CloudEvents extension keys and constants used across Chainguard platform event types, including delivery, registry, and audience classification extensions.
|
Package events defines CloudEvents extension keys and constants used across Chainguard platform event types, including delivery, registry, and audience classification extensions. |
|
apk
Package apk provides CloudEvents types for APK package registry operations.
|
Package apk provides CloudEvents types for APK package registry operations. |
|
generator
Package generator defines the CloudEvents event type and payload for on-demand vulnerability report generation requests.
|
Package generator defines the CloudEvents event type and payload for on-demand vulnerability report generation requests. |
|
receiver
Package receiver provides secure CloudEvent webhook receivers for Chainguard events.
|
Package receiver provides secure CloudEvent webhook receivers for Chainguard events. |
|
registry
Package registry defines CloudEvents event types and payload structs for Chainguard registry pull, push, and repository lifecycle events.
|
Package registry defines CloudEvents event types and payload structs for Chainguard registry pull, push, and repository lifecycle events. |
|
examples
|
|
|
registry/chainctl
command
|
|
|
registry/exchange
command
|
|
|
Package githubflow runs the GitHub App user (user-to-server) OAuth "loopback" flow shared by clients such as chainctl and the guardener OAuth test binary.
|
Package githubflow runs the GitHub App user (user-to-server) OAuth "loopback" flow shared by clients such as chainctl and the guardener OAuth test binary. |
|
helm
|
|
|
chart
Package chart provides utilities for reading and modifying Chainguard Helm charts stored as OCI artifacts or on the filesystem.
|
Package chart provides utilities for reading and modifying Chainguard Helm charts stored as OCI artifacts or on the filesystem. |
|
images
Package images provides utilities for parsing and resolving image value mappings embedded in Chainguard Helm chart packages.
|
Package images provides utilities for parsing and resolving image value mappings embedded in Chainguard Helm chart packages. |
|
v1
Package v1 provides types for chart-lock attestation data attached to Chainguard Helm charts.
|
Package v1 provides types for chart-lock attestation data attached to Chainguard Helm charts. |
|
Package octosts provides a client for minting and revoking GitHub installation tokens via the OctoSTS service using Workload Identity Federation.
|
Package octosts provides a client for minting and revoking GitHub installation tokens via the OctoSTS service using Workload Identity Federation. |
|
Package pathtree implements a hierarchical key-value tree where keys are slash-separated paths.
|
Package pathtree implements a hierarchical key-value tree where keys are slash-separated paths. |
|
proto
|
|
|
annotations
Package annotations contains the GRPC client and server definitions for implementing Auth interactions for the Console.
|
Package annotations contains the GRPC client and server definitions for implementing Auth interactions for the Console. |
|
capabilities
Package capabilities contains the proto enum with our IAM capabilities.
|
Package capabilities contains the proto enum with our IAM capabilities. |
|
chainguard/platform/actions/v1alpha1
Package v1alpha1 contains the gRPC client and server definitions for the actions entitlements and read-only actions catalog APIs.
|
Package v1alpha1 contains the gRPC client and server definitions for the actions entitlements and read-only actions catalog APIs. |
|
chainguard/platform/actions/v1alpha1/test
Package test provides mocks for the chainguard.platform.actions.v1alpha1 Actions service, suitable for unit testing consumers of the SDK.
|
Package test provides mocks for the chainguard.platform.actions.v1alpha1 Actions service, suitable for unit testing consumers of the SDK. |
|
chainguard/platform/clients/v2beta1
Package v2beta1 provides clients for Chainguard platform v2beta1 APIs.
|
Package v2beta1 provides clients for Chainguard platform v2beta1 APIs. |
|
chainguard/platform/events/v2beta1
Package v2beta1 provides Go clients for the Chainguard Events v2beta1 API.
|
Package v2beta1 provides Go clients for the Chainguard Events v2beta1 API. |
|
chainguard/platform/events/v2beta1/test
Package test provides mock implementations of the events v2beta1 service clients for use in unit tests.
|
Package test provides mock implementations of the events v2beta1 service clients for use in unit tests. |
|
chainguard/platform/guardener/v1alpha1
Package v1alpha1 contains the guardener GitHubAssociations service: the self-service surface for linking and unlinking a GitHub organization to a Chainguard group.
|
Package v1alpha1 contains the guardener GitHubAssociations service: the self-service surface for linking and unlinking a GitHub organization to a Chainguard group. |
|
chainguard/platform/iam/terms
Package terms provides version-agnostic types and error inspection for Chainguard Terms-of-Service acceptance.
|
Package terms provides version-agnostic types and error inspection for Chainguard Terms-of-Service acceptance. |
|
chainguard/platform/iam/v2beta1
Package v2beta1 provides clients for IAM v2beta1 services.
|
Package v2beta1 provides clients for IAM v2beta1 services. |
|
chainguard/platform/iam/v2beta1/test
Package test provides mock implementations of the IAM v2beta1 service clients for use in unit tests.
|
Package test provides mock implementations of the IAM v2beta1 service clients for use in unit tests. |
|
chainguard/platform/iter
Package iter provides generic pagination iterators for v2 APIs.
|
Package iter provides generic pagination iterators for v2 APIs. |
|
chainguard/platform/libraries/v2beta1
Package v2beta1 contains the v2beta1 Libraries Artifacts API protos and SDK client.
|
Package v2beta1 contains the v2beta1 Libraries Artifacts API protos and SDK client. |
|
chainguard/platform/ping/v2beta1
Package v2beta1 provides Go clients for the Chainguard Ping v2beta1 API.
|
Package v2beta1 provides Go clients for the Chainguard Ping v2beta1 API. |
|
chainguard/platform/registry/v2beta1
Package v2beta1 provides clients for registry v2beta1 services.
|
Package v2beta1 provides clients for registry v2beta1 services. |
|
chainguard/platform/registry/v2beta1/test
Package test provides mock implementations of the registry v2beta1 service clients for use in unit tests.
|
Package test provides mock implementations of the registry v2beta1 service clients for use in unit tests. |
|
chainguard/platform/test
Package test contains test-only proto definitions for SDK unit tests.
|
Package test contains test-only proto definitions for SDK unit tests. |
|
chainguard/platform/vulnerabilities/v2beta1
Package v2beta1 provides clients for vulnerabilities v2beta1 services.
|
Package v2beta1 provides clients for vulnerabilities v2beta1 services. |
|
chainguard/platform/vulnerabilities/v2beta1/test
Package test provides mock implementations of the vulnerabilities v2beta1 service clients for use in unit tests.
|
Package test provides mock implementations of the vulnerabilities v2beta1 service clients for use in unit tests. |
|
platform
Package platform provides gRPC client factories for all Chainguard platform services, including IAM, registry, advisory, and OIDC APIs.
|
Package platform provides gRPC client factories for all Chainguard platform services, including IAM, registry, advisory, and OIDC APIs. |
|
platform/actions/v1
Package v1 contains the v1 GRPC client and server definitions for authorizing GitHub Actions runners.
|
Package v1 contains the v1 GRPC client and server definitions for authorizing GitHub Actions runners. |
|
platform/advisory/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Advisory interactions.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Advisory interactions. |
|
platform/advisory/v1/test
Package test provides mock implementations of the advisory v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the advisory v1 gRPC clients for use in unit tests. |
|
platform/apk/v1
Package v1 contains the v1 GRPC client and server definitions for implementing APK interactions.
|
Package v1 contains the v1 GRPC client and server definitions for implementing APK interactions. |
|
platform/apk/v1/test
Package test provides mock implementations of the APK v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the APK v1 gRPC clients for use in unit tests. |
|
platform/argos/v1/test
Package test provides mock implementations of the v1 Argos clients.
|
Package test provides mock implementations of the v1 Argos clients. |
|
platform/auth/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Auth interactions for the Console.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Auth interactions for the Console. |
|
platform/auth/v1/test
Package test provides mock implementations of the auth service for testing.
|
Package test provides mock implementations of the auth service for testing. |
|
platform/common/v1
Package common contains Chainguard shared types exposed to the console.
|
Package common contains Chainguard shared types exposed to the console. |
|
platform/ecosystems/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Ecosystem interactions for the Console.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Ecosystem interactions for the Console. |
|
platform/ecosystems/v1/test
Package test provides mock implementations of the ecosystems v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the ecosystems v1 gRPC clients for use in unit tests. |
|
platform/events/v1
Package events contains the GRPC client and server definitions for implementing eventing interactions for the Console.
|
Package events contains the GRPC client and server definitions for implementing eventing interactions for the Console. |
|
platform/iam/v1
Package v1 provides gRPC client and server definitions for IAM interactions with the Chainguard Console.
|
Package v1 provides gRPC client and server definitions for IAM interactions with the Chainguard Console. |
|
platform/iam/v1/test
Package test provides mock implementations of IAM gRPC clients for testing.
|
Package test provides mock implementations of IAM gRPC clients for testing. |
|
platform/libraries/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Libraries interactions for the Console.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Libraries interactions for the Console. |
|
platform/libraries/v1/test
Package test provides mock implementations of the Libraries API clients for testing purposes.
|
Package test provides mock implementations of the Libraries API clients for testing purposes. |
|
platform/matcher/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Crystal Ball interactions.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Crystal Ball interactions. |
|
platform/matcher/v1/test
Package test provides mock implementations of the image matcher v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the image matcher v1 gRPC clients for use in unit tests. |
|
platform/oidc/v1
Package v1 contains the v1 GRPC client and server definitions for implementing OIDC interactions for the Platform.
|
Package v1 contains the v1 GRPC client and server definitions for implementing OIDC interactions for the Platform. |
|
platform/oidc/v1/test
Package test provides mock implementations of the OIDC v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the OIDC v1 gRPC clients for use in unit tests. |
|
platform/packages/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Packages interactions for the Console.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Packages interactions for the Console. |
|
platform/packages/v1/test
Package test provides mock implementations of the Packages API clients for testing purposes.
|
Package test provides mock implementations of the Packages API clients for testing purposes. |
|
platform/ping/v1
Package v1 contains the v1 GRPC client and server definitions for implementing ping interactions for the Platform.
|
Package v1 contains the v1 GRPC client and server definitions for implementing ping interactions for the Platform. |
|
platform/ping/v1/test
Package test provides mock implementations of the ping v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the ping v1 gRPC clients for use in unit tests. |
|
platform/policies/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Policies interactions.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Policies interactions. |
|
platform/policies/v1/test
Package test provides mock implementations of Policies gRPC clients for testing.
|
Package test provides mock implementations of Policies gRPC clients for testing. |
|
platform/registry/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Registry interactions.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Registry interactions. |
|
platform/registry/v1/test
Package test provides mock implementations of Registry gRPC clients for testing.
|
Package test provides mock implementations of Registry gRPC clients for testing. |
|
platform/skills/v1
Package v1 contains the v1 gRPC client and server definitions for implementing Skills Entitlements interactions.
|
Package v1 contains the v1 gRPC client and server definitions for implementing Skills Entitlements interactions. |
|
platform/tenant/v1
Package v1 contains the v1 GRPC client and server definitions for implementing Tenant interactions for the Console.
|
Package v1 contains the v1 GRPC client and server definitions for implementing Tenant interactions for the Console. |
|
platform/test
Package test provides mock implementations of the Chainguard platform gRPC clients for use in unit tests.
|
Package test provides mock implementations of the Chainguard platform gRPC clients for use in unit tests. |
|
platform/vulnerabilities/v1
Package v1 contains the platform API for the advisory service.
|
Package v1 contains the platform API for the advisory service. |
|
platform/vulnerabilities/v1/test
Package test provides mock implementations of the vulnerabilities v1 gRPC clients for use in unit tests.
|
Package test provides mock implementations of the vulnerabilities v1 gRPC clients for use in unit tests. |
|
Package sts provides OIDC token exchange functionality for Chainguard services.
|
Package sts provides OIDC token exchange functionality for Chainguard services. |
|
Package uidp contains utilities for reasoning about and manipulating the Chainguard IAM "UIDP" (UID Path) concept.
|
Package uidp contains utilities for reasoning about and manipulating the Chainguard IAM "UIDP" (UID Path) concept. |
|
Package uploads provides helpers for client-side-encrypted upload storage: the wire envelope shape and Seal / Parse / Open functions that mirror the browser's encryption.ts.
|
Package uploads provides helpers for client-side-encrypted upload storage: the wire envelope shape and Seal / Parse / Open functions that mirror the browser's encryption.ts. |
|
Package validation provides input validation helpers for Chainguard resource fields such as names, tags, descriptions, and Helm repository URLs.
|
Package validation provides input validation helpers for Chainguard resource fields such as names, tags, descriptions, and Helm repository URLs. |
Click to show internal directories.
Click to hide internal directories.