comply
Gemara compliance pipeline and policy generation via MCP server
Open source Open in the app JSON README (API)
About
Gemara compliance pipeline and policy generation via MCP server
Details
- Kind
- Plugins
- Topic
- Security & identity
- Publisher
- complytime
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 1
- Forks
- 9
- Open pull requests
- 2
- Last push
- 2026-09-04T13:51:07Z
- Repository state
- ativo
- Language
- Go
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
complytime/complypack
README
# ComplyPack
[](https://github.com/complytime/complypack/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/complytime/complypack)
[](https://goreportcard.com/report/github.com/complytime/complypack)
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
### Fedora / RPM
Download the `.rpm` from [GitHub Releases](https://github.com/complytime/complypack/releases), then:
```bash
sudo dnf install ./complypack_*.rpm
```
### Binary releases
Download a pre-built binary from [GitHub Releases](https://github.com/complytime/complypack/releases).
### From source
```bash
go install github.com/complytime/complypack/cmd/complypack@latest
```
### Library
```bash
go get github.com/complytime/complypack
```
## Configuration
Create `complypack.yaml` in your working directory:
```yaml
# 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 sources. Drive the MCP server's policy tools and, when
# packing, the source provenance recorded in the published artifact.
gemara:
sources:
- 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](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.
See `complypack.example.yaml` for full configuration options.
### Authentication
Uses the Docker credential chain:
```bash
docker login ghcr.io
```
## CLI Usage
### Initialize configuration
Generate a `complypack.yaml` configuration file:
```bash
# 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)
### Validate configuration
Validate a `complypack.yaml` file against the JSON Schema, structural rules, and scope-specific requirements:
```bash
# Validate in current directory (all scopes)
complypack config validate
# Validate a specific file
complypack config validate path/to/complypack.yaml
# Treat unknown fields as errors
complypack config validate --unknown-fields=error
# Validate for a specific operation
complypack config validate --scope pack
complypack config validate --scope serve
complypack config validate --scope pack --scope serve
```
**Flags:**
- `--unknown-fields` How to handle unknown config fields: `warn` (default) or `error`
- `--scope` Validation scope: `pack`, `serve`, `init`, or `all` (default: `all`, repeatable)
### Pack
Pack a directory of policy content into a ComplyPack OCI artifact and push to a registry:
```bash
# 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`, `version`, and `gemara.sources` from `complypack.yaml`. The content directory is tar+gzipped and stored as the artifact's opaque content layer.
If `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.
Flags:
- `--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.
- `--plain-http` Use plain HTTP instead of HTTPS for the target registry
### Validate a policy
Validate a policy file for syntax, contract compliance, and lint:
```bash
# Validate against a platform schema
complypack validate-policy policy.rego --platform kubernetes-deployment
# JSON output for CI pipelines
complypack validate-policy policy.rego --platform kubernetes-deployment --format json
```
Performs 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.
**Flags:**
- `--platform` Platform schema to validate against (required)
- `--schema` Override schema source (format: `platform=uri`, repeatable)
- `--format` Output format: `human` (default), `text`, or `json`
**Exit codes:** `0` valid, `1` invalid.
### Test a policy
Run a policy file's test suite with optional test-data schema validation:
```bash
# Run tests
complypack test-policy policy.rego --platform kubernetes-deployment
# With test-data validation
complypack test-policy policy.rego --platform kubernetes-deployment --test-data fixtures.json
# JSON output
complypack test-policy policy.rego --platform kubernetes-deployment --format json
```
When `--test-data` is provided, the JSON file is first validated against the platform's CUE schema. If validation fails, tests are not executed.
**Flags:**
- `--platform` Platform schema to use (required)
- `--test-data` Test data JSON file to validate before running tests
- `--schema` Override schema source (format: `platform=uri`, repeatable)
- `--format` Output format: `human` (default), `text`, or `json`
**Exit codes:** `0` all tests pass, `1` tests failed or test data invalid.
### MCP Server
Start the MCP server to expose Gemara catalogs, platform schemas, and policy tools to LLMs:
```bash
complypack mcp serve
complypack mcp serve --config /path/to/complypack.yaml
```
#### MCP Resources
| Resource | Description |
|----------------------------------|-----------------------------|
| `complypack://catalog/<name>` | Gemara catalog (YAML) |
| `complypack://schema/<platform>` | Platform schema (JSON) |
| `complypack://evaluator` | Available policy evaluators |
#### MCP Tools
| Tool | Description |
|--------------------------------|-----------------------------------------------------------|
| `validate_policy` | Validate policy syntax, contract compliance, and linting |
| `test_policy` | Run policy against test data with schema validation |
| `get_assessment_requirements` | Extract assessment requirements with parameters |
| `get_applicability_groups` | Get group definitions and requirement memberships |
| `get_automation_triage` | Classify assessment plans as Automated or Manual |
| `analyze_parameter_delta` | Compare L3 parameter values against L1/L2 requirements |
| `validate_config` | Validate complypack.yaml with scope-aware checks |
#### Tested AI Coding Tools
The MCP server and skills have been tested with:
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- [OpenCode](https://opencode.ai)
### Version
```bash
complypack version
complypack version --json
```
### 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](INSTALL.md) for setup instructions.
### Shell Completion
Generate shell completion scripts for tab-completion of commands and flags:
```bash
# 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
```json
{
"artifactType": "application/vnd.complypack.artifact.v1",
"config": { "mediaType": "application/vnd.complypack.config.v1+json" },
"layers": [{ "mediaType": "application/vnd.complypack.content.v1.tar+gzip" }]
}
```
| Purpose | Media Type |
|---------------|--------------------------------------------------|
| Artifact Type | `application/vnd.complypack.artifact.v1` |
| Config Layer | `application/vnd.complypack.config.v1+json` |
| Content Layer | `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.
#### Source Provenance
When 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`:
```json
{
"source": [
{
"policy-id": "container-platform-policy",
"gemara-content": [
{ "reference-id": "container-security-controls", "uri": "https://example.com/catalog", "version": "1.0.0" },
{ "reference-id": "container-security-guidance", "version": "1.0.0" }
]
}
]
}
```
- One entry per resolved policy (`policy-id`); `gemara-content` lists the catalog and guidance references that policy imports.
- `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.
- `source` is omitted entirely when a pack declares no `gemara.sources` or its sources resolve to no policy. Unresolvable sources fail the pack.
### 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
```go
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
```go
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](https://docs.sigstore.dev/cosign/signing/overview/) after pushing to a registry:
```bash
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](https://github.com/complytime/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](docs/adr/018-schema-file-layout.md))
## Related Projects
- [ComplyTime](https://github.com/complytime) — Compliance automation
- [Gemara](https://github.com/gemaraproj/gemara) — Compliance policy framework
- [ORAS](https://oras.land/) — OCI Registry as Storage
- [Open Policy Agent](https://www.openpolicyagent.org/) — Policy-based control
## License
Apache License 2.0 — see [LICENSE](LICENSE) for details.