名称： ggshield-scanner
描述： 在硬编码的密钥（API 密钥、凭证、令牌）泄露到 git 之前，检测 500 多种类型。封装了 GitGuardian 的 ggshield CLI。
主页： https://github.com/GitGuardian/ggshield-skill
元数据：
clawdbot:
requires:
bins: ["ggshield"]
env: ["GITGUARDIAN_API_KEY"]

ggshield 密钥扫描器

概述

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

输出示例（无问题）：

🔍 正在扫描仓库...
✅ 仓库干净：已扫描 1,234 个文件，未发现密钥

输出示例（检测到问题）：

❌ 发现 2 个密钥：

- config/prod.py:42 处的 AWS 访问密钥 ID
- .env.backup:8 处的 Slack API 令牌

使用 'ggshield secret ignore --last-found' 忽略，或将其移除。

2. scan-file

扫描单个文件以查找密钥。

@clawd scan-file /path/to/config.py

3. scan-staged

仅扫描已暂存的 git 更改（适用于提交前检查）。

@clawd scan-staged

此命令仅对您 git add 过的更改运行（速度很快！）。

4. install-hooks

将 ggshield 安装为 git 提交前钩子。

@clawd install-hooks

安装后，每次提交都会自动扫描：

$ git commit -m "添加配置"
🔍 正在运行 ggshield 提交前钩子...
❌ 检测到密钥！提交被阻止。
请移除密钥后重试。

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 所需

安装技能

clawdhub install ggshield-scanner

现在该技能已在您的 Moltbot 工作区中可用。

在 Moltbot 工作区中

启动一个新的 Moltbot 会话以加载此技能：

moltbot start
# 或通过消息：@clawd list-skills

使用模式

模式 1：推送前（安全检查）

开发者：@clawd scan-repo .
Moltbot：✅ 仓库干净。可以推送！

开发者：git push

模式 2：审计现有仓库

开发者：@clawd scan-repo ~/my-old-project
Moltbot：❌ 在历史记录中发现 5 个密钥！
         - config/secrets.json 中的 AWS 密钥
         - docker-compose.yml 中的数据库密码
         - .env.example 中的 Slack webhook
Moltbot：建议：立即轮换这些凭证。
         考虑使用 git-filter-repo 将其从历史记录中移除。

模式 3：提交前强制检查

开发者：@clawd install-hooks
Moltbot：✅ 已安装提交前钩子

开发者：echo "SECRET_TOKEN=xyz" > config.py
开发者：git add config.py
开发者：git commit -m "添加配置"
Moltbot：❌ 提交前钩子检测到密钥！
开发者：rm config.py && git reset
开发者：（将配置添加到 .gitignore 和环境变量中）
开发者：git commit -m "添加配置" # 现在可以了！

模式 4：Docker 镜像安全

开发者：@clawd scan-docker my-api:v1.2.3
Moltbot：✅ Docker 镜像干净

配置

环境变量

这些是技能运行所必需的：

可选的 ggshield 配置

创建 ~/.gitguardian/.gitguardian.yml 以进行持久化设置：

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 中。

修复：

pip install ggshield
which ggshield  # 应返回一个路径

"GITGUARDIAN_API_KEY not found"

环境变量未设置。

修复：

export GITGUARDIAN_API_KEY="your-key"
# 如需持久化，添加到 ~/.bashrc 或 ~/.zshrc：
echo 'export GITGUARDIAN_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

"401 Unauthorized"

API 密钥无效或已过期。

修复：

# 测试 API 密钥
ggshield auth status

# 如果无效，请在 https://dashboard.gitguardian.com → API Tokens 重新生成
# 然后：export GITGUARDIAN_API_KEY="new-key"

"在大型仓库上速度慢"

扫描 50GB 的单体仓库需要时间。ggshield 正在执行大量工作。

变通方案：

# 仅扫描暂存的更改（更快）：
@clawd scan-staged

# 或指定子目录：
@clawd scan-file ./app/config.py

高级主题

忽略误报

有时 ggshield 会标记一个并非密钥的字符串（例如，测试密钥）：

# 忽略最后发现的密钥
ggshield secret ignore --last-found

# 忽略文件中的所有密钥
ggshield secret ignore --path ./config-example.py

这将创建包含忽略规则的 .gitguardian/config.json。

与 CI/CD 集成

您可以将密钥扫描添加到 GitHub Actions / GitLab CI：

# .github/workflows/secret-scan.yml
名称： 密钥扫描
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 企业版，您可以在不将数据发送到云端的情况下进行扫描：

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