constraints-registry

约束注册表

为 AI 生成的代码提供策略即代码防护措施。 一个 MCP 服务，在代码生成时向编码 Agent（Claude Code、Cursor、Codex）提供工程约束，并使用 OPA、Conftest、Checkov 和 Semgrep 验证产物。

单一、可查询的工程约束来源（涵盖基础设施、组织和架构），供编码 Agent（Claude Code、Cursor、Codex 等）在代码生成时查阅，并通过 MCP 服务提供。它本身不会强制执行约束，而是为 Agent 提供指导，并将确定性验证交由现有的执行引擎（OPA、Conftest、Checkov、Semgrep）处理。

约束在源代码仓库中编写，汇总为不可变的、带版本的捆绑包，并通过 MCP 提供服务，使 Agent 可以：

1. describe_scope — 发现有效的选择器词汇，
2. get_constraints — 获取与其构建内容相关的规则，以及
3. validate — 根据绑定的执行引擎检查候选产物。

权威要求：constraint-registry-v0-spec.md。 要求 → 组件 → 测试映射：TRACEABILITY.md。

---

目录

• 功能
• 前置条件
• 快速开始
• 运行 MCP 服务
• 与编码 Agent 集成
• 编写约束
• 热重载
• 验证工具
• 添加执行引擎
• 仓库布局
• 贡献
• 许可证

---

功能

• 三类约束 — 基础设施、组织和架构约束，包括关系型选择器（例如“禁止跨领域边界进行同步调用”）以及建议性（不强制执行的）约束。
• 多来源汇总 — 从多个源代码仓库导入；ID 按来源命名空间划分；生成确定性的、内容哈希校验的不可变版本化捆绑包。
• 优先级与防偏移 — 可配置的默认策略（强约束优先级高于较弱约束；下游来源不得放宽同一范围内优先级更高的规则）；通过夹具交叉检查，防止指导与执行规则发生偏移。
• 可插拔引擎 — 稳定的适配器接口，配有四个实际适配器：OPA 和 Conftest（Rego 策略）、Checkov（IaC 扫描）以及 Semgrep（应用程序源代码）。输出 SARIF 的引擎共用一个标准化接口（adapters/sarif/），因此接入新的 SARIF 引擎主要是完成接线配置。添加引擎 = 一个适配器 + 一行配置（参见添加执行引擎）。
• 目录导入器 — Checkov 和 Semgrep 提供导入器，可将引擎的规则目录/规则集转换为草拟约束存根（附带许可证/来源出处信息），供人工补充完善，是快速初始化来源的途径。
• MCP 服务 — 通过 stdio 或共享的 HTTP 端点提供三个工具（describe_scope、get_constraints、validate）。get_constraints 失败时默认放行，确保 Agent 不会因此受阻。
• 热重载 — 服务可定期重新导入，以便在无需重启的情况下获取约束变更。
• 验证工具 — 验证注册表和约束集在内部保持一致；输出机器可读的 JSON，失败时返回非零退出码。

---

前提条件

工具	必需？	说明
Python ≥ 3.11	是	此软件包面向 3.11 及更高版本
uv	是	管理虚拟环境并运行入口点
OPA（opa）	用于 Rego validate／fixture 交叉检查	参考策略执行引擎
Conftest（conftest）	可选	第二个 Rego 引擎；如果未安装，其检查会跳过
Checkov（checkov）	可选	IaC 扫描引擎；如果未安装，其检查会跳过
Semgrep（semgrep）	随附	源代码引擎；由 uv sync 自动安装

在 macOS 上安装外部引擎：

brew install opa conftest checkov   # semgrep is installed by `uv sync`

每个引擎都是可选且相互独立的：如果某项测试或 harness 检查所需的引擎二进制文件不在 PATH 中，该项检查会跳过，而不是失败。注册表以及 get_constraints／describe_scope 指引无需任何引擎即可使用——只有在运行 validate 和针对绑定到相应引擎的约束执行 fixture 交叉检查时，才需要引擎。

---

快速开始

git clone https://github.com/SureshKhemka/constraints-registry.git
cd constraints-registry

uv sync                      # create the venv + install deps (incl. semgrep)

uv run cregistry-harness     # run the validation harness against the bundled samples

harness 会输出机器可读的 JSON，并且任何失败都会以非零状态码退出。成功运行的输出如下：

{ "passed": true, "summary": { "pass": 21, "fail": 0, "skip": 0, "total": 21 }, "checks": [ ... ] }

（只有在未安装 conftest 这类可选引擎时才会使用 skip。）

---

运行 MCP 服务

有两种传输方式——根据工具的连接方式选择。

# stdio (default): each tool launches its own copy; nothing to manage
uv run cregistry-mcp

# one shared HTTP server every tool connects to (recommended for multiple tools)
uv run cregistry-mcp --http --port 8765 --reload-interval 60

标志：--transport {stdio,http,sse}、--http（简写）、--host（默认值 127.0.0.1）、--port（默认值 8765）、--config（或 $CREGISTRY_CONFIG）、--reload-interval SECONDS（0 = 关闭）。

管理共享 HTTP 服务：

lsof -ti tcp:8765 | xargs kill     # stop
# restart = stop + start

完整的运维指南（停止／重启、macOS launchd 自动启动、仓库同步／解耦模式）：docs/RUNNING.md。 工具输入／输出约定：docs/MCP_CONTRACT.md。

---

与编码 Agent 集成

此服务提供三个工具：describe_scope、get_constraints、validate。

Claude Code

# shared HTTP server (start it first, see above), available in every project:
claude mcp add --scope user --transport http constraint-registry http://127.0.0.1:8765/mcp

# OR stdio (no separate server to run; Claude launches it):
claude mcp add constraint-registry -- uv run --directory "$(pwd)" cregistry-mcp

claude mcp list   # should show: constraint-registry ... ✔ Connected

Cursor（~/.cursor/mcp.json）

{ "mcpServers": { "constraint-registry": { "url": "http://127.0.0.1:8765/mcp" } } }

Codex／其他仅支持 stdio 的工具

将 MCP 服务配置为 command: uv、args: ["run","--directory","/abs/path/to/repo","cregistry-mcp"]。

让 Agent 真正查询它

Agent 会自动发现这些工具，但如果要让它们在生成代码之前查询注册表，请在项目中（或 ~/.claude/CLAUDE.md）添加一条指令：

在编写 AWS／基础设施代码之前，调用 constraint-registry MCP：先调用 describe_scope 了解有效的选择器值，再使用正确的作用域调用 get_constraints，并将每项 hard 约束 作为不可协商的下游门禁予以遵守。也可以选择调用 validate 验证结果。

---

编写约束

源是一个包含 constraints/*.yaml（每个文件一个约束）的目录，也可以选择包含 policies/（引擎策略）和 fixtures/（示例产物）。在 registry.config.yaml 中注册源和引擎：

sources:
  - { name: platform-security, path: sources/platform-security, precedence: 100 }
  - { name: data-platform,     path: sources/data-platform,     precedence: 50  }
engines:
  - { name: opa,      adapter: "cregistry.engine.adapters.opa:OpaAdapter" }
  - { name: conftest, adapter: "cregistry.engine.adapters.conftest:ConftestAdapter" }
  - { name: checkov,  adapter: "cregistry.engine.adapters.checkov:CheckovAdapter", options: { min_level: warning } }
  - { name: semgrep,  adapter: "cregistry.engine.adapters.semgrep:SemgrepAdapter", options: { min_level: warning } }
precedence_policy: default

约束示例（参见 sources/platform-security/constraints/aws-s3-no-public-access.yaml）：

id: aws.s3.no-public-access
title: "S3 buckets must not be publicly accessible"
intent: "Public buckets are the top source of data-exposure incidents."
category: infrastructure          # infrastructure | organizational | architectural
scope:
  providers: [aws]
  resource_types: [aws_s3_bucket] # Terraform resource ids (NOT "s3_bucket")
  environments: [all]
  repos: ["tag:data-plane"]
severity: hard                    # hard | soft | advisory
enforcement:                      # omit for an advisory (guidance-only) constraint
  - { engine: opa, policy: policies/s3_public.rego }
guidance:
  do:   ["Attach an aws_s3_bucket_public_access_block with all four flags true"]
  dont: ["Never set acl = 'public-read' or 'public-read-write'"]
  example_compliant: |
    {"resources": {"aws_s3_bucket": {"data": {"acl": "private", "public_access_block": true}}}}
owner: platform-security
version: 1.0.0
fixtures:                         # optional; cross-checked against the engine
  pass: fixtures/s3_private.json
  fail: fixtures/s3_public.json

作用域说明（查询时很重要）：

• resource_types 使用目标工具的标识符（Terraform：aws_s3_bucket）。 调用 describe_scope 可发现其中的准确词汇。
• 查询省略某个维度时，会进行宽泛匹配；值与约束的选择器矛盾时，则会排除该约束。关系作用域约束只会在查询提供匹配关系时返回。
• 编写完成后，运行 uv run cregistry-harness 验证架构、优先级和 fixtures。

---

热重载（约束变更时无需重启）

使用 --reload-interval N 运行服务，它会每隔 N 秒从磁盘重新导入，并在内容发生变化时发布新的不可变捆绑包：

uv run cregistry-mcp --http --port 8765 --reload-interval 60

• 内容未变化时不会执行任何操作；之前的捆绑包版本仍可按 ID 固定使用。
• 重新导入失败时（例如，优先级冲突无法解决），会继续提供上一个正常版本的捆绑包，并记录原因——服务不会中断。
• 服务会从配置的源路径读取内容，因此请将团队的约束仓库配置为同步或拉取到这些路径（通过单独的运维任务，例如 cron git pull 或 CI 发布）。代码或依赖项变更仍需重启。

---

验证测试套件

uv run cregistry-harness 会使用捆绑的独立示例源进行端到端测试，验证：架构符合性、确定性导入、错误约束隔离、命名空间与优先级、版本控制与弃用、引擎接口符合性（包括可供任何适配器运行的可复用测试套件）、测试夹具交叉检查／绑定错误检测、MCP 契约／范围限定／故障开放，以及热重载行为。它会输出结构化 JSON，并在任何测试失败时返回非零退出码，适用于 CI。

uv run cregistry-harness            # human-readable JSON to stdout, exit 0/1
uv run cregistry-harness --config path/to/registry.config.yaml

---

添加执行引擎

在 src/cregistry/engine/adapters/ 下的新模块中实现 EngineAdapter 接口，在 registry.config.yaml 的 engines: 下添加一行配置，并使用现有符合性测试套件对其进行验证——无需更改架构、导入器、MCP 服务或测试套件。完整指南： docs/ADDING_AN_ENGINE.md。

---

仓库结构

src/cregistry/
  model.py            constraint schema (Pydantic)
  loader.py           load + per-field schema validation
  config.py           registry config (sources, engines)
  importer.py         import → aggregate → bundle
  precedence.py       namespacing precedence / conflict resolution
  scope.py            scope matching (query + conflict)
  bundle.py store.py  immutable versioned bundles + store
  query.py validate.py  scoped queries + artifact validation
  integrity.py        fixture cross-check / anti-drift
  service.py          transport-independent service (+ hot reload)
  mcp_server.py       MCP server (stdio / http) + CLI
  engine/             stable engine interface, registry, and adapters:
    adapters/opa, adapters/conftest, adapters/checkov, adapters/semgrep
    adapters/sarif    shared SARIF normalization seam (used by checkov + semgrep)
  harness/            the validation harness (checks/*)
sources/              bundled sample source repos (constraints, policies, fixtures)
scenarios/            self-contained fixtures for harness edge cases
tests/                pytest suite: adapter conformance, fixtures, import, e2e
docs/                 RUNNING.md, MCP_CONTRACT.md, ADDING_AN_ENGINE.md
deploy/               launchd template for auto-starting the HTTP server
CONTRACTS.md          the frozen engine-adapter seam new adapters code against

直接使用 uv run pytest 运行适配器测试套件。

---

贡献

我们非常欢迎各种贡献——错误报告、新的引擎适配器、约束源和文档。添加引擎的流程刻意设计得十分精简：只需一个适配器模块和一行配置，无需更改架构、导入器、MCP 服务或测试套件。

• 阅读 CONTRIBUTING.md，了解开发环境设置、约定和引擎适配器检查清单。
• 请友善待人——参阅 行为准则。
• 发现漏洞？请按照 SECURITY.md 中的说明私下报告。

提交 PR 前，请确保 uv run pytest 和 uv run cregistry-harness 均通过；CI 会在每个拉取请求中运行这两项测试。

---

许可证

本项目根据 Apache License 2.0 授权。有关致谢以及本项目集成的外部引擎所采用的许可证，请参阅 NOTICE。