介绍
# ggshield Secret Scanner
## 概述
**ggshield** 是一个用于检测代码库中硬编码密钥的 CLI 工具。该 Moltbot 技能为您的 AI 代理带来了密钥扫描功能。
### 什么是“密钥”？
密钥是不应提交到版本控制中的敏感凭据： - AWS 访问密钥、GCP 服务帐户、Azure 凭据 - API 令牌（GitHub、Slack、Stripe 等） - 数据库密码和连接字符串 - 私有加密密钥和证书 - OAuth 令牌和刷新令牌 - PayPal/Stripe API 密钥 - 电子邮件服务器凭据
### 为什么这很重要
单个泄露的密钥可能导致： - 🔓 基础设施被入侵 - 💸 产生巨额云账单（攻击者滥用您的 AWS 帐户） - 📊 客户数据泄露（违反 GDPR/CCPA） - 🚨 引发安全事件和审计
ggshield 会在密钥到达您的仓库**之前**拦截它们。
## 功能
### 可用命令
#### 1. `scan-repo` 扫描整个 git 仓库中的密钥（包括历史记录）。
``` @clawd scan-repo /path/to/my/project ```
**输出**： ``` 🔍 Scanning repository... ✅ Repository clean: 1,234 files scanned, 0 secrets found ```
**检测到时的输出**： ``` ❌ Found 2 secrets:
- AWS Access Key ID in config/prod.py:42 - Slack API token in .env.backup:8
Use 'ggshield secret ignore --last-found' to ignore, or remove them. ```
#### 2. `scan-file` 扫描单个文件中的密钥。
``` @clawd scan-file /path/to/config.py ```
#### 3. `scan-staged` 仅扫描已暂存的 git 更改（作为提交前检查很有用）。
``` @clawd scan-staged ```
这仅对您 `git add` 的更改运行（速度很快！）。
#### 4. `install-hooks` 将 ggshield 安装为 git pre-commit hook。
``` @clawd install-hooks ```
安装后，每次提交都会自动扫描： ``` $ git commit -m "Add config" 🔍 Running ggshield pre-commit hook... ❌ Secrets detected! Commit blocked. Remove the secrets and try again. ```
#### 5. `scan-docker` 扫描 Docker 镜像各层中的密钥。
``` @clawd scan-docker my-app:latest ```
## 安装
### 前置条件
1. **ggshield CLI**：通过 pip 安装 ```bash pip install ggshield>=1.15.0 ```
2. **GitGuardian API 密钥**：进行密钥检测所必需 - 注册：https://dashboard.gitguardian.com （免费） - 在设置中生成 API 密钥 - 设置环境变量：
```bash export GITGUARDIAN_API_KEY="your-api-key-here" ```
3. **Python 3.8+**：ggshield 所必需
### 安装技能
```bash clawdhub install ggshield-scanner ```
该技能现在已在您的 Moltbot 工作区中可用。
### 在您的 Moltbot 工作区中
启动一个新的 Moltbot 会话以加载该技能：
```bash moltbot start # or via messaging: @clawd list-skills ```
## 使用模式
### 模式 1：推送前（安全检查）
``` Dev: @clawd scan-repo . Moltbot: ✅ Repository clean. All good to push!
Dev: git push ```
### 模式 2：审计现有仓库
``` Dev: @clawd scan-repo ~/my-old-project Moltbot: ❌ Found 5 secrets in history! - AWS keys in config/secrets.json - Database password in docker-compose.yml - Slack webhook in .env.example Moltbot: Recommendation: Rotate these credentials immediately. Consider using git-filter-repo to remove from history. ```
### 模式 3：提交前强制执行
``` Dev: @clawd install-hooks Moltbot: ✅ Installed pre-commit hook
Dev: echo "SECRET_TOKEN=xyz" > config.py Dev: git add config.py Dev: git commit -m "Add config" Moltbot: ❌ Pre-commit hook detected secret! Dev: rm config.py && git reset Dev: (add config to .gitignore and to environment variables instead) Dev: git commit -m "Add config" # Now works! ```
### 模式 4：Docker 镜像安全
``` Dev: @clawd scan-docker my-api:v1.2.3 Moltbot: ✅ Docker image clean ```
## 配置
### 环境变量
这些是该技能工作所必需的：
| 变量 | 值 | 设置位置 | | :-- | :-- | :-- | | `GITGUARDIAN_API_KEY` | 您从 https://dashboard.gitguardian.com 获取的 API 密钥 | `~/.bashrc` 或 `~/.zshrc` | | `GITGUARDIAN_ENDPOINT` | `https://api.gitguardian.com` （默认，可选） | 通常不需要 |
### 可选的 ggshield 配置
创建 `~/.gitguardian/.gitguardian.yml` 以进行持久化设置：
```yaml verbose: false output-format: json exit-code: true ```
详情请见：https://docs.gitguardian.com/ggshield-docs/
## 隐私与安全
### 发送给 GitGuardian 的数据是什么？
✅ **仅发送元数据**：
- 密钥模式的哈希值（而非实际密钥） - 文件路径（仅限相对路径） - 行号
❌ **从不发送**：
- 您的实际密钥或凭据 - 文件内容 - 私有密钥 - 凭据
**参考**：GitGuardian 企业版客户可以使用本地部署扫描，不向任何地方发送数据。
### 如何检测密钥
ggshield 使用：
1. **基于熵的检测**：识别高熵字符串（随机令牌） 2. **模式匹配**：查找已知的密钥格式（AWS 密钥前缀等） 3. **公共 CVE**：交叉引用已披露的密钥 4. **机器学习**：基于泄露密钥数据库进行训练
## 故障排除
### “ggshield: command not found”
ggshield 未安装或未在您的 PATH 中。
**修复**：
```bash pip install ggshield which ggshield # Should return a path ```
### “GITGUARDIAN_API_KEY not found”
环境变量未设置。
**修复**：
```bash export GITGUARDIAN_API_KEY="your-key" # For persistence, add to ~/.bashrc or ~/.zshrc: echo 'export GITGUARDIAN_API_KEY="your-key"' >> ~/.bashrc source ~/.bashrc ```
### “401 Unauthorized”
API 密钥无效或已过期。
**修复**：
```bash # Test the API key ggshield auth status
# If invalid, regenerate at https://dashboard.gitguardian.com → API Tokens # Then: export GITGUARDIAN_API_KEY="new-key" ```
### “在大型仓库上速度慢”
扫描 50GB 的单体仓库需要时间。ggshield 正在进行大量工作。
**变通方法**：
```bash # Scan only staged changes (faster): @clawd scan-staged
# Or specify a subdirectory: @clawd scan-file ./app/config.py ```
## 高级主题
### 忽略误报
有时 ggshield 会标记一个非密钥的字符串（例如测试密钥）：
```bash # Ignore the last secret found ggshield secret ignore --last-found
# Ignore all in a file ggshield secret ignore --path ./config-example.py ```
这会创建带有忽略规则的 `.gitguardian/config.json`。
### 集成到 CI/CD
您可以将密钥扫描添加到 GitHub Actions / GitLab CI：
```yaml # .github/workflows/secret-scan.yml name: Secret Scan on: [push] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: pip install ggshield - run: ggshield secret scan repo . env: GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }} ```
### 企业版：本地部署扫描
如果您的公司使用 GitGuardian 企业版，您可以在不向云端发送数据的情况下进行扫描：
```bash export GITGUARDIAN_ENDPOINT="https://your-instance.gitguardian.com" export GITGUARDIAN_API_KEY="your-enterprise-key" ```
## 相关资源
- **ggshield 文档**：https://docs.gitguardian.com/ggshield-docs/ - **GitGuardian 仪表板**：https://dashboard.gitguardian.com （查看发现的所有密钥） - **Moltbot 技能**：https://docs.molt.bot/tools/clawdhub - **密钥管理最佳实践**：https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
## 支持
- **错误报告**：https://github.com/GitGuardian/ggshield-skill/issues - **问题**：在 ClawdHub 上提交 issue 或评论 - **ggshield 问题**：https://github.com/GitGuardian/ggshield/issues
## 许可证
MIT 许可证 - 请参阅 LICENSE 文件
## 贡献者
- GitGuardian 团队 - [欢迎您的贡献！]
---
**版本**：1.0.0 **最后更新**：2026 年 1 月 **维护者**：GitGuardian