codefit-cli/codefit

 # codefit [](https://github.com/codefit-cli/codefit/actions/workflows/ci.yml) [](LICENSE) codefit 是一个开源工具，使用 Go 编写，专门用于审计由 AI 编写（部分或全部）的软件。它检测开发者在正常开发期间**永远看不到**的内容：安全漏洞、扩展性糟糕的算法复杂度、结构性数据库问题、回归风险，以及只有在深入审查时才会显现的质量问题。其指导原则是：*codefit 审计开发者永远看不到的内容* —— 如果某个维度在正常开发期间是可见的，那它就不在范围内。 ## 工作原理 —— 一个协作循环，而不是 linter 报告的堆砌 codefit 并不是一个只打印问题列表的工具。它是你、你的 agent 和 codefit 之间循环的一部分 —— 每一方都有其独特的职责。**codefit 负责读取和分析（不使用 LLM，绝不修改代码）；你的 agent 借助其 LLM 进行推理；由你做出决定。** **三种角色 —— 各司其职。** 每种颜色代表一个角色；你将在下方的循环中再次看到相同的颜色。 ``` flowchart LR DEV["DEVELOPER
talks & decides"] AGENT["AGENT
orchestrates & reasons
(its own LLM)"] CF["CODEFIT
static analysis · NO LLM
never edits code"] BL[("baseline
audit memory")] DEV -->|"'audit this project / these endpoints / this function'"| AGENT AGENT -->|calls MCP tools| CF CF -->|"structural FACTS
3 buckets + delta"| AGENT AGENT -->|"buckets + project context"| DEV CF <-.->|reads/writes| BL DEV -.->|"fix code → re-audit"| AGENT AGENT -.->|accept / prune| 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 辅助程序”）—— 从不给出判决。你已经在使用的 agent 提供了智能，结合项目的上下文对每一项进行推理。这就是审计的民主化之处：任何已经使用 AI 编写代码的人都可以进行审计，而无需额外的 API 密钥或基础设施。 **一次完整的循环过程。** 相同的参与者，与上述相同的顺序 —— 开发者提出请求，agent 进行编排，codefit 报告事实，开发者做出决定，修复后再次进入循环。 ``` sequenceDiagram actor Dev as Developer participant Agent as Agent (its own LLM) participant CF as codefit (NO LLM) participant BL as baseline Dev->>Agent: "audit this project / these endpoints / this function" Agent->>CF: calls MCP tools CF->>BL: reads code + baseline CF-->>Agent: structural FACTS — 3 buckets + delta Note over CF: never judges, never edits code Agent->>Agent: reasons buckets WITH project context Agent-->>Dev: findings + recommendation Dev->>Agent: decides — false positive / fix / resolved Agent->>BL: accept / prune Note over Dev,BL: fix code → re-audit (loop repeats) ``` ## 它解决的问题（以及它不是什么） agent 生成的代码能够**通过测试**并**满足可见的标准**。没人能看到其余的部分：endpoint 上缺失的所有权检查、将模型的所有列都序列化给客户端、安全性薄弱的哈希算法、只有在规模扩大时才会造成危害的 index。codefit 审计的正是这一隐形层。 它是对 linter 和类型检查器的**补充** —— 而不是替代它们。未使用的 `any`、代码风格问题、明显的类型错误在正常开发期间都是可见的，linter 已经可以捕获它们，因此它们**不在范围内**。codefit 是独立的审计层，用于在 AI 生成的代码合并**之前**验证其安全性和正确性。 ## 状态 —— 第二阶段已完成 (`v0.2.0`) **如今在 `main` 分支上可用，并已在真实的后端实际使用中验证：** - **Providers：** TypeScript (gotreesitter，纯 Go) 和 Go (`go/ast`，用于 CI 自我审计)。 - **确定性安全规则** —— 五大类，每一类都是确定性为 1.0 的事实（参见 [COVERAGE.md](COVERAGE.md)）。 - **Surface 映射** —— 针对三种类别（IDOR、broken authorization、over-fetching），支持 Next.js (App Router + Server Actions)、**Express、Fastify 和 NestJS**，为 agent 的推理进行了完整的枚举。对于位于另一个文件中的资源访问会进行标记（`indirect_access`），而不进行跨文件追踪。 - **`scan-all` 三桶综合分析** + 按需提供的 `scan-endpoint` 详情。 - **Baseline** —— 对已审计 surface 的已提交、内容寻址记忆，配合 `baseline-list` / `-accept` / `-prune`，因此重新扫描时只会浮现出发生变更的内容。 - **`codefit init`** —— 检测技术栈，写入 `.codefit.yaml`，并为检测到的每个 agent 安装 codefit 自己的轻量级 skill。 - **MCP stdio server**（官方 MCP Go SDK），单一静态二进制文件，`CGO_ENABLED=0`。 - **数据库结构审计（第二阶段）** —— 一个中立的 schema 模型，包含两个 schema 解析器，**Prisma** (`schema.prisma`) 和 **SQL-DDL**（Flyway migrations，增量重建），后者支持由 `.codefit.yaml` 中的 `database.type` 选择的 **PostgreSQL、MySQL 和 SQL Server (T-SQL)** 方言（`postgresql` | `mysql` | `sqlserver`；`sqlite` 会返回明确的“尚不支持”提示）。八条纯 schema 的 OLTP 规则，与方言无关 —— 它们基于中立 schema 进行推理，无论是由哪种方言解析的：没有主键的表（已确认），以及 —— 作为 agent 推理的 surface —— 未建索引的外键、重复的索引、多值列、文本类型的外键、缺失的审计时间戳、明文敏感列和重复组。使用 `codefit-scan-db` 独立运行；它也会作为独立部分在 `scan-all` 中运行，并带有各维度的评分。已在真实的 Prisma 后端和真实的 SQL-DDL (Postgres/MySQL/T-SQL) 后端上进行了 Dogfooding（内部测试）。 **在路线图上（尚未进入 `main`）：** HTTP/SSE 传输；DB 查询驱动规则（N+1，index-vs-query）和视图/存储过程/触发器规则；第三阶段代码审查 / 最佳实践 / 测试；第四阶段知识包 + `update`。 参见 [PRD](docs/PRD-codefit-v1.4.md) §25 和 [VERSIONING.md](VERSIONING.md)。 ## codefit 目前涵盖的内容 具体来说，在 `main` 分支上 —— 这样你无需完整阅读 [COVERAGE.md](COVERAGE.md) 就能确切知道预期内容： - **语言。** TypeScript / TSX（完整规则 + surface）和 Go（CI 自我审计）。 - **确定性规则（TypeScript，确定性 1.0）。** 硬编码的密钥、弱加密（MD5/SHA-1，用于 token 的不安全 `Math.random`）、危险的 `eval`/`new Function`、内联 SQL 注入，以及通过 `dangerouslySetInnerHTML` 进行的内联 XSS（根据其模式属于 React 专有）。这些规则在**任何** `.ts`/`.tsx` 文件上运行 —— 没有框架门控；触发哪些规则取决于代码，而不是框架。 - **Surface 映射 —— agent 进行推理。** 针对 **Next.js**（App Router 路由处理程序 + Server Actions）、**Express**、**Fastify** 和 **NestJS** 的 IDOR、broken authorization 和 over-fetching。通过结构形状而不是路径或名称来查找处理程序。当处理程序在另一个文件中通过 service 访问资源时，codefit 会对其进行标记（`indirect_access`）并指出该调用 —— 它不会跨文件追踪；这由 agent 来完成。 - **依赖项 CVE。** `codefit-check-cves` 使用 `package-lock.json` / `go.mod` 中的**确切**版本对照 [OSV.dev](https://osv.dev)（免费，无需 API 密钥）检查依赖项 —— 绝不从 `package.json` 的范围中猜测（如果没有 lockfile → 给出诚恳的提示，而不是猜测）。codefit 不保留自己的漏洞数据库，并显示 OSV 的严重程度，而不是重新计算 CVSS。 - **数据库结构 —— 纯 schema，agent 对 surface 进行推理。** 从 `database.schema_paths` 读取（Prisma `schema.prisma` 或重建为最终 schema 的 SQL-DDL / Flyway migrations 目录）。SQL-DDL 解析支持**三种方言**，由 `.codefit.yaml` 中的 `database.type` 选择： database: type: postgresql # postgresql | mysql | sqlserver (sqlite: not supported yet) schema_paths: - db/migrations 已确认：没有主键的表 (DB-050)。Surface：未建索引的外键、重复的索引、多值列、文本类型的外键、缺失的审计时间戳、明文敏感列、重复组 —— 全部与方言无关（它们基于重建的中立 schema 进行推理，绝不基于特定方言的字段）。查询行为（N+1、index-vs-query）、视图/存储过程/触发器和 OLAP **尚未**被审计 —— 已明确声明，而非保持沉默。有关已声明的 SQL-DDL 方言限制（T-SQL 例程主体边缘情况、MySQL `DELIMITER` 识别等），请参见 [COVERAGE.md](COVERAGE.md)。 - **不涵盖（已声明，而非隐藏）。** 超出 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`）： ``` tar -xzf codefit_0.1.0_linux_amd64.tar.gz sudo mv codefit /usr/local/bin/ # a directory on your PATH chmod +x /usr/local/bin/codefit ``` **Windows** (`windows_amd64`)：下载 `codefit_0.1.0_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_0.1.0_windows_amd64.zip -Algorithm SHA256` (Windows PowerShell)。 ### 选项 B —— `go install`（需要 Go 1.25+） ``` go install github.com/codefit-cli/codefit/cmd/codefit@latest ``` 请注意：这会将其版本报告为 `0.1.0-dev (commit none, built unknown)`，因为 `go install` 不会嵌入发布元数据 —— 该版本仅通过 ldflags 注入到发布构建版本 和 `make build` 中。此二进制文件在功能上与发布版本**完全一致**。如需带有标签的版本，请从 [Releases](https://github.com/codefit-cli/codefit/releases/latest) 下载，或者通过检出代码并使用 `make build` 进行构建。 ### 验证安装 ``` codefit version # 示例输出 —— 你的 commit 和 date 会有所不同： # release binary → codefit 0.1.0 (commit , built ) # go install → codefit 0.1.0-dev (commit none, built unknown) ``` 一个单一的静态二进制文件，没有运行时依赖（`CGO_ENABLED=0`），可交叉编译到 linux/amd64、linux/arm64、windows/amd64、darwin/arm64。没有需要配置的 LLM 或身份验证 —— codefit 不管理任何模型，也不管理任何凭证。 ## 快速开始 ``` # 1. 在你的项目中，生成 config + 为你的 agent(s) 安装 codefit 的 skill codefit init # 2. 将 codefit 注册为你 agent 的 MCP server（参见下方的“Connect codefit”） # 3. 从你的 agent 中，用自然语言： # “audit 该项目中的 endpoints 是否存在 IDOR 和 broken authorization” ``` agent 会加载 codefit 的 skill，调用 `codefit-scan-all`，读取这三个桶，结合你项目的上下文对 surface 进行推理，并向你报告。当你确定某一项为误报时，它会附带你的理由调用 `codefit-baseline-accept`；在修复之后，它会调用 `codefit-baseline-prune`。你始终无需离开 agent，而 codefit 也绝不会触碰你的代码。 ## 连接 codefit 将 codefit 注册为本地 (stdio) MCP server。除非二进制文件位于 agent 进程的 `PATH` 中，否则配置块需要该二进制文件的**绝对路径**。codefit 是无状态的 —— 项目根目录在每次调用时作为 `root` 工具参数传入，因此 server 不需要 `cwd`。 ### 查找二进制文件路径 **Linux / macOS：** ``` which codefit # if it's on your PATH echo "$(go env GOPATH)/bin/codefit" # if you used `go install` ``` **Windows (PowerShell)：** ``` where.exe codefit # if it's on your PATH Write-Output "$(go env GOPATH)\bin\codefit.exe" # if you used `go install` ``` 如果使用发布版的二进制文件，路径取决于你放置它的位置（例如 `C:\tools\codefit\codefit.exe`）。 在下方每个 Windows 示例中，**请将 `you` 替换为你的 Windows 用户名**，并将路径指向 codefit 实际所在的位置。 **Claude Code** —— `.mcp.json` (项目) 或 `claude mcp add`： Linux / macOS： ``` { "mcpServers": { "codefit": { "type": "stdio", "command": "/usr/local/bin/codefit", "args": ["mcp", "serve"] } } } ``` Windows： ``` { "mcpServers": { "codefit": { "type": "stdio", "command": "C:\\Users\\you\\go\\bin\\codefit.exe", "args": ["mcp", "serve"] } } } ``` **OpenCode** —— `opencode.json`： Linux / macOS： ``` { "mcp": { "codefit": { "type": "local", "command": ["/usr/local/bin/codefit", "mcp", "serve"], "enabled": true } } } ``` Windows： ``` { "mcp": { "codefit": { "type": "local", "command": ["C:\\Users\\you\\go\\bin\\codefit.exe", "mcp", "serve"], "enabled": true } } } ``` **Codex** —— `~/.codex/config.toml`： Linux / macOS： ``` [mcp_servers.codefit] command = "/usr/local/bin/codefit" args = ["mcp", "serve"] ``` Windows（单引号字面字符串 —— 无需转义反斜杠）： ``` [mcp_servers.codefit] command = 'C:\Users\you\go\bin\codefit.exe' args = ["mcp", "serve"] ``` 然后在项目中运行 `codefit init`。它通过**项目本地的 `.codex/`** 目录（而非全局配置）检测 Codex；如果 Codex 仅进行了全局配置，`init` 会 skill 写入标准的 `.agents/skills/codefit/` 位置，并提示你。 ## 工具 codefit 将其能力以三种角色的 MCP 工具形式公开： **引擎** —— 运行分析并读取结果。 | 工具 | 功能 | | --- | --- | | `codefit-scan-all` | 每个 endpoint 的综合分析：三个桶（`actionable` / `resolved_clean` / `frontier_pending`）+ baseline delta，加上一个并行的 `db` 部分（数据库结构发现/surface）以及各维度的 `score`。这是主入口。 | | `codefit-scan-endpoint` | 按需提供单个文件的完整详细信息（用于追踪 `frontier_pending` endpoint）。 | | `codefit-scan-security` | 对项目进行确定性发现 + 映射 surface（扁平化结果）。 | | `codefit-scan-db` | 针对已配置的 schema 进行数据库结构审计（`database.schema_paths` —— Prisma `schema.prisma` 或根据 `database.type` 指定的 PostgreSQL、MySQL 或 SQL Server 方言的 SQL-DDL migrations）：确认（例如没有主键的表）+ surface（未建索引的外键、重复的索引等）。当没有 schema 或解析器时，返回带提示的 `measured: false`。 | | `codefit-surface-idor` / `-authz` / `-overfetch` | 为 agent 的推理枚举一个 surface 类别。 | | `codefit-check-cves` | 根据 OSV.dev（免费，无需 API 密钥）检查项目的依赖项。从 lockfiles / `go.mod` 读取确切版本；报告带有 ID、严重性和修复版本的易受攻击依赖项。 | **Baseline** —— 项目的审计记忆（见下文）。 | 工具 | 功能 | | --- | --- | | `codefit-baseline-list` | 列出被追踪的项（指纹、文件、类别、状态）—— 使用 `filter: known` 查看仍待处理的项。 | | `codefit-baseline-accept` | 记录人类接受某一项（误报 / 接受的技术债务）的决定及理由。 | | `codefit-baseline-prune` | 剔除重构已解决的问题（首先会重新扫描以确认它们已被消除）。 | **辅助** —— 反馈结果并进行内省。 | 工具 | 功能 | | --- | --- | | `codefit-confirm-surface` | 整合 agent 的判决：被确认的项目将成为锚定于该 surface 的概率性发现。 | | `codefit-coverage` | 针对某种语言的覆盖范围清单 —— codefit 审计什么、推理什么以及不涵盖什么。 | ## Baseline 模型 Baseline 是一个已提交的文件（`.codefit-baseline`，位于仓库根目录 —— 像 `.codefit.yaml` 一样属于共享知识），它记录了 codefit 对已审计 surface 的看法，因此重新扫描时只会浮现出发生变更的内容。主要特性： - **按内容而非行号标识。** 每一项都通过其内容（类别 + 文件 + 规范化的代码片段）生成指纹，因此移动代码不会扰乱 baseline；只有当项的内容真正发生改变时才会被重新检测 (ADR 0009)。 - **当前状态的快照，而非接受列表。** `scan-all` 记录 delta —— `new` / `changed` / `known` / `gone` —— 并对新出现的项采取行动；`known` 的 surface 会被静默处理但仍被计算在内 (ADR 0010)。 - **根据确定性分级的防护措施。** 一个 surface 项（一个*问题*）会自动变为 `known`。确定性发现（一种*断言*，确定性 1.0）**永远不会被自动静默** —— 它会在每次扫描中显示，直到人类以充分理由接受它。静默处理一项断言比静默处理一个问题要严重得多 (ADR 0011)。 - **codefit 绝不修改你的代码** —— 它只修改自己的 baseline 文件，并且只能通过 agent 根据你的决定采取行动 (ADR 0012)。完整的决策历史记录在 `docs/decisions/` 中。 ## 差异化所在：surface 映射 确定性规则是任何 linter 都会做的事情。供 agent 进行推理的、诚实的 **surface 映射** 才是 codefit 与众不同之处。诸如 IDOR、broken authorization 和 over-fetching 等类别无法通过固定的模式来捕获 —— 它们需要语义理解。因此，codefit 不会外科手术式地标记候选对象（从而继承 AST 的盲点）；它会**枚举每个类别的完整结构面**，并将所有内容连同作为**事实**的结构信号和作为**问题**的审查理由一起交给 agent。它无法在本地确认的内容（离开处理程序的数据）会在*边界*处移交；它不涵盖的内容则会在 [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 绝不触碰你的代码。** 它读取代码并读/写自己的 baseline。修复是由 agent 和你完成的，绝不是 codefit。 - **始终由开发者决定。** codefit 提供信息（`blocked`、各个桶、后果）；它对你的 git 没有任何控制权，也绝不会自己接受任何项。 - **Agent 优先，自身不含 LLM。** codefit 返回事实；由你的 agent 进行推理。 - **对覆盖范围诚实。** 未审计的内容都是明确声明的，而非隐藏的。 ## 支持的语言 | 语言 / 生态系统 | 状态 | | --- | --- | | **Go** | Provider + 静态安全/最佳实践检测器。codefit 在 CI 中进行自我审计。 | | **TypeScript / Next.js / Express / Fastify / NestJS / Prisma** | 确定性安全规则（5 大类，任何 TS 文件均可）+ surface 映射（IDOR、authz、over-fetching），适用于 Next.js App Router、Server Actions、Express、Fastify 和 NestJS。跨文件资源访问会进行标记（`indirect_access`），不进行追踪。已通过真实的 Next.js、Express/Prisma 和 NestJS/Prisma 后端验证。 | | Java / Spring | 路线图 | | Python / FastAPI / Django | 路线图 | 添加一种语言意味着只需实现一个 `LanguageProvider` —— 它绝不会触及核心、传感器、MCP server 或报告功能（参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 `docs/decisions/`）。 ## 贡献 欢迎各种贡献 —— 特别是新规则、surface 类别、语言 provider 以及误报报告。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [`rules/README.md`](rules/README.md)。请遵循我们的[行为准则](CODE_OF_CONDUCT.md)，并按照我们的[安全政策](SECURITY.md)报告安全问题。 ## 许可证 [Apache 2.0](LICENSE)。

标签：AI辅助开发, EVTX分析, Go, MCP, Ruby工具, 日志审计, 错误基检测, 静态代码分析