内容
# Custos
**Custos** 是一款用于 AI 代理的安全编码助手 —— 一种 MCP 服务器，可以在代理编写代码时提供官方安全指导，确保指导得到落实，并将结果转化为审计证据。
## Guide → Enforce → Prove
**Guide** —— 官方安全编码指导，在上下文中，实时提供。
MCP 工具涵盖整个 MITRE CWE 目录（944 个弱点，附官方缓解措施和易受攻击/已修复的代码示例）、NIST 800-53 Rev 5、OWASP ASVS 5.0、NIST SSDF、ISO 27001/27017 和 NIST 云指导。`controls_for_change` 将 *"添加密码重置"* 转换为确切的控制措施和缓解措施，然后再编写一行代码；`cwe_lookup` 将任何扫描器发现转换为修复指导。所有文本均直接来自官方出版物 —— 没有 AI 生成的内容，运行时无需网络。
**Enforce** —— 指导必须落实到代码中。
预编辑提示（Claude Code 钩子）在进行安全相关编辑时立即显示相关控制措施和 CWE 缓解措施，而预提交/CI 门控阻止对安全敏感代码的提交，如果没有引用收据（`// Refs: NIST IA-5(1)` 内联或在提交消息中）。编辑时提供建议，提交时强制执行，在 CI 中不可绕过（`--strict`）。
**Prove** —— 输出审计证据。
`custos-evidence` 遍历仓库，收集每条引用，解析 NIST → ISO 27001 附录 A，通过官方 NIST OLIR 映射，并生成带有文件:行指针的 `COMPLIANCE.md` 证据索引。
## 安装
需要 [Bun](https://bun.sh)。
```bash
bun add -g mcp-custos # 或：npm install -g mcp-custos
```
**Claude Code**
```bash
claude mcp add custos -- mcp-custos
```
**任何其他 MCP 客户端**（Claude Desktop, Cursor, …）—— 添加到其 MCP 配置：
```json
{ "mcpServers": { "custos": { "command": "mcp-custos" } } }
```
预编辑提示特定于 Claude Code；工具、提交门控、CI 检查和证据生成器适用于任何代理（或没有）。
## 项目设置（可选钩子和服务器注册）
两种安装方式，一条命令即可：
**团队（推荐）** —— 作为开发依赖项添加，以便队友可以通过 `pnpm install` 获取，锁定文件可确保所有人使用相同的版本：
```bash
pnpm add -D mcp-custos # 或 npm i -D / yarn add -D / bun add -d
pnpm exec custos-init .
```
**个人/全局** —— 在全局安装软件包：
```bash
custos-init /path/to/your/project # --skip-hooks=husky,ci 跳过层
```
`custos-init` 检测安装模式（通过 `--local`/`--global` 覆盖），在项目的 `.mcp.json` 中注册 `custos` 服务器（与包管理器匹配），并复制三个可选层：`.claude/settings.json`（预编辑提示）、`.husky/pre-commit`（引用门控 —— 需要项目中的 husky）和 GitHub Actions 工作流（带有 `--strict` 的相同门控）。现有文件永远不会被覆盖。人类可以在本地执行 `git commit --no-verify`；CI 是最后的保障。
## 生成审计证据
```bash
custos-evidence /path/to/your/repo --out=COMPLIANCE.md
```
## 数据和出处
所有数据集都已捆绑（`src/data/`）并通过 `bun run update-sources` 从官方来源刷新：MITRE cwec 目录、NIST OSCAL（800-53、SSDF）、OWASP ASVS 发布 JSON、NIST OLIR 映射以及 NIST 云 SP 的逐字摘录。ISO 标准文本未随附（需付费）—— 仅包含 ID/标题，实施细节来自映射的 NIST 控制措施。唯一的项目策划（非官方）数据：CWE→ASVS/NIST 启动映射和 Top 25 叠加，标记为此类，位于数据集内。
## 开发
```bash
git clone https://github.com/an0malous/mcp-custos && cd mcp-custos
bun install
bun link # 使 mcp-custos / custos-* 命令在此 checkout 中可见
bun run typecheck && bun test
```
功能开发通过 Kiro 规格流程 —— 请参见 `CLAUDE.md`。
MIT © an0malous
