内容
# 🔐 SecretSentry
<p align="center">
<img src="img/SecretSentry.png" alt="SecretSentry Logo" width="800"/>
</p>
<p align="center">
<b>基于管道的秘密检测，适用于任何MCP兼容编辑器。</b><br/>
即使硬编码的秘密被编码、分割、混淆或隐藏在命令替换中，也能捕获。
</p>
<p align="center">
<code>50+ 正则规则</code> · <code>35+ 提供商前缀</code> · <code>6阶段管道</code> · <code>0-100 置信度评分</code>
</p>
---
## 快速开始
```bash
# 先决条件：Python 3.10+, uv
uv run secret-sentry/server.py
```
将以下内容添加到您的MCP客户端配置中：
```json
{
"mcpServers": {
"secret-sentry": {
"command": "uv",
"args": ["run", "/path/to/secret-sentry/server.py"]
}
}
}
```
与 [Claude Desktop](https://claude.ai/download)、 [Cursor](https://cursor.sh)、 [Kiro](https://kiro.dev)、 [VS Code + Continue](https://continue.dev) 和任何 [MCP兼容](https://modelcontextprotocol.io/) 客户端兼容。
---
## 示例输出
<p align="center">
<img src="img/secretSentry_result.png" alt="SecretSentry Scan Result" width="800"/>
</p>
---
## 工具
| 工具 | 描述 |
|------|-------------|
| `scan_code` | 直接扫描代码片段 |
| `scan_file` | 按路径扫描磁盘上的文件 |
| `scan_directory` | 扫描整个项目（自动跳过二进制文件、node_modules、.git、构建目录） |
| `check_entropy` | 分析字符串的香农熵 + 前缀智能 |
---
## 工作原理
SecretSentry通过6阶段的管道运行每次扫描：
```
原始代码
→ 1. 标准化 unicode转义、十六进制转义、易混淆字符
→ 2. 解码 base64、十六进制、URL编码、链式转换（3层）、命令替换
→ 3. 重建 字符串连接、分割赋值、数组片段
→ 4. 前缀匹配 35+ 已知提供商前缀（AWS、GitHub、Stripe、Slack等）
→ 5. 正则匹配 50+ 模式规则，涵盖15+ 类别
→ 6. 评分 置信度 0-100，带噪声过滤
→ 输出 按置信度排序的表格结果
```
每个阶段都会馈送到下一个阶段 - 因此，base64编码、数组分割的Stripe密钥会被解码、重建、前缀匹配 和 正则匹配，置信度评分会反映所有信号。
---
## 检测内容
| 类别 | 示例 |
|----------|---------|
| 云密钥 | AWS（`AKIA`）、GCP（`AIza`）、Azure存储/连接字符串 |
| 版本控制系统令牌 | GitHub（`ghp_`、`gho_`、`ghu_`）、GitLab（`glpat-`） |
| 支付 | Stripe（`sk_live_`、`rk_live_`）、PayPal、Square |
| 通信 | Slack（`xoxb-`）、Discord webhook、Twilio、SendGrid、Mailgun |
| 监控 | Datadog、New Relic、Sentry DSN |
| 数据库 | MongoDB/Postgres/MySQL/Redis/AMQP连接字符串、JDBC |
| 加密 | RSA/EC/DSA/OpenSSH/PGP私钥、加密密钥 |
| 身份验证 | JWT、硬编码密码/秘密/令牌 |
| 注册表 | npm、PyPI、Docker Hub令牌 |
| Android | Manifest API密钥、BuildConfig秘密、Firebase内联配置 |
| 基础设施 | 硬编码IP地址、带有嵌入式凭证的URL |
| 混淆 | Base64/十六进制/URL编码秘密、分割字符串、命令替换 |
---
## 置信度评分
每个发现结果都会根据8个因素获得0-100的评分：
| 因素 | 影响 |
|--------|--------|
| 模式强度 | 规则特定的基准评分（15-98） |
| 熵 + 长度 | 高熵 + 长 → 强信号；低熵 + 长 → 噪声惩罚 |
| 关键词邻近度 | 靠近“password”、“secret”、“token” → 提升 |
| 上下文 | 测试文件、占位符、注释、环境变量引用 → 惩罚 |
| 噪声过滤 | 重复字符、顺序模式 → 重大惩罚 |
| 附近行 | 附近有多行与秘密相关的行 → 提升 |
| 综合信号 | 高熵 + 关键词 + 不是测试 → 额外提升 |
| 隐藏奖励 | 解码/重建秘密 → +5（混淆 = 更可疑） |
| 评分 | 严重程度 |
|-------|----------|
| 90-100 | 🚨 严重 |
| 70-89 | 🔴 高 |
| 50-69 | 🟡 中等 |
| 30-49 | 🟢 低 |
| 0-29 | ℹ️ 信息 |
结果分为**确认发现** 和 **可能候选**。评分低于15的会被抑制。
---
## 项目结构
```
secret-sentry/
├── server.py # 入口点（uv run）
├── pyproject.toml
├── README.md
├── ROADMAP.md # 漏洞扫描路线图
├── img/
└── src/secret_sentry/
├── __init__.py
├── models.py # 扫描上下文数据类
├── utils.py # 熵、掩码、帮助函数
├── pipeline.py # 6阶段编排器
├── formatter.py # 表格输出
├── server.py # MCP工具定义
└── stages/
├── normalize.py # 阶段1
├── decode.py # 阶段2
├── reconstruct.py # 阶段3
├── prefix.py # 阶段4
├── regex.py # 阶段5
└── score.py # 阶段6
```
---
## 共享/分发
```bash
# PyPI
pip install build twine && python -m build && twine upload dist/*
# 其他人使用它：
uvx secret-sentry
```
或者分享Git仓库 - 其他人克隆并指向他们的MCP配置到 `server.py`。
---
## 路线图
参见 [ROADMAP.md](ROADMAP.md) 以获取完整的漏洞扫描扩展计划。
| 状态 | 功能 |
|--------|---------|
| ✅ | 具有置信度评分的6阶段管道 |
| ✅ | 50+ 正则规则，35+ 提供商前缀 |
| ✅ | Base64/十六进制/URL解码，带3层链式转换 |
| ✅ | 字符串重建（连接、分割、数组） |
| ✅ | 命令替换模拟 |
| ✅ | 噪声过滤（重复字符、顺序模式） |
| ✅ | 模块化 `src/` 包结构 |
| 🔜 | 依赖CVE扫描（第一阶段） |
| 🔜 | 代码漏洞模式 - SQLi、XSS等（第二阶段） |
| 🔜 | 配置文件扫描 - Dockerfile、K8s、Terraform（第三阶段） |
| 📋 | 基于AST的SAST，带tree-sitter（第四阶段） |
| 📋 | 供应链和许可证检查（第五阶段） |
| 📋 | Git预提交钩子、基准/允许列表、SARIF输出 |
---
## 已知限制
- 无语义/数据流分析（无法跟踪变量跨函数）
- XOR/加密混淆绕过检测
- 单文件上下文（无跨文件跟踪）
- 命令模拟基于模式，非基于执行
## 许可证
MIT
