adhamcybersec/secretguard
GitHub: adhamcybersec/secretguard
SecretGuard 是一款基于正则、熵值分析和机器学习三层引擎的代码密钥检测与修复工具，用于发现和防止代码仓库中的敏感凭证泄露。
Stars: 0 | Forks: 0
# SecretGuard 🔐
[](https://pypi.org/project/secretguard/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/adhamcybersec/secretguard/issues)
[](https://github.com/adhamcybersec/secretguard/stargazers)
SecretGuard 使用三层检测引擎（正则表达式模式、香农熵分析和随机森林机器学习分类器，F1 分数：0.96）扫描您的源代码，以发现暴露的凭证、API 密钥、密码和敏感数据。
## 功能特性
- **三层检测**：28+ 种正则表达式模式、熵分析和机器学习分类器协同工作
- **机器学习驱动**：基于 210 个样本训练并进行交叉验证的随机森林模型（精确率：0.95，召回率：0.97）
- **密钥掩码**：所有报告输出都会对检测到的密钥进行掩码处理，以防止二次泄露
- **Git 历史扫描**：使用 `scan-history` 扫描过去的提交记录以查找密钥
- **实时验证**：`--verify` 标志可检查检测到的凭证是否仍然有效（支持 GitHub, AWS）
- **SARIF 输出**：通过增强型 SARIF 2.1.0 报告实现 IDE 和 CI/CD 集成
- **Pre-commit 框架**：原生 `.pre-commit-hooks.yaml` 支持标准 pre-commit 集成
- **默认安全**：报告文件以 0o600 权限写入，跳过符号链接
- **多种格式**：支持控制台、JSON、Markdown、HTML 和 SARIF 输出
- **可配置**：通过 `.secretguard.yml` 进行项目特定设置
- **白名单与行内忽略**：通过文件/模式白名单和 `# secretguard:ignore` 减少误报
## 安装
```
pip install secretguard
```
包含实时凭证验证支持：
```
pip install secretguard[verify]
```
## 快速开始
```
# 扫描当前目录
secretguard scan
# 扫描指定路径并输出 JSON
secretguard scan /path/to/project --format json --output report.json
# 生成 HTML 报告
secretguard scan . --format html --output report.html
# 扫描并提供修复建议
secretguard scan . --remediate
# 禁用 ML 以加速扫描
secretguard scan . --no-ml
# 验证检测到的凭据是否有效
secretguard scan . --verify
# 扫描 git 历史记录以查找泄露的机密
secretguard scan-history --max-commits 200
# 评估 ML 模型性能
secretguard ml-evaluate
```
## Pre-commit 框架集成
添加到您的 `.pre-commit-config.yaml`：
```
repos:
- repo: https://github.com/adhamcybersec/secretguard
rev: v0.8.0
hooks:
- id: secretguard
```
然后运行：
```
pre-commit install
```
或者，使用内置的 hook 安装程序：
```
secretguard install-hook
```
## CI/CD 集成
### GitHub Actions
```
name: Secret Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install secretguard
- run: secretguard scan . --format sarif --output results.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
### GitLab CI
```
include:
- remote: 'https://raw.githubusercontent.com/adhamcybersec/secretguard/master/ci-templates/gitlab-ci.yml'
```
或手动添加：
```
secretguard-scan:
stage: test
image: python:3.12-slim
before_script:
- pip install secretguard
script:
- secretguard scan . --format sarif --output gl-secretguard-report.sarif
artifacts:
reports:
sast: gl-secretguard-report.sarif
```
## 工作原理
SecretGuard 采用三层检测方法：
1. **正则表达式模式匹配**（28+ 种模式）：检测已知的密钥格式 —— AWS 密钥、GitHub 令牌、Stripe 密钥、私钥文件头、数据库连接字符串等。模式按提供商分组，位于 `secretguard/detectors/patterns.py` 中。
2. **香农熵分析**：识别可能是密码或密钥的高随机性字符串（熵值 >= 4.0）。根据熵、长度和字符多样性应用置信度评分，并对 UUID 和 git 哈希值进行惩罚。
3. **机器学习分类**（随机森林）：基于 210 个标记样本训练的分类器，用于捕获与已知模式不匹配的密钥。特征包括熵、字符比例、多样性、常见前缀和连续字符运行。交叉验证 F1 分数：0.96。
结果通过 O(1) 基于集合的查找在各检测器间进行去重，机器学习模型会缓存到磁盘以加快后续扫描速度。
## 支持的密钥类型
| 类别 | 类型 |
|----------|-------|
| **云服务** | AWS Access Keys, AWS Secret Keys, Google API Keys, Azure Storage Keys |
| **Git 平台** | GitHub PATs, GitHub OAuth, GitHub Fine-Grained, GitLab PATs |
| **支付** | Stripe Live & Test Keys |
| **通信** | Slack Webhooks, Slack Bot Tokens, Discord Bot Tokens |
| **邮件** | SendGrid, Twilio, Mailgun API Keys |
| **包管理** | npm Tokens, PyPI Tokens |
| **加密** | RSA/SSH/PGP/EC/DSA Private Keys |
| **数据库** | PostgreSQL, MySQL, MongoDB, Redis 连接字符串 |
| **认证** | JWT Tokens, OAuth Bearer Tokens, 通用 API Keys, 密码 |
## 配置
使用 `secretguard init` 创建 `.secretguard.yml`，或手动创建：
```
exclude:
- "node_modules/**"
- "*.test.js"
- "vendor/**"
confidence_threshold: 0.75
custom_patterns:
- name: "Internal API Key"
pattern: "INTERNAL_[A-Z0-9]{32}"
confidence: 0.95
severity: high
remediation: "Move to environment variables"
allowlist:
- file: "tests/fixtures/secrets.py"
line: 10
reason: "Test fixture"
- pattern: "example.*key"
reason: "Documentation examples"
ignore_patterns:
- "example_api_key_here"
- "REPLACE_WITH_YOUR_KEY"
```
### 行内忽略
使用注释标记忽略特定行：
```
password = "test123" # secretguard:ignore
api_key = "demo_key" # sg:ignore
```
标记必须出现在注释分隔符（`#`、`//`、`/*`、`--`）之后，以防止通过字符串值滥用。
## CLI 参考
| 命令 | 描述 |
|---------|-------------|
| `secretguard scan [PATH]` | 扫描文件以查找密钥（默认：`.`） |
| `secretguard scan-history` | 扫描 git 提交历史 |
| `secretguard ml-evaluate` | 显示机器学习模型交叉验证指标 |
| `secretguard init` | 创建 `.secretguard.yml` 模板 |
| `secretguard install-hook` | 安装 git pre-commit hook |
| `secretguard uninstall-hook` | 移除 pre-commit hook |
| `secretguard hook-status` | 检查 hook 安装状态 |
| `secretguard version` | 显示版本 |
### 扫描选项
| 标志 | 描述 |
|------|-------------|
| `--format` | 输出格式：`console`, `json`, `markdown`, `html`, `sarif` |
| `--output PATH` | 将报告保存到文件 |
| `--confidence FLOAT` | 最小置信度阈值 (0.0-1.0) |
| `--exclude PATTERN` | 排除文件模式 |
| `--no-ml` | 禁用机器学习检测（速度更快） |
| `--verify` | 尝试实时凭证验证 |
| `--staged` | 仅扫描 git 暂存文件 |
| `--remediate` | 包含修复建议 |
| `--verbose` | 详细输出 |
| `--config PATH` | 自定义配置文件路径 |
| `--no-config` | 忽略配置文件 |
## 安全特性
- **密钥掩码**：报告从不包含原始密钥值（仅可见前/后 4 个字符）
- **安全权限**：报告文件以 `0o600` 权限创建（仅所有者可读/写）
- **符号链接保护**：扫描器跳过符号链接并验证解析后的路径保持在扫描目录内
- **强化的忽略机制**：`secretguard:ignore` 标记仅在注释内有效，在字符串值中无效
- **选择性验证**：实时凭证检查需要显式的 `--verify` 标志
## 路线图
SecretGuard 正在积极开发中。以下是即将推出的内容：
- **v0.9.0** — 用于 AI 代理集成（Claude Code, Cursor, Windsurf）的 MCP 服务器，Python SDK，VS Code 扩展
- **v1.0.0** — PyPI 稳定版发布，Docker 镜像，90%+ 测试覆盖率，文档站点
- **v1.1.0** — 基于 Transformer 的机器学习模型，额外的凭证验证器（Stripe, Google, Slack），自定义机器学习训练
- **v1.2.0** — 团队 Web 仪表板，策略引擎，多仓库扫描，密钥轮换辅助
- **v1.3.0** — Bitbucket/Jenkins 集成，Terraform/IaC 扫描，Jupyter Notebook 支持
## 开发
```
git clone https://github.com/adhamcybersec/secretguard.git
cd secretguard
pip install -e ".[dev]"
pytest
```
## 贡献
欢迎贡献！请先阅读我们的[贡献指南](CONTRIBUTING.md)。
1. Fork 本仓库
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开一个 Pull Request
## 许可证
MIT 许可证 - 详情请参见 [LICENSE](LICENSE)。
## 作者
**Adham Rashed**
网络安全研究员
[adhampx.com](https://adhampx.com) | [GitHub](https://github.com/adhamcybersec)
**安全提示**：SecretGuard 有助于识别密钥，但不能替代适当的密钥管理。对于生产系统，请始终使用专用解决方案（HashiCorp Vault, AWS Secrets Manager 等）。
标签：Apex, API密钥泄露, CI/CD安全, DevSecOps, Git历史扫描, Google AI, Llama, Pre-commit, Python安全工具, SARIF, 上游代理, 云安全监控, 人工智能, 代码安全, 安全助手, 对抗攻击, 敏感信息检测, 机器学习, 漏洞枚举, 熵分析, 用户模式Hook绕过, 秘密遮掩, 网络安全, 误报率降低, 逆向工具, 随机森林, 随机森林分类器, 隐私保护, 静态分析