ggshield 密钥扫描器

概述

ggshield是一款命令行工具，用于检测代码库中的硬编码密钥。此 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 提交前钩子。

@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 命令行工具：通过 pip 安装

   pip install ggshield>=1.15.0
   

2. GitGuardian API 密钥：敏感信息检测所需

   • 注册：https://dashboard.gitguardian.com（免费）
   • 在设置中生成API密钥
   • 设置环境变量：

export GITGUARDIAN_API_KEY="your-api-key-here"

3. Python 3.8+：ggshield 所需版本

安装技能

clawdhub install ggshield-scanner

该技能现已可在您的Moltbot工作空间中使用。

在您的Moltbot工作空间中

启动新的Moltbot会话以启用该技能：

moltbot start
# or via messaging: @clawd list-skills

使用模式

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

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

配置

环境变量

以下是该技能正常运行所需的变量：

可选的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: 未找到命令"

ggshield未安装或不在您的PATH环境变量中。

修复方法：

pip install ggshield
which ggshield  # Should return a path

"未找到GITGUARDIAN_API_KEY"

环境变量未设置。

修复方法：

export GITGUARDIAN_API_KEY="your-key"
# For persistence, add to ~/.bashrc or ~/.zshrc:
echo 'export GITGUARDIAN_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

"401 未经授权"

API密钥无效或已过期。

修复方法：

# 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正在执行大量工作。

变通方案：

# Scan only staged changes (faster):
@clawd scan-staged

# Or specify a subdirectory:
@clawd scan-file ./app/config.py

高级主题

忽略误报

有时ggshield会标记出并非真实密钥的字符串（例如测试密钥）：

# 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：

# .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企业版，可在不向云端发送数据的情况下进行扫描：

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 上提交议题或评论
• ggshield 议题:https://github.com/GitGuardian/ggshield/issues

许可证

MIT 许可证 - 详见许可证文件

贡献者

• GitGuardian 团队
• [欢迎您的贡献！]

版本: 1.0.0最后更新: 2026年1月维护者: GitGuardian