内容
# codefit
[](https://github.com/codefit-cli/codefit/actions/workflows/ci.yml)
[](LICENSE)
> **MCP 首选审计器，用于 AI 生成的代码 — codefit 映射，代理推理。**
codefit 是一个开源工具，基于 Go 语言开发，用于审计部分或全部由 AI 编写的软件。它可以检测开发者在正常开发过程中**看不到**的安全漏洞、算法复杂度、可扩展性问题、结构化数据库问题、回归风险和质量问题。其指导原则是：**codefit 审计开发者永远不会看到的内容** — 如果在正常开发过程中能够看到某个维度，那么它就不在 codefit 的范围内。
## 它是如何工作的 — 协作循环，而非 linting 转储
codefit 不是一种打印发现结果的工具。它是开发者、代理和 codefit 之间的协作循环，每个部分都有明确的职责。**codefit 读取并分析（不使用 LLM，永不编辑代码）；你的代理使用自己的 LLM 进行推理；由你来决策。**
**三种角色 — 谁负责什么。** 每个颜色代表一种角色；在下面的循环中，你将看到相同的颜色。
```mermaid
flowchart LR
DEV["开发者<br/>对话和决策"]
AGENT["代理<br/>协调和推理<br/>(其自己的LLM)"]
CF["CODEFIT<br/>静态分析 · 无LLM<br/>永不编辑代码"]
BL[("基准<br/>审计内存")]
DEV -->|"'审计此项目 / 这些端点 / 此函数'"| AGENT
AGENT -->|调用MCP工具| CF
CF -->|"结构事实<br/>3个桶 + 增量"| AGENT
AGENT -->|"桶 + 项目上下文"| DEV
CF <-.->|读取/写入| BL
DEV -.->|"修复代码 → 重新审计"| AGENT
AGENT -.->|接受 / 修剪| BL
style DEV stroke:#c89a4a,stroke-width:3px
style AGENT stroke:#5a8cd8,stroke-width:3px
style CF stroke:#2d9e54,stroke-width:3px
```
边界是关键：**codefit 永不调用 LLM。** 它运行确定性层（模式 + AST），映射需要推理的类的结构表面，并返回**事实**（“读取 `params.id`”，“正文中无已知 authz 辅助函数”）— 而不是判决。你使用的代理提供智能，通过项目的上下文推理每个项目。 这就是使审计民主化的方法：任何已经使用 AI 编码的人都可以审计，无需额外的 API 密钥或基础设施。
**完整的循环过程。** 相同的参与者，相同的顺序 — 开发者提问，代理协调，codefit 报告事实，开发者决策，修复重新进入循环。
```mermaid
sequenceDiagram
actor Dev as 开发者
participant Agent as 代理（其自己的LLM）
participant CF as codefit（无LLM）
participant BL as 基准
Dev->>Agent: "审计此项目 / 这些端点 / 此函数"
Agent->>CF: 调用MCP工具
CF->>BL: 读取代码 + 基准
CF-->>Agent: 结构事实 — 3个桶 + 增量
Note over CF: 永不判断，永不编辑代码
Agent->>Agent: 用项目上下文推理桶
Agent-->>Dev: 发现 + 推荐
Dev->>Agent: 决策 — 误报 / 修复 / 已解决
Agent->>BL: 接受 / 修剪
Note over Dev,BL: 修复代码 → 重新审计（循环重复）
```
## 它解决了什么问题（以及它不是什么）
代理生成的代码**通过测试**并**满足可见标准**。其他内容无人问津：缺少端点的所有权检查、序列化模型时向客户端发送了每一列、用于安全性的弱哈希、仅在规模扩大时才会造成伤害的索引、存储过程、函数和触发器（动态 SQL、缺少异常处理、跨表级联、外部影响调用）等。codefit 正是审计这一不可见的层面。
它**补充**了 linter 和类型检查器 — 它不取代它们。未使用的 `any`、样式问题、明显的类型错误在正常开发过程中是可见的，因此 linter 已经捕获了它们，它们**不属于 codefit 的范围**。codefit 是独立的审计层，验证 AI 生成的代码在合并之前是安全且正确的。
## 状态 — 第 2 阶段（数据库维度），OLAP 仍未开放
**今日有效，在 `main` 分支上验证，针对真实后端进行实时验证：**
- **提供者：** TypeScript（gotreesitter，纯 Go）和 Go（`go/ast`，用于 CI 自我审计）。
- **确定性安全规则（TypeScript）** — 五类，每类确定性为 1.0（参见 [COVERAGE.md](COVERAGE.md)）。
- **表面映射** — 三类（IDOR、损坏的授权、过载）适用于 Next.js（应用路由器 + 服务器操作）、**Express**、**Fastify** 和 **NestJS**，代理推理完全枚举。另一个文件中资源的访问被标记为（`indirect_access`），不跨文件跟随。
- **`scan-all` 三桶合成** + 按需 `scan-endpoint` 详细信息。
- **基准** — 一个已承诺的、内容寻址的审计表面内存，具有 `baseline-list` / `-accept` / `-prune`，因此重新扫描只会显示更改的内容。
- **`codefit init`** — 检测堆栈，写入 `.codefit.yaml`，并为每个检测到的代理安装 codefit 自己的薄技能。
- **MCP stdio 服务器**（官方 MCP Go SDK），单个静态二进制文件，`CGO_ENABLED=0`。
- **数据库维度审计** — 中立的模式模型，具有两个模式解析器，**Prisma**（`schema.prisma`）和 **SQL-DDL**（Flyway 迁移，增量重建），后者支持 **PostgreSQL**、**MySQL** 和 **SQL Server（T-SQL）** 方言由 `.codefit.yaml` 中的 `database.type` 选择（`postgresql` | `mysql` | `sqlserver`；`sqlite` 返回明确的“尚不支持”提示）。它审计整个中立模式：模式的**结构质量**（键、索引、列形状、名称启发式气味）、**视图** 敏感列暴露、**例程主体** 存储过程、函数和触发器（动态 SQL、缺少异常处理、跨表级联、外部影响调用），以及 **代码 × 模式交叉**，检查代码实际过滤的列是否由索引支持。 一个结构事实被确认（一个没有主键的表）；其他一切都是表面由代理推理。独立运行 `codefit-scan-db`；它也在 `scan-all` 中作为自己的部分运行，并带有自己的维度得分。规则清单位于 [COVERAGE.md](COVERAGE.md)。在真实的 Prisma 和 SQL-DDL（Postgres/MySQL/T-SQL）后端上进行测试。
**在路线图上（尚未在 `main` 分支上）：** HTTP/SSE 传输；OLAP / 数据仓库 DB 规则；**查询模型中的字面值** — 携带 WHERE 子句中的字面值，以便交叉可以从用法中推断基数（`String` 用作枚举，`DateTime` 用作标志）并区分相等过滤器和范围，索引与查询交叉的两个字段观察限制；第 3 阶段代码审查 / 最佳实践 / 测试；第 4 阶段知识包 + `update`。
## codefit 今日覆盖的内容
具体来说，在 `main` 分支上 — 这样你就可以在不阅读完整的 [COVERAGE.md](COVERAGE.md) 的情况下确切知道会发生什么：
- **语言。** TypeScript / TSX（完整规则 + 表面）和 Go（CI 自我审计）。
- **确定性规则（TypeScript，确定性 1.0）。** 硬编码秘密、弱加密（MD5/SHA-1、不安全的 `Math.random` 生成令牌）、危险的 `eval`/`new Function`、内联 SQL 注入和内联 XSS via `dangerouslySetInnerHTML`（React 特有）。这些规则适用于任何 `.ts`/`.tsx` 文件 — 无框架门；哪些规则触发取决于代码，而不是框架。
- **表面映射 — 代理推理。** IDOR、损坏的授权和过载，适用于 **Next.js**（应用路由器路由处理程序 + 服务器操作）、**Express**、**Fastify** 和 **NestJS**。通过结构形状查找处理程序，从不按路径或名称查找。当处理程序通过另一个文件中的服务到达资源时，codefit 标记它（`indirect_access`）并命名调用 — 它不跨文件跟随；代理会。
- **依赖 CVE。** `codefit-check-cves` 使用 [OSV.dev](https://osv.dev)（免费，无需 API 密钥）检查项目的依赖项。与 `package-lock.json` / `go.mod` 中的确切版本一起使用；从 `package.json` 范围中猜测（无 lockfile → 一个诚实的注释，而不是猜测）。codefit 不保留自己的漏洞数据库，而是显示 OSV 的严重性评分。
- **数据库维度 — 代理推理表面。** 从 `database.schema_paths` 读取（Prisma `schema.prisma` 或 SQL-DDL / Flyway 迁移重建为最终模式）。SQL-DDL 解析支持 **三个方言**，由 `.codefit.yaml` 中的 `database.type` 选择：
```yaml
database:
type: postgresql # postgresql | mysql | sqlserver（sqlite：尚不支持）
schema_paths:
- db/migrations
```
codefit 审计模式的**结构质量**（键、索引、列形状和名称启发式气味）、**视图** 敏感列暴露、**例程主体** 存储过程、函数和触发器（动态 SQL、缺少异常处理、跨表级联、外部影响调用），以及 `scan-all` 中的 **交叉代码与模式** 以查看代码过滤的列是否由索引支持。 一个结构事实被确认（一个没有主键的表）；其他一切都是表面由代理判断，全都在重建的中立模式上独立于方言。OLAP **尚未** 审计 — 已声明但未静默。参见 [COVERAGE.md](COVERAGE.md)，获取完整的规则清单和声明的 SQL-DDL 方言限制。
- **未覆盖（已声明，但未静默）。** 超越 Next.js/Express/Fastify/NestJS 的 JS 服务器框架；深度污点分析；业务逻辑正确性；架构和竞争条件类。按引用传递的 Express/Fastify 处理程序不会被枚举。完整的列表和限制在 [COVERAGE.md](COVERAGE.md) 中。
## 安装
两种安装方式。**推荐选项 A（发布二进制文件）** — 它会报告正确的版本，不需要 Go 工具链。
### 选项 A — 下载发布二进制文件（推荐）
从 [最新版本](https://github.com/codefit-cli/codefit/releases/latest) 中获取您平台的存档文件。这是已标记的构建，因此 `codefit version` 会报告实际版本，并且不需要 Go。
**Linux / macOS**（选择您的目标：`linux_amd64`、`linux_arm64`、`darwin_arm64`）：
```bash
tar -xzf codefit_<version>_linux_amd64.tar.gz
sudo mv codefit /usr/local/bin/ # 一个在您的 PATH 上的目录
chmod +x /usr/local/bin/codefit
```
**Windows**（`windows_amd64`）：下载 `codefit_<version>_windows_amd64.zip`，解压它，并将 `codefit.exe` 放入一个稳定的文件夹中（例如 `C:\tools\codefit\`）。可选地将该文件夹添加到您的 `PATH` 中。
使用发布二进制文件验证下载内容 — `checksums.txt` — `sha256sum -c checksums.txt`（Linux），`shasum -a 256 -c checksums.txt`（macOS），或 `Get-FileHash codefit_<version>_windows_amd64.zip -Algorithm SHA256`（Windows PowerShell）。
### 选项 B — `go install`（需要 Go 1.25+）
```bash
go install github.com/codefit-cli/codefit/cmd/codefit@latest
```
注意：此报告的版本为 `0.1.0-dev（commit none, built unknown）`，因为 `go install` 不会嵌入发布元数据 — 版本仅在发布构建（GoReleaser）和 `make build` 中通过 ldflags 注入。在 [Releases](https://github.com/codefit-cli/codefit/releases/latest) 中下载或使用 `make build` 从检出构建时，版本将被标记。
### 验证安装
```bash
codefit version
# 示例输出 — 您的版本、提交和日期将有所不同：
# 发布二进制文件 → codefit <version>（提交 <commit>，构建 <date>）
# go install → codefit 0.1.0-dev（commit none, built unknown）
```
单个静态二进制文件，无运行时依赖项（`CGO_ENABLED=0`），跨编译为 linux/amd64、linux/arm64、windows/amd64、darwin/arm64。不需要 LLM 或身份验证配置 — codefit 不管理模型也不管理凭证。
## 快速开始
```bash
# 1. 在您的项目中，生成配置文件并安装 codefit 的技能
codefit init
# 2. 将 codefit 注册为您的代理的 MCP 服务器（请参阅“连接 codefit”）
# 3. 来自您的代理，用自然语言：
# “审计此项目中的端点以获取 IDOR 和损坏的授权”
```
代理加载 codefit 的技能，调用 `codefit-scan-all`，读取三个桶，推理表面，并与您的项目上下文一起报告。 当您确定某个项目是误报时，它调用 `codefit-baseline-accept` 并提供您的理由；修复后，它调用 `codefit-baseline-prune`。您永远不会离开代理，并且 codefit 从不接触您的代码。
## 连接 codefit
将 codefit 注册为本地（stdio）MCP 服务器。 配置块需要 **绝对路径** 到二进制文件，除非它在代理进程的 `PATH` 上。 codefit 是无状态的 — 每次调用都传递 `root` 工具参数，因此服务器不需要 `cwd`。
### 查找二进制文件路径
**Linux / macOS：**
```bash
which codefit # 如果它在您的 PATH 上
echo "$(go env GOPATH)/bin/codefit" # 如果您使用了 `go install`
```
**Windows（PowerShell）：
```powershell
where.exe codefit # 如果它在您的 PATH 上
Write-Output "$(go env GOPATH)\bin\codefit.exe" # 如果您使用了 `go install`
```
使用发布二进制文件，路径是您放置它的位置（例如 `C:\tools\codefit\codefit.exe`）。
> **Windows 路径陷阱（这是最咬人的部分）：** 在 JSON（`.mcp.json`、`opencode.json`）中，Windows 路径必须使用 **双反斜杠**（`"C:\\Users\\you\\go\\bin\\codefit.exe"`）或 **正斜杠**（`"C:/Users/you/go/bin/codefit.exe"`）。单个反斜杠是一个无效的 JSON 转义字符，并且会静默地破坏配置。同样适用于 TOML 基本字符串（Codex），或使用单引用的字符串字面量： `'C:\Users\you\go\bin\codefit.exe'`。
```json
{
"mcpServers": {
"codefit": { "type": "stdio", "command": "/usr/local/bin/codefit", "args": ["mcp", "serve"] }
}
}
```
Linux / macOS：
```json
{
"mcpServers": {
"codefit": { "type": "stdio", "command": "/usr/local/bin/codefit", "args": ["mcp", "serve"] }
}
}
```
Windows：
```json
{
"mcpServers": {
"codefit": { "type": "stdio", "command": "C:\\Users\\you\\go\\bin\\codefit.exe", "args": ["mcp", "serve"] }
}
}
```
**OpenCode** — `opencode.json`:
Linux / macOS:
```json
{
"mcp": {
"codefit": { "type": "local", "command": ["/usr/local/bin/codefit", "mcp", "serve"], "enabled": true }
}
}
```
Windows:
```json
{
"mcp": {
"codefit": { "type": "local", "command": ["C:\\Users\\you\\go\\bin\\codefit.exe", "mcp", "serve"], "enabled": true }
}
}
```
**Codex** — `~/.codex/config.toml`:
Linux / macOS:
```toml
[mcp_servers.codefit]
command = "/usr/local/bin/codefit"
args = ["mcp", "serve"]
```
Windows (单引号字符串 — 不需要反斜杠转义)：
```toml
[mcp_servers.codefit]
command = 'C:\Users\you\go\bin\codefit.exe'
args = ["mcp", "serve"]
```
然后在项目中运行 `codefit init`。它通过一个 **项目本地 `.codex/`** 目录来检测 Codex（而不是全局配置）；如果 Codex 仅在全局配置，则 `init` 将技能写入标准的 `.agents/skills/codefit/` 目录，并告诉您。
## 工具
codefit 通过 MCP 工具以三种角色公开其功能：
**引擎** — 运行分析并读取结果。
| 工具 | 它能做什么 |
| --- | --- |
| `codefit-scan-all` | 端点综合分析：三个桶（`actionable` / `resolved_clean` / `frontier_pending`）+ 基线增量，以及一个并行的 `db` 部分（数据库结构发现/表面）和每个维度一个 `score`。主要的入口点。 |
| `codefit-scan-endpoint` | 按需详细显示一个文件（以跟进一个 `frontier_pending` 端点）。 |
| `codefit-scan-security` | 确定性发现 + 映射项目上的表面（扁平结果）。 |
| `codefit-scan-db` | 数据库结构审计，基于配置的模式（`database.schema_paths` — Prisma `schema.prisma` 或 SQL-DDL 迁移，支持 PostgreSQL、MySQL 或 SQL Server 方言）。确认（例如，没有主键的表）+ 表面（未索引的外键，重复索引，...）。如果没有模式或解析器，则返回 `measured: false` 和一个注释。 |
| `codefit-surface-idor` / `-authz` / `-overfetch` | 为代理推理一个表面类别。 |
| `codefit-check-cves` | 将项目的依赖项与 OSV.dev（免费，无需 API 密钥）进行对比。根据 lockfiles / `go.mod` 中的确切版本；报告具有 id、严重性和修复版本的漏洞依赖项。 |
**基准** — 项目的审计内存（见下文）。
| 工具 | 它能做什么 |
| --- | --- |
| `codefit-baseline-list` | 列出跟踪的项目（指纹、文件、类别、状态） — `filter: known` 以获取仍待处理的内容。 |
| `codefit-baseline-accept` | 记录人类决定接受某项（误报 / 接受债务）及其原因。 |
| `codefit-baseline-prune` | 在重扫描确认它们消失之前，删除重构解决的项目。 |
**辅助** — 反馈结果并进行内省。
| 工具 | 它能做什么 |
| --- | --- |
| `codefit-confirm-surface` | 集成代理的判决：确认的项目成为一个概率发现，锚定到它。 |
| `codefit-coverage` | 语言的覆盖率清单 — codefit 审计 vs. 推理 vs. 不覆盖的内容。 |
## 基线模型
基线是一个提交的文件（`.codefit-baseline`，仓库根目录 — 共享知识，如 `.codefit.yaml`），记录了 codefit 对审计表面的看法，因此重新扫描只会显示发生变化的内容。关键属性：
- **按内容识别，而非按行。** 每个项目都通过其内容（类别 + 文件 + 规范化代码片段）进行指纹识别，因此移动代码不会导致基线变化；只有当项目内容实际发生变化时（ADR 0009），才会重新检测。
- **当前状态的快照，而非接受列表。** `scan-all` 记录增量 — `new` / `changed` / `known` / `gone` — 并对新增内容采取行动；`known` 界面被沉默但被计数（ADR 0010）。
- **按确定性分级的安全防护。** 表面项目（一个 *问题*）自动变为 `known`。确定性发现（一个 *确认*，确定性 1.0）**永远不会自动沉默** — 它会在每次扫描中显示，直到人类通过原因接受它。沉默确认比沉默问题更严重（ADR 0011）。
- **codefit 绝不会编辑您的代码** — 只会编辑自己的基线文件，并且只有通过代理根据您的决定进行编辑（ADR 0012）。完整的决定历史记录在 `docs/decisions/` 中。
## 差异化：表面映射
确定性规则是任何 linter 都具备的。代理推理的诚实 **表面映射** 使 codefit 与众不同。像 IDOR、破坏的授权和过度获取等类不能通过固定模式捕获 — 它们需要语义理解。因此，codefit 不会外科手术式地标记候选对象（继承 AST 的盲点）；它 **枚举每个类的完整结构表面**，并将所有内容交给代理，附带 **事实** 的结构信号和 **问题** 的审查原因。对于本地无法确认的内容（数据已离开处理程序），它会在 *前沿* 移交；对于未覆盖的内容，它会 **声明** 在 [COVERAGE.md](COVERAGE.md) 中。记录在 [ADR 0005](docs/decisions/0005-surface-frontier-finite-vs-infinite.md) 和 [ADR 0006](docs/decisions/0006-scan-all-endpoint-synthesis.md) 中。
## 原则
- **codefit 绝不会触及您的代码。** 它读取代码和读写自己的基线。修复由代理和您完成，绝不是 codefit。
- **开发者始终做出决定。** codefit 提供信息（`blocked`、存储桶、后果）；它对您的 git 毫无权力，绝不会自行接受项目。
- **代理优先，无自己的 LLM。** codefit 返回事实；您的代理进行推理。
- **诚实关于覆盖范围。** 它未审计的内容被声明，而不是隐藏。
## 支持的语言
| 语言 / 生态系统 | 状态 |
| --- | --- |
| **Go** | 提供商 + 静态安全/最佳实践检测器。 codefit 在 CI 中审计自己。 |
| **TypeScript / Next.js / Express / Fastify / NestJS / Prisma** | 确定性安全规则（5 类，任何 TS 文件）+ 表面映射（IDOR、授权、过度获取）适用于 Next.js 应用路由器、服务器操作、Express、Fastify 和 NestJS。跨文件资源访问被发出信号（`indirect_access`），但不被跟随。针对真实的 Next.js、Express/Prisma 和 NestJS/Prisma 后端进行验证。 |
| Java / Spring | 路线图 |
| Python / FastAPI / Django | 路线图 |
添加语言意味着实现一个 `LanguageProvider` — 它绝不会触及核心、传感器、MCP 服务器或报告（参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 `docs/decisions/`）。
## 贡献
欢迎贡献 — 新规则、表面类别、语言提供商和误报报告尤其受欢迎。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [`rules/README.md`](rules/README.md)。请遵循我们的 [行为准则](CODE_OF_CONDUCT.md)，并根据我们的 [安全政策](SECURITY.md) 报告安全问题。
## 许可证
[Apache 2.0](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器