chinmay-sawant/codehound
GitHub: chinmay-sawant/codehound
CodeHound 是一款 Rust 实现的 Go 静态分析器，作为 golangci-lint 等工具的补充，专注于性能反模式、框架陷阱和 CWE 启发式检测。
Stars: 3 | Forks: 0
# CodeHound — Go PERF 扫描器 + 框架陷阱检测器
CodeHound 是一款快速、有主见的分析器，用于**补充** golangci-lint、
staticcheck 和 govulncheck —— 它专注于那些工具看不到的问题：
- **PERF** — 239 条规则：循环中的 regex、热点路径上的 `fmt.Sprintf`、紧密循环中的 defer、`http.ServeFile` 主体泄漏、请求路径上的分配抖动。参见 [`documents/perf-rules.md`](./documents/perf-rules.md)。计数源自活跃注册表（`codehound --list-rules`）。
- **框架陷阱** — 支持 Gin/Echo/GORM/sqlx：未关闭的响应主体、无界查询行、缺少超时、context 泄漏。
- **CWE 启发式** — 175 个基于夹具的条目，涵盖文件 I/O、SQL 注入、命令注入、链接解析和配置 sink。
- **不良实践** — 136 条规则，涵盖错误处理、并发、测试、API 设计和生产强化。
- **污点跟踪（实验性）** — 针对 CWE-22/78/79/89 的过程内分析。基于名称字符串匹配；非安全级别 —— 用于分类筛查，而非严格拦截。
## 目标
- 检测 Go 服务中静态可见的性能和弱点模式。
- 将发现结果映射到 **PERF** 规则 ID 和 **CWE** 参考。
- 输出机器可读的结果（text、JSON、SARIF）—— 参见 [`documents/output-formats.md`](./documents/output-formats.md)。
- 作为单一静态二进制文件运行，无需外部服务。
## 适用人群
云 AI 订阅（ChatGPT、Claude 等）目前受到了大量
**补贴**。这不会永远持续下去 —— 即使在补贴存在期间，
无限制的 agent 循环依然会耗费真实的资金和天数。
CodeHound 面向**业余项目**和**小规模 Go 作品**：在这些场景中，
你不需要企业级的性能工程，但你仍然希望获得*一些*优化、更清晰的架构，并在实际的交付截止日期前减少代码库中的**冗余污迹**。它是为了在这些限制下供个人使用而构建的：这是一个确定性的、离线的检查清单，你可以在消耗 token 进行无限制审查之前（或取代它）运行。
**在你现有的 Go CI 和 linter 之后运行它** —— 比如 **golangci-lint**、
staticcheck、govulncheck 等。CodeHound 通过这些工具经常遗漏的热点路径 PERF、框架陷阱和**不良实践**规则来补充它们。它不替代它们。目前的语言支持是**以 Go 优先**。
如果你希望减少 agent 造成的问题混乱、培养更好的架构习惯，或者需要一个具体的不良实践目录，请在此环节**使用 CodeHound 而不是开放式技能**：稳定的规则 ID、文件和行号 —— 而不是每次运行都在飘忽不定的感觉。
可选的 agent 分类筛查保持有界；而检查清单是无界的。
如果你为大型组织需要完整的 SRE / CodeQL 级别的覆盖范围，请使用为此构建的工具。如果你需要为副业项目或小型 Go 服务进行快速的 PERF + 陷阱 + BP 检查，并希望通过固定预算进行可选的 agent 分类筛查，那么这款工具适合你。
## 状态
**0.1.0** 产品基准。**以 Go 优先：**生产规则和包主要针对 Go。
Python 是一个 **opt-in** 的 Cargo 特性，仅包含一条实验性规则
（`SLOP101`）。目前没有 TypeScript 插件。用于补充 golangci-lint；
参见 [`documents/go-vs-staticcheck.md`](./documents/go-vs-staticcheck.md) 和
[`documents/adr/0005-multi-lang-honesty.md`](./documents/adr/0005-multi-lang-honesty.md)。
## 路线图
实时路线图：**[`ROADMAP.md`](./ROADMAP.md)**。位于 `plans/` 下的
历史计划是归档笔记，而非待办事项。
## 安装
```
# Go-first 默认构建
cargo install --path .
# 可选的实验性 Python（仅限 SLOP101）
cargo install --path . --features python
```
## 用法
```
# 默认 = 推荐的 pack（S-tier PERF + taint-core CWEs；关闭 BP；fail high）
codehound .
# PERF 风格的 finding 示例（请求路径 / 超时）—— 产品楔子
codehound --profile recommended --only PERF-101 .
# Security pack（启用 taint）或完整目录
codehound --profile security .
codehound --profile all .
# JSON 或 SARIF 输出
codehound --format json ./...
codehound --format sarif ./... > out.sarif
# 测试文件（*_test.go 等）默认排除；使用以下命令包含它们：
codehound --include-tests .
# 限制为特定规则（与 pack allow-list 合并）
codehound --only CWE-22,CWE-89 .
# 显示每个已注册的规则
codehound --list-rules
# 显示单个规则的详细信息
codehound --explain PERF-101
# 编写一个起始的 codehound.toml
codehound init
# 增量分析缓存（默认启用）
codehound --rebuild-cache .
codehound --prune-cache .
codehound --no-cache .
```
配置文件：[`documents/go-recommended-pack.md`](./documents/go-recommended-pack.md)。
缓存：[`documents/incremental-cache.md`](./documents/incremental-cache.md)。
CI 示例：[`.github/workflows/codehound.yml`](./.github/workflows/codehound.yml)。
## 建议
**在 golangci-lint + govulncheck 之后使用 CodeHound**，用于**应用层级的 Go PERF + 框架陷阱 + 精选的 CWE 启发式** —— 而不是取代它们。
**非目标：**不替代 golangci-lint / staticcheck / govulncheck / CodeQL；不是 CVE 扫描器；在 CI 中不默认全面开启 BP。
默认包是 **`recommended`**（高信噪比，遇到高级别即失败）。仅在你确实需要完整目录时才使用 `--profile all`。
### 严重级别
| 级别 | 描述 | 退出码（推荐包） |
|----------|----------------------------------|-------------------------|
| Info | 建议性 | 0 |
| Low | 次要问题 | 0 |
| Medium | 需审查（不会导致推荐包失败） | 0 |
| High | 可能是真实问题 | 1 |
| Critical | 必须立即修复 | 1 |
### SARIF 输出
详细的 SARIF schema 参考、字段映射和 `security-severity` 评分
记录在 [`documents/output-formats.md`](./documents/output-formats.md#sarif-210) 中。
请在 [`plans/v0.0.1/go/perf-heuristics-and-sarif.md`](./plans/v0.0.1/go/perf-heuristics-and-sarif.md) 中查找 SARIF
兼容性说明（特定于 perf 规则的 SARIF 元数据正在开发中）。
### 诊断摘要
传入 `--diagnostics-summary` 以将紧凑的扫描摘要打印到 stderr：
```
scanned 238 files | 195 cached | 43 fresh | 1250.3ms | slowest: PERF-141
```
### 污点跟踪（实验性）
CodeHound 包含一个实验性的过程内污点跟踪引擎，用于
CWE-22、CWE-78、CWE-79 和 CWE-89。**默认禁用** —— 传入 `--taint` 或
设置 `[codehound.taint] enabled = true`。**非安全级别** —— 基于名称字符串的 sink
匹配，无类型系统；仅凭 `filepath.Clean` **不**被视为路径净化器。
用于分类筛查，而非严格拦截。参见 [`documents/taint.md`](./documents/taint.md)。
### 标准 CI 单行命令
默认情况下导出是**关闭**的（`scripts/` 下没有写入操作）。示例：
```
# 默认推荐的 pack → SARIF（fail high；无 BP；无工作区脏数据）
codehound --profile recommended --format sarif . > codehound.sarif
# Security pack（开启 taint）
codehound --profile security --format sarif . > codehound.sarif
```
### 不良实践
136 条 Go 不良实践规则（`BP-*`），涵盖错误处理、
并发、测试、API 设计、代码组织、生产强化和
依赖项管理。注意：与 staticcheck/errcheck 存在部分重叠 —— CodeHound 最适合作为补充工具使用，而不是替代品。参见 [`documents/bad-practices.md`](./documents/bad-practices.md)。
### 配置文件 (`codehound.toml`)
所有字段均为可选。请参阅 `codehound init` 获取入门模板。
```
[codehound]
# 仅分析这些语言。
# languages = ["go", "python"]
# 仅运行特定规则。
# only = ["CWE-22", "CWE-89"]
# 跳过特定规则。
# skip = ["CWE-15"]
# 退出策略："none" | "never" | "medium" | "warnings" | "high" | "strict"。
# 未知值在加载时会被拒绝。
# fail_on = "high"
# 包含/排除 gitignore 风格的 globs。
# include = ["**/*.go"]
# exclude = ["**/vendor/**", "**/*_test.go"]
# 测试文件（*_test.*）默认排除；设置为 false 以包含它们。
# exclude_tests = false
```
## 示例
一个带有路径遍历问题的小型 Go 文件：
```
package sample
import (
"net/http"
"path/filepath"
)
func readFile(w http.ResponseWriter, r *http.Request) {
requested := r.URL.Query().Get("path")
full := filepath.Join("/srv/public", requested)
http.ServeFile(w, r, full)
}
```
CodeHound 输出：
```
high CWE-22 sample.go:10:13 user-controlled input reaches a filesystem path sink
```
## 开发
```
cargo build
cargo test
cargo run -- ./tests/fixtures
```
## 许可证
基于以下任一许可证授权：[MIT](LICENSE)
标签：Go, Python安全, Ruby工具, SAST, 代码安全检测, 可视化界面, 性能优化, 日志审计, 检测绕过, 盲注攻击, 通知系统, 错误基检测, 静态代码分析