Documentation
¶
Index ¶
Constants ¶
const ( // MediaTypeArtifact is the OCI artifactType for ComplyPack artifacts. // Used as the second parameter to oras.PackManifest(). MediaTypeArtifact = "application/vnd.complypack.artifact.v1" // MediaTypeConfig is the OCI config layer media type. // Contains evaluator-id, version, and optional provenance. MediaTypeConfig = "application/vnd.complypack.config.v1+json" // MediaTypeContent is the OCI content layer media type. // Contains opaque policy content (e.g., OPA bundle tarball). MediaTypeContent = "application/vnd.complypack.content.v1.tar+gzip" )
const ( // MaxContentSize is the maximum allowed content size (100MB). // Prevents memory exhaustion attacks via unbounded content. MaxContentSize = 100 * 1024 * 1024 )
Variables ¶
var ( // ErrInvalidConfig is returned when the Config has missing or invalid required fields. ErrInvalidConfig = errors.New("complypack: invalid config") // ErrEmptyContent is returned when the content reader provides zero bytes. ErrEmptyContent = errors.New("complypack: content must not be empty") // ErrContentTooLarge is returned when content exceeds maximum size. ErrContentTooLarge = errors.New("complypack: content exceeds maximum size") // ErrVerificationFailed is returned when signature verification fails. ErrVerificationFailed = errors.New("complypack: signature verification failed") // ErrSigningFailed is returned when signing fails. ErrSigningFailed = errors.New("complypack: signing failed") // ErrInvalidMediaType is returned when an OCI layer has an unexpected media type. ErrInvalidMediaType = errors.New("complypack: invalid media type") // ErrNoContentLayer is returned when unpacking finds no content layer. ErrNoContentLayer = errors.New("complypack: no content layer found") )
Functions ¶
func Pack ¶
func Pack(ctx context.Context, store content.Storage, cfg Config, content io.Reader, opts ...PackOption) (ocispec.Descriptor, error)
Pack assembles a ComplyPack OCI artifact from config and opaque content. The content is stored as a single layer with MediaTypeContent. The config is stored with MediaTypeConfig.
Memory Usage: Pack loads the entire content into memory for digest calculation. Content size is limited to MaxContentSize (100MB) to prevent memory exhaustion. Returns ErrContentTooLarge if content exceeds this limit.
Options:
- WithSigning(keyPath) enables keyed signing
- WithKeylessSigning(identity, issuer) enables OIDC-based keyless signing
- WithAnnotations(map) adds OCI manifest annotations
Returns the OCI manifest descriptor pointing to the packed artifact.
Types ¶
type ComplyPack ¶
type ComplyPack struct {
// Config contains the evaluator-id, version, and optional provenance.
Config Config
// Content is the opaque policy content (e.g., OPA bundle tarball).
// Caller must Close() when done.
Content io.ReadCloser
}
ComplyPack is an unpacked ComplyPack artifact with its config and content.
func Unpack ¶
func Unpack(ctx context.Context, store content.ReadOnlyStorage, desc ocispec.Descriptor, opts ...UnpackOption) (*ComplyPack, error)
Unpack extracts a ComplyPack's config and content from an OCI store. The descriptor must point to an OCI manifest with a ComplyPack config layer.
IMPORTANT: The returned ComplyPack.Content is an io.ReadCloser that MUST be closed by the caller to avoid resource leaks:
result, err := complypack.Unpack(ctx, store, desc)
if err != nil { return err }
defer result.Content.Close() // Required!
Options:
- WithVerification(keyPath) enables keyed signature verification
- WithKeylessVerification(cert, issuer, identity) enables OIDC-based verification
Returns ComplyPack with config and content reader. Caller must close Content.
type Config ¶
type Config struct {
// ID is the globally unique pack identifier using reverse-domain convention
// (e.g., "io.complytime.my-controls", "com.acme.appsec").
// Required. Survives registry moves and distinguishes packs from different
// authors that target the same evaluator.
ID string `json:"id"`
// EvaluatorID identifies the provider plugin that evaluates this pack's
// content (e.g., "opa"). Must match the provider's registered ID.
// Required. Used by complyctl to dispatch content to the correct provider.
EvaluatorID string `json:"evaluator-id"`
// Version is the ComplyPack artifact version.
// Required. Semantic versioning recommended.
Version string `json:"version"`
// Source links this ComplyPack to the Gemara content it implements.
// Optional. Nil for standalone policies.
Source *Provenance `json:"source,omitempty"`
}
Config is the ComplyPack OCI artifact configuration. Embedded in the OCI config layer so consumers can identify the pack and route it to the correct provider without inspecting the content.
type PackOption ¶
type PackOption func(*packOptions)
PackOption configures optional Pack behavior.
func WithAnnotations ¶
func WithAnnotations(annotations map[string]string) PackOption
WithAnnotations adds OCI manifest annotations. Common annotations: org.opencontainers.image.created, org.opencontainers.image.authors
func WithKeylessSigning ¶
func WithKeylessSigning(identity, issuer string) PackOption
WithKeylessSigning enables keyless signing via OIDC identity and issuer. Requires OIDC token in environment (e.g., GitHub Actions, GitLab CI). Mutually exclusive with WithSigning.
func WithSigning ¶
func WithSigning(keyPath string) PackOption
WithSigning enables keyed signing with the private key at keyPath. Mutually exclusive with WithKeylessSigning.
type Provenance ¶
type Provenance struct {
// GemaraContent is the URI or hash of the Gemara catalog.
// Examples: "oci://registry/gemara/controls:latest", "sha256:abc123..."
GemaraContent string `json:"gemara-content"`
// PolicyID identifies the policy within the Gemara catalog.
PolicyID string `json:"policy-id"`
}
Provenance links a ComplyPack to the Gemara content and policy it implements.
type UnpackOption ¶
type UnpackOption func(*unpackOptions)
UnpackOption configures optional Unpack behavior.
func WithKeylessVerification ¶
func WithKeylessVerification(certPath, issuer, identity string) UnpackOption
WithKeylessVerification enables keyless signature verification. Verifies certificate chain, Rekor inclusion, and OIDC claims. Mutually exclusive with WithVerification.
func WithVerification ¶
func WithVerification(keyPath string) UnpackOption
WithVerification enables keyed signature verification with the public key at keyPath. Mutually exclusive with WithKeylessVerification.
Source Files