oasilturk/ctguard
GitHub: oasilturk/ctguard
一款专为 Go 语言设计的静态分析工具，用于检测并预防时序侧信道安全漏洞。
Stars: 3 | Forks: 1
CTGuard
用于捕获 Go 中时序侧信道漏洞的静态分析器。
[](https://github.com/oasilturk/ctguard/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/oasilturk/ctguard)
[](https://github.com/oasilturk/ctguard/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/oasilturk/ctguard)
[](https://opensource.org/licenses/MIT)
CTGuard 使用基于 SSA 的污点追踪来查找因执行时序导致敏感数据泄露的代码路径。它能捕获使用 `==` 的比较、对私钥的分支判断、依赖于敏感数据的索引等情况。
## 快速开始
### 安装
**macOS / Linux**
```
brew install oasilturk/tap/ctguard
```
或者
```
go install github.com/oasilturk/ctguard/cmd/ctguard@latest
```
**Windows**
```
go install github.com/oasilturk/ctguard/cmd/ctguard@latest
```
所有平台的预编译二进制文件可在 [Releases](https://github.com/oasilturk/ctguard/releases) 页面获取。
### 运行
标记敏感参数，然后进行扫描：
```
//ctguard:secret key
func Verify(key []byte, message []byte) bool {
return bytes.Equal(key, expected) // CTGuard flags this
}
```
```
ctguard ./...
```
## 规则
| 规则 | 描述 | 示例 |
|------|-------------|---------|
| **CT001** | 依赖于敏感数据的分支 | `if secret == "admin"` |
| **CT002** | 非常数时间比较 | `bytes.Equal(secret, input)` |
| **CT003** | 依赖于敏感数据的索引 | `table[secret[i]]` (缓存时序) |
| **CT004** | 在日志/错误中暴露敏感数据 | `log.Printf("%s", secret)` |
| **CT005** | 变长时间算术运算 | `secret / n`, `secret % n` |
| **CT006** | 敏感数据出现在 channel 中 | `ch <- secret` |
| **CT007** | 敏感数据传入 I/O sink | 在隔离区域中的 `conn.Write(secret)` |
## 示例
```
//ctguard:secret key
func Check(key string) {
if key == "admin" { // secret-dependent comparison
grantAccess()
}
}
```
```
auth.go:3:8 CT001: branch depends on secret 'key' (confidence: high)
auth.go:3:8 CT002: string comparison uses secret 'key' (confidence: high)
```
使用常数时间操作进行修复：
```
//ctguard:secret key
func Check(key string) {
if subtle.ConstantTimeCompare([]byte(key), []byte("admin")) == 1 {
grantAccess()
}
}
```
```
No issues found
```
## 输出格式
```
ctguard ./... # Plain text (default)
ctguard -format=json ./... # JSON
ctguard -format=sarif ./... # SARIF (GitHub Code Scanning)
```
## CI 集成
### GitHub Actions
```
- uses: oasilturk/ctguard@main
```
### 结合代码扫描
```
- uses: oasilturk/ctguard@main
with:
format: sarif
args: "-fail=false ./..."
sarif-file: ctguard.sarif
- uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: ctguard.sarif
```
## 配置
在你的项目根目录下创建 `.ctguard.yaml`：
```
rules:
enable: [all]
disable: [CT003]
exclude:
- "vendor/**"
- "**/*_test.go"
```
所有选项
```
annotations:
secrets:
- package: "github.com/vendor/pkg"
function: "Compare"
params: ["secret"]
ignores:
- package: "github.com/vendor/pkg"
function: "SafeFunc"
rules: all
format: json
fail: true
summary: true
min-confidence: low
```
请参阅 [.ctguard.yaml.example](.ctguard.yaml.example) 获取完整参考。
## 抑制检查结果
```
//ctguard:ignore CT002 -- constant prefix check, not a timing risk
return strings.HasPrefix(token, "Bearer ")
```
```
//ctguard:ignore // all rules
//ctguard:ignore CT001 // specific rule
//ctguard:ignore CT001 CT002 // multiple rules
```
## 工作原理
CTGuard 作为自定义分析器与 `go vet` 集成。它会构建代码的 SSA 表示，然后执行以下操作：
1. 收集 `//ctguard:secret` 注解以识别敏感参数
2. 追踪包内跨函数的污点（定点迭代）
3. 针对污点图运行 7 个专门的规则检查器
4. 根据污点的精确度报告带有置信度（高/低）的检查结果
## 局限性
- **污点不会跨包边界传播。** 传递给另一个包中函数的敏感数据不会被追踪进入该包的函数体。请在相应的入口点使用 `//ctguard:secret` 进行标记，或者在 `.ctguard.yaml` 的 `annotations.secrets` 下声明它们。
- **污点不会被追踪进入闭包、goroutine 或延迟执行的函数。** 如果敏感数据被 `go func(){...}()`、闭包或 `defer` 捕获，则不会继续追踪其函数体。
- **CT007 仅在 `//ctguard:isolated` 区域内触发**，该区域需要选择性开启。
- **置信度为 `high` 或 `low`**，由污点精确度推导而来，并非数值评分。
## 兼容性
ctguard 遵循语义化版本控制。在 `1.x` 版本中，以下内容将保持稳定：规则 ID（CT001-CT007）、`.ctguard.yaml` schema、JSON 和 SARIF 输出结构、CLI flag 名称以及下文列出的退出代码。增量更改（新规则、新的可选字段）可能会在次要版本中发布。
| 退出代码 | 含义 |
|-----------|---------|
| `0` | 无检查结果（或使用 `-fail=false` 时的检查结果） |
| `1` | 报告了检查结果，或扫描未完成（加载包失败） |
| `2` | 用法或配置错误（错误的 flag、未知规则、缺少 `go` 工具链） |
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南，参阅 [SECURITY.md](SECURITY.md) 了解如何报告漏洞。
## 许可证
MIT © [oasilturk](https://github.com/oasilturk)
标签：EVTX分析, Go语言, 代码安全审计, 侧信道分析, 安全检测工具, 污点分析, 程序破解, 错误基检测, 静态代码分析