Overview

ComplyPack is a CLI and Go library for packing and unpacking OCI artifacts containing policy bundles. It provides an evaluator-agnostic format for distributing compliance policies using OCI registries, and an MCP server for LLM-assisted policy generation.

Features#

• OCI Artifact Packaging - Pack policy content into OCI Image Manifest v1.1 artifacts
• MCP Server - Expose Gemara catalogs, platform schemas, and evaluators to LLMs
• Policy Graph Resolution - Resolve effective policies with overlays from Gemara bundles
• Evaluator-Agnostic - Supports any policy language (OPA, CEL, etc.) via evaluator-id dispatch
• CUE Schema Sources - Load platform schemas from CUE registry, HTTPS, or local files

Installation#

CLI#

go install github.com/complytime/complypack/cmd/complypack@latest

Library#

go get github.com/complytime/complypack

Configuration#

Create complypack.yaml in your working directory:

## Globally Unique Pack Identifier (reverse-domain Convention).
## Survives Registry Moves, Distinguishes Packs From Different Authors.
id: io.complytime.my-controls

## Provider Plugin That Evaluates This Pack's Content.
## Must Match The Provider's Binary Suffix (e.g., "opa" ��� Complyctl-provider-opa).
evaluator-id: opa

## Complypack Artifact Version
version: 0.1.0

## Gemara Policy Source (for Mcp Server)
gemara:
  source: oci://ghcr.io/org/controls:v1

## Platform Schemas (for Mcp Server Validation Tools)
## Built-in Platforms: Ci-github-actions, Ci-gitlab, Ci-azure-pipelines,
## Kubernetes-deployment, Kubernetes-pod, Etc. (see Schemas/index.yaml)
schemas:
  - platform: kubernetes-deployment
  - platform: ci-github-actions

Configuration files are validated against a JSON Schema. The pack command uses strict validation — unknown fields cause an error. The mcp serve command uses lenient validation — unknown fields produce a warning on stderr but do not prevent startup. Run complypack init --strict to verify your config has no unrecognized fields.

See complypack.example.yaml for full configuration options.

Authentication#

Uses the Docker credential chain:

docker login ghcr.io

CLI Usage#

Initialize Configuration#

Generate a complypack.yaml configuration file:

## Interactive ��� Prompts For Platforms And Sources
complypack init

## From Flags ��� No Prompts
complypack init \
  --schema kubernetes-deployment \
  --schema ci-github-actions \
  --source oci://ghcr.io/org/catalog:latest \
  --evaluator-id opa \
  --id io.complytime.my-pack \
  --version 0.1.0 \
  --strict

Interactive mode requires a terminal. It prompts for pack identity (ID, version, evaluator), platform schemas via a filterable multi-select, and a Gemara source URI. If the output file already exists, a confirmation prompt appears. If the output path’s parent directory does not exist, a confirmation prompt offers to create it. For non-interactive use (CI, scripts), provide --schema and --source flags.

Flags:

• --schema Platform schema to include (repeatable)
• --source Gemara source to include (repeatable)
• --id Pack identifier in reverse-domain notation
• --evaluator-id Policy evaluator plugin ID (default: opa)
• --version Pack version in semver format (default: 0.1.0)
• --force Overwrite existing config file without prompting
• --output, -o Output file path (default: complypack.yaml). If the path is a directory (trailing / or existing directory), the default filename is appended
• --parents, -p Create parent directories for the output path if they do not exist
• --strict Treat unknown config fields as errors
• --allow-credentials Allow source URIs with embedded credentials (not recommended)

Pack#

Pack a directory of policy content into a ComplyPack OCI artifact and push to a registry:

## Pack And Push To A Registry
complypack pack policy/ ghcr.io/org/my-policies:v1.0.0

## Pack To A Local Registry
complypack pack policy/ localhost:5001/test:latest --plain-http

The command reads evaluator-id and version from complypack.yaml. The content directory is tar+gzipped and stored as the artifact’s opaque content layer.

Mcp Server#

Start the MCP server to expose Gemara catalogs, platform schemas, and policy tools to LLMs:

complypack mcp serve
complypack mcp serve --config /path/to/complypack.yaml

Mcp Resources#

Mcp Tools#

Tested Ai Coding Tools#

The MCP server and skills have been tested with:

• Claude Code
• OpenCode

Ai Tool Setup#

ComplyPack is available as a plugin for Claude Code, Gemini CLI, and OpenCode. Cursor is also supported via MCP server configuration. See INSTALL.md for setup instructions.

Shell Completion#

Generate shell completion scripts for tab-completion of commands and flags:

## Bash
complypack completion bash > /etc/bash_completion.d/complypack

## Zsh
complypack completion zsh > "${fpath[1]}/_complypack"

## Fish
complypack completion fish > ~/.config/fish/completions/complypack.fish

## Powershell
complypack completion powershell > complypack.ps1

Run complypack completion --help for detailed instructions per shell.

Architecture#

Complypack Oci Artifact#

{
  "artifactType": "application/vnd.complypack.artifact.v1",
  "config": { "mediaType": "application/vnd.complypack.config.v1+json" },
  "layers": [{ "mediaType": "application/vnd.complypack.content.v1.tar+gzip" }]
}

The content layer is opaque — the evaluator-id in the config tells consumers which provider handles it. For OPA, this is a tarball of .rego files.

Policy Graph Resolution#

The MCP server resolves Gemara policy graphs:

1. Load OCI bundle or local file
2. bundle.Classify() — identify artifact types (Policy, ControlCatalog, etc.)
3. ResolveEffectivePolicy() — apply overlays from policy imports
4. Extract assessment requirements with structured parameters from assessment plans

Library Quick Start#

Packing#

cfg := complypack.Config{
    ID:          "io.example.my-policies",
    EvaluatorID: "opa",
    Version:     "1.0.0",
}

content := strings.NewReader("policy content here")
desc, err := complypack.Pack(ctx, store, cfg, content)

Unpacking#

result, err := complypack.Unpack(ctx, store, desc)
defer result.Content.Close()

fmt.Printf("Evaluator: %s\n", result.Config.EvaluatorID)

Error Handling#

ComplyPack uses sentinel errors:

• ErrInvalidConfig — Config validation failed
• ErrEmptyContent — Content reader returned zero bytes
• ErrContentTooLarge — Content exceeds 100MB limit
• ErrInvalidMediaType — Unexpected media type in manifest
• ErrNoContentLayer — Manifest missing content layer

Signing & Verification#

ComplyPack is a pure pack/unpack library and does not handle trust decisions. Sign artifacts with cosign after pushing to a registry:

complypack pack policy/ ghcr.io/org/my-policies:v1.0.0
cosign sign ghcr.io/org/my-policies:v1.0.0

Verification is handled on the consumer side by complyctl.

Current Limitations#

• Content Size: Maximum 100MB per artifact
• Single Content Layer: Only one content layer per artifact is supported
• Windows Symlinks: The schemas/json-schema/ directory contains a symlink for editor discoverability. Windows users cloning the repo need git config core.symlinks true (see ADR-018)

Related Projects#

• ComplyTime — Compliance automation
• Gemara — Compliance policy framework
• ORAS — OCI Registry as Storage
• Open Policy Agent — Policy-based control

License#

Apache License 2.0 — see LICENSE for details.