afuckingco/sift
GitHub: afuckingco/sift
Sift 是一款零依赖、超轻量的 Go 语言 CLI 密钥扫描工具，结合正则规则与 Shannon 熵分析来检测代码中的硬编码密钥。
Stars: 0 | Forks: 0
# 🔍 Sift
**超快、零依赖的 CLI 安全扫描器，专用于检测硬编码的 secrets。**
[](https://golang.org/)
[](LICENSE)
[]()
[]()
[](https://github.com/afuckingco/sift/actions/workflows/ci.yml)
Sift 会扫描你的代码库以查找硬编码的 secrets、API keys 和有风险的配置模式 —— 它结合了**基于模式的规则**与 **Shannon entropy 分析**，以便同时捕获已知的 secret 格式和未知的、经过混淆的格式。它被打包为一个没有外部依赖的单一静态二进制文件，完全基于 Go 标准库构建。
## 目录
- [为什么选择 Sift](#why-sift)
- [安装](#installation)
- [快速开始](#quick-start)
- [CLI 参考](#cli-reference)
- [检测引擎](#detection-engine)
- [内置规则](#built-in-rules)
- [自定义规则](#custom-rules)
- [CI/CD 集成](#cicd-integration)
- [项目架构](#project-architecture)
- [开发](#development)
- [路线图](#roadmap)
- [贡献](#contributing)
- [许可证](#license)
## 为什么选择 Sift
大多数 secret 扫描器属于以下两种阵营之一：要么是带有数十个依赖项且启动缓慢的重量级工具，要么是简单的正则表达式 grep，它们会漏掉任何不符合已知模式的内容。Sift 旨在切入一个更小、更精准的生态位：
| | Sift |
|---|---|
| **Dependencies** | 零 — 100% Go 标准库 |
| **Binary 大小** | ~2.3 MB，单一静态文件 |
| **启动时间** | < 100ms |
| **检测方法** | Regex 规则 + Shannon entropy（捕获未知/混淆的 secrets） |
| **并发** | 是 — worker-pool 文件扫描 |
| **Git-aware 模式** | 仅扫描更改过的文件 (`--git-diff`) |
| **自定义规则** | 纯文本 `.siftrules` 格式，无需学习配置语言 |
| **CI/CD 输出** | 原生 JSON 输出，方便流水线解析 |
Sift 有意保持精简。它不会联网通信，不需要配置服务器，也不需要包管理器来安装。克隆它，构建它，运行它。
## 安装
### 下载预构建的二进制文件
从 [Releases 页面](https://github.com/afuckingco/sift/releases) 获取适合你平台的最新版本：
```
# Linux
curl -L https://github.com/afuckingco/sift/releases/latest/download/sift-linux-amd64 -o sift
chmod +x sift
# macOS (Apple Silicon)
curl -L https://github.com/afuckingco/sift/releases/latest/download/sift-macos-arm64 -o sift
chmod +x sift
```
```
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/afuckingco/sift/releases/latest/download/sift-windows-amd64.exe" -OutFile "sift.exe"
```
### 从源码构建
需要 Go 1.21+。
```
git clone https://github.com/afuckingco/sift.git
cd sift
go build -ldflags="-s -w" -o sift .
```
或者使用 `make`：
```
make build
```
验证安装：
```
./sift --version
```
## 快速开始
```
# 扫描当前目录
./sift .
# 仅扫描上次提交中更改的文件（快速，适用于 pull requests 上的 CI）
./sift --git-diff .
# 用于 pipelines 的机器可读输出
./sift --json . > report.json
# 使用自定义规则文件
./sift --rules .siftrules .
```
示例输出：
```
🔍 Sift v1.0.0: Smart & Extensible Security Scanner
✅ Loaded 5 default rules + 2 custom rules.
⚠️ Found 1 issues in 3.2ms:
[CRITICAL] AWS Access Key (S001)
config/settings.go:14
| awsKey := "AKIAIOSFODNN7EXAMPLE123"
```
如果存在任何 `CRITICAL` 或 `HIGH` 严重级别的发现，Sift 将以状态码 `1` 退出 —— 这使其成为 CI 流水线和 pre-commit hooks 的直接替代门禁。
## CLI 参考
| Flag | 描述 | 默认值 |
|---|---|---|
| `--json` | 以 JSON 格式输出发现结果，而不是格式化的终端文本 | `false` |
| `--git-diff` | 仅扫描上次提交中更改过的文件（在 git 仓库之外回退到全量扫描） | `false` |
| `--rules ` | 自定义规则文件的路径，将与内置规则合并 | `.siftrules` |
| `--version` | 打印版本信息并退出 | — |
| `[directory]` | 位置参数：要扫描的目录 | `.` |
## 检测引擎
Sift 结合了两种互补的检测策略：
**1. 模式匹配** — 一组针对已知 secret 格式（云提供商密钥、私钥标头、通用 token 赋值）和有风险的配置模式（Dockerfile 配置不当）的正则表达式。
**2. Shannon entropy 分析** — 用于应对固定模式无法预料的所有情况。Sift 从源文件中提取带引号的字符串字面量，并计算它们的 [Shannon entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory))：
```
H(X) = -Σ p(x) · log₂ p(x)
```
具有高字符多样性和低可预测性的字符串（一个真正看起来随机的 token）会获得高 entropy 值。低 entropy 字符串 —— 常规单词、短标识符、重复字符 —— 得分较低，将被忽略。这使得 Sift 能够标记出它以前从未见过的格式的 secrets，其代价是需要进行一些调整以避免误报。
为了降低噪声，entropy 引擎在标记之前还会过滤掉常见的高 entropy 但无害的模式：
- JWTs（三个由点分隔的 base64url 段）
- UUIDs（标准的 8-4-4-4-12 十六进制格式）
如果一个字符串的 entropy 超过 `5.2`，并且它混合了大写字母、小写字母和数字，或者其 entropy 直接超过了 `5.8`，就会被标记为可能的 secret。
## 内置规则
| ID | 描述 | 严重性 |
|---|---|---|
| `S001` | AWS Access Key (`AKIA`, `ASIA` 及相关前缀) | CRITICAL |
| `S002` | 通用 secret/token/password 赋值 (`api_key = "..."` 等) | HIGH |
| `S003` | Private key 块 (`-----BEGIN ... PRIVATE KEY-----`) | CRITICAL |
| `D001` | Dockerfile 以 `USER root` 运行 | MEDIUM |
| `D002` | Dockerfile 使用 `:latest` 镜像标签 | LOW |
| `ENT01` | 高 entropy 字符串字面量 (Shannon entropy 引擎) | HIGH |
## 自定义规则
通过在你的项目根目录放置一个 `.siftrules` 文件（或使用 `--rules` 指向任意路径）来添加特定于项目的检测规则。格式：
```
# Sift 自定义规则
# ID | Severity | Regex | Description
CUST01 | HIGH | (?i)internal_db_pass\s*=\s*['"].+['"] | Internal DB Password Leak
CUST02 | MEDIUM | (?i)192\.168\.\d{1,3}\.\d{1,3} | Hardcoded Internal IP Address
```
规则：
- 每行一条规则，以竖线分隔：`ID | SEVERITY | REGEX | DESCRIPTION`
- 以 `#` 开头的行和空行将被忽略
- `SEVERITY` 必须是 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW` 中的一种
- 无效的 regex 或格式错误的行将被跳过并发出警告 —— 它们永远不会导致扫描崩溃
- 自定义规则是叠加的；它们将与 6 条内置规则一起运行
## CI/CD 集成
### GitHub Actions
Sift 提供了一个现成可用的 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)，它会运行测试、构建二进制文件，并在打标签发布时交叉编译适用于 Linux、macOS 和 Windows 的二进制文件。将其放入任何仓库中，即可在 Pull request 上设置 secret 扫描门禁：
```
- name: Run Sift
run: |
curl -L https://github.com/afuckingco/sift/releases/latest/download/sift-linux-amd64 -o sift
chmod +x sift
./sift --git-diff .
```
如果存在任何 `CRITICAL` 或 `HIGH` 发现结果，扫描将自动导致任务失败。
### Pre-commit hook
```
#!/bin/sh
# .git/hooks/pre-commit
./sift --git-diff . || {
echo "❌ Sift found potential secrets. Commit blocked."
exit 1
}
```
## 项目架构
```
sift/
├── main.go # CLI entry point, flag parsing, exit codes
├── engine.go # Concurrent file scanner, git-diff mode, worker pool
├── rules.go # Default rule definitions + custom rule file parser
├── entropy.go # Shannon entropy calculation and secret heuristics
├── output.go # Terminal (colorized) and JSON output formatting
├── sift_test.go # Unit tests covering entropy, rules, scanning, output
├── .siftrules # Example custom rules file
├── Makefile # build / test / clean / release targets
└── .github/workflows/ # CI: test, build, cross-compile on tag
└── ci.yml
```
扫描通过一个固定大小的 worker pool（4 个 goroutines）进行并行化处理，它们从带有缓冲的文件路径 channel 中读取数据，并使用一个受 mutex 保护的共享 findings slice。文件发现过程会跳过隐藏目录、`node_modules`、`vendor` 和 `target`，并忽略超过 2MB 的文件和符号链接，以确保在大型仓库中扫描既快速又安全。
## 开发
```
make build # Build the binary for your platform
make test # Run the test suite (uses -race when cgo is available)
make clean # Remove built binaries
make release # Cross-compile for linux/amd64, darwin/amd64, darwin/arm64, windows/amd64
```
直接运行测试：
```
go test -v ./...
```
## 路线图
- [ ] 配置文件支持 (`.sift.yml`)，用于设置默认 flags 和忽略路径
- [ ] `--ignore` flag / `.siftignore` 文件，用于排除路径
- [ ] 基准/允许列表支持，用于处理已接受的误报
- [ ] 更多内置规则（GCP、Azure、Slack、Stripe、通用 PEM 格式）
- [ ] SARIF 输出，用于 GitHub 代码扫描集成
- [ ] 预构建的 `pre-commit` 框架 hook 定义
## 许可证
MIT License — 详情请参阅 [LICENSE](LICENSE)。
**由 [@afuckingco](https://github.com/afuckingco) 构建**
标签：EVTX分析, Go, Redis利用, Ruby工具, StruQ, 云安全监控, 文档结构分析, 日志审计, 静态分析