{
  "markdown": "# ComplyPack\n\n[![CI](https://github.com/complytime/complypack/actions/workflows/ci.yml/badge.svg)](https://github.com/complytime/complypack/actions/workflows/ci.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/complytime/complypack.svg)](https://pkg.go.dev/github.com/complytime/complypack)\n[![Go Report Card](https://goreportcard.com/badge/github.com/complytime/complypack)](https://goreportcard.com/report/github.com/complytime/complypack)\n\nComplyPack 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.\n\n## Features\n\n- **OCI Artifact Packaging** - Pack policy content into OCI Image Manifest v1.1 artifacts\n- **MCP Server** - Expose Gemara catalogs, platform schemas, and evaluators to LLMs\n- **Policy Graph Resolution** - Resolve effective policies with overlays from Gemara bundles\n- **Evaluator-Agnostic** - Supports any policy language (OPA, CEL, etc.) via evaluator-id dispatch\n- **CUE Schema Sources** - Load platform schemas from CUE registry, HTTPS, or local files\n\n## Installation\n\n### Fedora / RPM\n\nDownload the `.rpm` from [GitHub Releases](https://github.com/complytime/complypack/releases), then:\n\n```bash\nsudo dnf install ./complypack_*.rpm\n```\n\n### Binary releases\n\nDownload a pre-built binary from [GitHub Releases](https://github.com/complytime/complypack/releases).\n\n### From source\n\n```bash\ngo install github.com/complytime/complypack/cmd/complypack@latest\n```\n\n### Library\n\n```bash\ngo get github.com/complytime/complypack\n```\n\n## Configuration\n\nCreate `complypack.yaml` in your working directory:\n\n```yaml\n# Globally unique pack identifier (reverse-domain convention).\n# Survives registry moves, distinguishes packs from different authors.\nid: io.complytime.my-controls\n\n# Provider plugin that evaluates this pack's content.\n# Must match the provider's binary suffix (e.g., \"opa\" → complyctl-provider-opa).\nevaluator-id: opa\n\n# ComplyPack artifact version\nversion: 0.1.0\n\n# Gemara policy sources. Drive the MCP server's policy tools and, when\n# packing, the source provenance recorded in the published artifact.\ngemara:\n  sources:\n    - source: oci://ghcr.io/org/controls:v1\n\n# Platform schemas (for MCP server validation tools)\n# Built-in platforms: ci-github-actions, ci-gitlab, ci-azure-pipelines,\n# kubernetes-deployment, kubernetes-pod, etc. (see schemas/index.yaml)\nschemas:\n  - platform: kubernetes-deployment\n  - platform: ci-github-actions\n```\n\nConfiguration files are validated against a [JSON Schema](schemas/jsonschema/complypack.schema.json). 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. Use `complypack config validate` to check your config before running any command.\n\nSee `complypack.example.yaml` for full configuration options.\n\n### Authentication\n\nUses the Docker credential chain:\n\n```bash\ndocker login ghcr.io\n```\n\n## CLI Usage\n\n### Initialize configuration\n\nGenerate a `complypack.yaml` configuration file:\n\n```bash\n# Interactive — prompts for platforms and sources\ncomplypack init\n\n# From flags — no prompts\ncomplypack init \\\n  --schema kubernetes-deployment \\\n  --schema ci-github-actions \\\n  --source oci://ghcr.io/org/catalog:latest \\\n  --evaluator-id opa \\\n  --id io.complytime.my-pack \\\n  --version 0.1.0 \\\n  --strict\n```\n\nInteractive mode requires a terminal. It prompts for pack identity (ID,\nversion, evaluator), platform schemas via a filterable multi-select, and\na Gemara source URI. If the output file already exists, a confirmation\nprompt appears. If the output path's parent directory does not exist, a\nconfirmation prompt offers to create it. For non-interactive use (CI,\nscripts), provide `--schema` and `--source` flags.\n\n**Flags:**\n- `--schema`        Platform schema to include (repeatable)\n- `--source`        Gemara source to include (repeatable)\n- `--id`            Pack identifier in reverse-domain notation\n- `--evaluator-id`  Policy evaluator plugin ID (default: `opa`)\n- `--version`       Pack version in semver format (default: `0.1.0`)\n- `--force`         Overwrite existing config file without prompting\n- `--output`, `-o`  Output file path (default: `complypack.yaml`). If the path is a directory (trailing `/` or existing directory), the default filename is appended\n- `--parents`, `-p` Create parent directories for the output path if they do not exist\n- `--strict`              Treat unknown config fields as errors\n- `--allow-credentials`  Allow source URIs with embedded credentials (not recommended)\n\n### Validate configuration\n\nValidate a `complypack.yaml` file against the JSON Schema, structural rules, and scope-specific requirements:\n\n```bash\n# Validate in current directory (all scopes)\ncomplypack config validate\n\n# Validate a specific file\ncomplypack config validate path/to/complypack.yaml\n\n# Treat unknown fields as errors\ncomplypack config validate --unknown-fields=error\n\n# Validate for a specific operation\ncomplypack config validate --scope pack\ncomplypack config validate --scope serve\ncomplypack config validate --scope pack --scope serve\n```\n\n**Flags:**\n- `--unknown-fields`  How to handle unknown config fields: `warn` (default) or `error`\n- `--scope`           Validation scope: `pack`, `serve`, `init`, or `all` (default: `all`, repeatable)\n\n### Pack\n\nPack a directory of policy content into a ComplyPack OCI artifact and push to a registry:\n\n```bash\n# Pack and push to a registry\ncomplypack pack policy/ ghcr.io/org/my-policies:v1.0.0\n\n# Pack to a local registry\ncomplypack pack policy/ localhost:5001/test:latest --plain-http\n```\n\nThe command reads `evaluator-id`, `version`, and `gemara.sources` from `complypack.yaml`. The content directory is tar+gzipped and stored as the artifact's opaque content layer.\n\nIf `complypack.yaml` declares `gemara.sources`, `pack` also resolves those sources and records their policy provenance in the artifact's config blob (see [Source Provenance](#source-provenance)). Source resolution fails closed: an unresolvable source aborts the pack, and resolution is bounded by a 5-minute timeout.\n\nFlags:\n\n- `--cache-dir`  Cache directory for resolved Gemara sources (default: `$XDG_CACHE_HOME/complypack` or `$HOME/.cache/complypack`). Set this when running in a restricted or headless environment where `HOME` is unset.\n- `--plain-http` Use plain HTTP instead of HTTPS for the target registry\n\n### Validate a policy\n\nValidate a policy file for syntax, contract compliance, and lint:\n\n```bash\n# Validate against a platform schema\ncomplypack validate-policy policy.rego --platform kubernetes-deployment\n\n# JSON output for CI pipelines\ncomplypack validate-policy policy.rego --platform kubernetes-deployment --format json\n```\n\nPerforms three checks in sequence: syntax validation, contract validation (all `input.*` references exist in the schema), and linting. Contract and lint checks are skipped when syntax errors exist. Lint warnings are non-fatal.\n\n**Flags:**\n- `--platform`  Platform schema to validate against (required)\n- `--schema`    Override schema source (format: `platform=uri`, repeatable)\n- `--format`    Output format: `human` (default), `text`, or `json`\n\n**Exit codes:** `0` valid, `1` invalid.\n\n### Test a policy\n\nRun a policy file's test suite with optional test-data schema validation:\n\n```bash\n# Run tests\ncomplypack test-policy policy.rego --platform kubernetes-deployment\n\n# With test-data validation\ncomplypack test-policy policy.rego --platform kubernetes-deployment --test-data fixtures.json\n\n# JSON output\ncomplypack test-policy policy.rego --platform kubernetes-deployment --format json\n```\n\nWhen `--test-data` is provided, the JSON file is first validated against the platform's CUE schema. If validation fails, tests are not executed.\n\n**Flags:**\n- `--platform`   Platform schema to use (required)\n- `--test-data`  Test data JSON file to validate before running tests\n- `--schema`     Override schema source (format: `platform=uri`, repeatable)\n- `--format`     Output format: `human` (default), `text`, or `json`\n\n**Exit codes:** `0` all tests pass, `1` tests failed or test data invalid.\n\n### MCP Server\n\nStart the MCP server to expose Gemara catalogs, platform schemas, and policy tools to LLMs:\n\n```bash\ncomplypack mcp serve\ncomplypack mcp serve --config /path/to/complypack.yaml\n```\n\n#### MCP Resources\n\n| Resource                         | Description                 |\n|----------------------------------|-----------------------------|\n| `complypack://catalog/<name>`    | Gemara catalog (YAML)       |\n| `complypack://schema/<platform>` | Platform schema (JSON)      |\n| `complypack://evaluator`         | Available policy evaluators |\n\n#### MCP Tools\n\n| Tool                           | Description                                               |\n|--------------------------------|-----------------------------------------------------------|\n| `validate_policy`              | Validate policy syntax, contract compliance, and linting  |\n| `test_policy`                  | Run policy against test data with schema validation       |\n| `get_assessment_requirements`  | Extract assessment requirements with parameters           |\n| `get_applicability_groups`     | Get group definitions and requirement memberships         |\n| `get_automation_triage`        | Classify assessment plans as Automated or Manual          |\n| `analyze_parameter_delta`      | Compare L3 parameter values against L1/L2 requirements    |\n| `validate_config`              | Validate complypack.yaml with scope-aware checks          |\n\n#### Tested AI Coding Tools\n\nThe MCP server and skills have been tested with:\n\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n- [OpenCode](https://opencode.ai)\n\n### Version\n\n```bash\ncomplypack version\ncomplypack version --json\n```\n\n### AI Tool Setup\n\nComplyPack is available as a plugin for Claude Code, Gemini CLI, and OpenCode.\nCursor is also supported via MCP server configuration.\nSee [INSTALL.md](INSTALL.md) for setup instructions.\n\n### Shell Completion\n\nGenerate shell completion scripts for tab-completion of commands and flags:\n\n```bash\n# Bash\ncomplypack completion bash > /etc/bash_completion.d/complypack\n\n# Zsh\ncomplypack completion zsh > \"${fpath[1]}/_complypack\"\n\n# Fish\ncomplypack completion fish > ~/.config/fish/completions/complypack.fish\n\n# PowerShell\ncomplypack completion powershell > complypack.ps1\n```\n\nRun `complypack completion --help` for detailed instructions per shell.\n\n## Architecture\n\n### ComplyPack OCI Artifact\n\n```json\n{\n  \"artifactType\": \"application/vnd.complypack.artifact.v1\",\n  \"config\": { \"mediaType\": \"application/vnd.complypack.config.v1+json\" },\n  \"layers\": [{ \"mediaType\": \"application/vnd.complypack.content.v1.tar+gzip\" }]\n}\n```\n\n| Purpose       | Media Type                                       |\n|---------------|--------------------------------------------------|\n| Artifact Type | `application/vnd.complypack.artifact.v1`         |\n| Config Layer  | `application/vnd.complypack.config.v1+json`      |\n| Content Layer | `application/vnd.complypack.content.v1.tar+gzip` |\n\nThe 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.\n\n#### Source Provenance\n\nWhen a pack is built from `gemara.sources`, `complypack pack` resolves those sources and records which Gemara policies the pack implements in the config blob under `source`:\n\n```json\n{\n  \"source\": [\n    {\n      \"policy-id\": \"container-platform-policy\",\n      \"gemara-content\": [\n        { \"reference-id\": \"container-security-controls\", \"uri\": \"https://example.com/catalog\", \"version\": \"1.0.0\" },\n        { \"reference-id\": \"container-security-guidance\", \"version\": \"1.0.0\" }\n      ]\n    }\n  ]\n}\n```\n\n- One entry per resolved policy (`policy-id`); `gemara-content` lists the catalog and guidance references that policy imports.\n- `uri` is sanitized before it is recorded into the published blob: userinfo, query strings, and fragments are stripped, and local/`file://` paths are omitted (the `reference-id` and `version` are still recorded). This keeps internal paths and embedded credentials out of a publicly distributable artifact.\n- `source` is omitted entirely when a pack declares no `gemara.sources` or its sources resolve to no policy. Unresolvable sources fail the pack.\n\n### Policy Graph Resolution\n\nThe MCP server resolves Gemara policy graphs:\n\n1. Load OCI bundle or local file\n2. `bundle.Classify()` — identify artifact types (Policy, ControlCatalog, etc.)\n3. `ResolveEffectivePolicy()` — apply overlays from policy imports\n4. Extract assessment requirements with structured parameters from assessment plans\n\n## Library Quick Start\n\n### Packing\n\n```go\ncfg := complypack.Config{\n    ID:          \"io.example.my-policies\",\n    EvaluatorID: \"opa\",\n    Version:     \"1.0.0\",\n}\n\ncontent := strings.NewReader(\"policy content here\")\ndesc, err := complypack.Pack(ctx, store, cfg, content)\n```\n\n### Unpacking\n\n```go\nresult, err := complypack.Unpack(ctx, store, desc)\ndefer result.Content.Close()\n\nfmt.Printf(\"Evaluator: %s\\n\", result.Config.EvaluatorID)\n```\n\n## Error Handling\n\nComplyPack uses sentinel errors:\n\n- `ErrInvalidConfig` — Config validation failed\n- `ErrEmptyContent` — Content reader returned zero bytes\n- `ErrContentTooLarge` — Content exceeds 100MB limit\n- `ErrInvalidMediaType` — Unexpected media type in manifest\n- `ErrNoContentLayer` — Manifest missing content layer\n\n## Signing & Verification\n\nComplyPack is a pure pack/unpack library and does not handle trust decisions. Sign artifacts with [cosign](https://docs.sigstore.dev/cosign/signing/overview/) after pushing to a registry:\n\n```bash\ncomplypack pack policy/ ghcr.io/org/my-policies:v1.0.0\ncosign sign ghcr.io/org/my-policies:v1.0.0\n```\n\nVerification is handled on the consumer side by [complyctl](https://github.com/complytime/complyctl).\n\n## Current Limitations\n\n- **Content Size**: Maximum 100MB per artifact\n- **Single Content Layer**: Only one content layer per artifact is supported\n- **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](docs/adr/018-schema-file-layout.md))\n\n## Related Projects\n\n- [ComplyTime](https://github.com/complytime) — Compliance automation\n- [Gemara](https://github.com/gemaraproj/gemara) — Compliance policy framework\n- [ORAS](https://oras.land/) — OCI Registry as Storage\n- [Open Policy Agent](https://www.openpolicyagent.org/) — Policy-based control\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.\n",
  "bytes": 14822,
  "sha": "fe1767fe76946bd3ff1090494b530131f51fe116fde861dcaedcf2524998499b",
  "repo_slug": "complytime/complypack",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_complytime_complypack_0c40988b/readme"
}