内容
# mcp-guardian
[English](./README.md) | [한국어](./README.ko.md) | [中文](./README.zh.md) | [日本語](./README.ja.md) | [Español](./README.es.md) | [Français](./README.fr.md) | [हिन्दी](./README.hi.md) | [العربية](./README.ar.md)
---
AI 驱动的开发隐私防火墙，防止敏感信息和内部关键词在提交代码时泄露到 GitHub。
## ✨ 这是什么
**AI 编写代码。** 而且会犯错误。 例如，在提交中包含敏感信息，在远程 URL 中暴露令牌，或在 README 中写下个人信息。
一旦上传到 GitHub，**就无法撤销。** 它会被 fork、缓存，并永久保留。
`mcp-guardian` 是 **四层防护线**：
```bash
# ❌ 之前：等待 AI 犯错
AI 硬编码 API 密钥 → push → 发现 → 惊慌 → 清理历史 → 撤销令牌
# ✅ 之后：事先拦截
AI 硬编码 API 密钥 → check_files 立即拦截 → 不允许提交 → 无事故
```
**实际运作方式：**
```text
AI: "我要保存这个文件。"
→ check_files("src/config.py")
→ 🔍 扫描中...
→ ❌ 发现：OpenAI API 密钥模式（第 12 行）
→ 拦截：不允许提交
AI: "啊，谢谢。我会修改的。"
```
## 🎯 何时使用
**场景 1：AI 编写包含敏感信息的文件时**
```text
AI: "我要保存这个配置文件。"
→ check_files("config.py")
结果：
🔍 扫描结果 — 2 个文件，1 个问题
❌ config.py
第 12 行：OPENAI_API_KEY = "sk-proj-abc123..."
→ 检测到：OpenAI API 密钥模式
→ 已拦截
✅ 修改后：
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
→ ✅ 通过
```
**场景 2：提交前检查所有更改**
```bash
# 自动检查暂存文件
git add .
→ check_commit()
结果：
🔍 提交前检查 — 5 个文件
❌ README.md
第 45 行：export GH_TOKEN=ghp_abc123...
→ 检测到：GitHub PAT 模式
→ 提交被拦截
✅ 修改后再次提交：
export GH_TOKEN=$GITHUB_TOKEN
→ ✅ 提交成功
```
**场景 3：跟踪已推送的敏感信息**
```text
"啊，我好像不小心推送了一个令牌..."
→ sanitize_history()
结果：
🔍 历史记录检查 — 47 个提交
❌ 发现：1 个
提交：a1b2c3d（2 周前）
文件：.env
内容：OPENAI_API_KEY = "sk-..."
→ 从此提交中首次暴露
措施：
1. 立即撤销令牌
2. 使用 git filter-branch 清理历史记录
3. 强推（注意！）
```
**场景 4：远程 URL 中包含令牌**
```bash
git remote set-url origin https://ghp_abc123@github.com/user/repo.git
git push
→ check_remote_url()
结果：
❌ 远程 URL 中包含令牌
检测到：GitHub PAT（ghp_...）
自动修复：删除令牌后推送
✅ 修改后的 URL：
https://github.com/user/repo.git
```
## 为什么存在
AI 代理编写代码的速度比人类审查的速度快。 在提交到 GitHub 时，README 中单个的凭证或个人信息可能会成为永久的公共记录。 `mcp-guardian` 是一个防御层，在四个检查点捕获这些错误：
1. **编辑时** - `check_files` 在保存前标记敏感内容。
2. **提交时** - `check_commit` 或 pre-commit Hook 完全阻止提交。
3. **推送时** - `check_remote_url` 删除泄露到远程 URL 的 PAT。
4. **审计时** - `sanitize_history` 跟踪过去的泄露到其原始提交。
## 递归安全
服务器在其自己的 `src/mcp_guardian/patterns.py` 文件中提供自己的模式规则。 该文件被列入白名单（以及 `server.py` 和测试fixtures），因此守护程序在扫描自己的存储库时永远不会阻止自己。
## 安装
```bash
pip install mcp-guardian
```
或从源代码：
```bash
git clone https://github.com/nerin81-netizen/mcp-guardian
cd mcp-guardian
pip install -e .
```
## 连接
在 MCP 客户端配置文件中（例如 Claude Code 的 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"guardian": {
"command": "python",
"args": ["-m", "mcp_guardian.server"]
}
}
}
```
然后询问您的代理：
> "在提交之前，在此仓库上运行 `check_commit`。"
或一次性安装 OS 级别的强制措施：
```bash
mcp-guardian install-hook
```
现在，每个 `git commit` 都受到保护，即使代理忘记调用该工具。
## 规则类别
| 类别 | 捕获的示例 |
| --- | --- |
| 个人标识符 | 公司 / 项目 / 个人姓名关键词 |
| GitHub 令牌 | `ghp_…`、`gho_…`、`github_pat_…` |
| 提供商密钥 | OpenAI、Anthropic、Slack、Google、AWS |
| 通用密钥 | `api_key = "..."` 样式赋值 |
| 电子邮件地址 | 非允许的地址 |
通过 MCP 资源检查实时规则：
```
resource: config://rules
```
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE)。
