ggshield-scanner

用途

ggshield-scanner 是一个将 GitGuardian 的 ggshield CLI 封装为 AI 智能体技能的密钥扫描工具，用于在硬编码密钥（API Key、凭证、令牌等）泄露到 git 仓库之前将其检测出来。

所谓“密钥”，指不应被提交到版本控制系统的敏感凭证，包括：AWS Access Key、GCP Service Account、Azure 凭证；API 令牌（GitHub、Slack、Stripe 等）；数据库密码与连接字符串；私有加密密钥与证书；OAuth 令牌与刷新令牌；PayPal/Stripe API Key；邮件服务器凭证等。单个泄露的密钥可能导致基础设施被入侵、产生高额云账单、暴露客户数据（违反 GDPR/CCPA）以及触发安全事件与审计。

主要能力

该技能提供以下命令：

scan-repo：扫描整个 git 仓库（包括历史记录）中的密钥。 @clawd scan-repo /path/to/my/project 输出示例：✅ Repository clean: 1,234 files scanned, 0 secrets found；检测到问题时列出密钥类型与文件位置，并提示可用 ggshield secret ignore --last-found 忽略或移除。
scan-file：扫描单个文件。 @clawd scan-file /path/to/config.py
scan-staged：仅扫描已暂存的 git 变更，适合 pre-commit 检查，速度较快。 @clawd scan-staged
install-hooks：将 ggshield 安装为 git pre-commit 钩子。安装后每次提交都会自动扫描，检测到密钥时阻止提交。 @clawd install-hooks
scan-docker：扫描 Docker 镜像各层中的密钥。 @clawd scan-docker my-app:latest

使用方式

前置条件

安装 ggshield CLI：pip install ggshield>=1.15.0
获取 GitGuardian API Key：在 https://dashboard.gitguardian.com 注册（免费），在 Settings 中生成 API Key，并设置环境变量： export GITGUARDIAN_API_KEY="your-api-key-here"
Python 3.8+（ggshield 要求）

安装技能

clawdhub install ggshield-scanner

安装后技能在 Moltbot 工作区可用。启动新会话以加载技能：moltbot start，或通过消息 @clawd list-skills 查看。

典型使用模式

推送前安全检查：@clawd scan-repo .，确认干净后再 git push。
审计已有仓库：@clawd scan-repo ~/my-old-project，若发现历史中的密钥，建议立即轮换凭证，并考虑用 git-filter-repo 从历史中移除。
提交前强制拦截：@clawd install-hooks 后，含密钥的提交会被阻止，需移除密钥（改用 .gitignore 与环境变量）后重新提交。
Docker 镜像安全：@clawd scan-docker my-api:v1.2.3。

配置

必需环境变量：

GITGUARDIAN_API_KEY：来自 https://dashboard.gitguardian.com，建议写入 ~/.bashrc 或 ~/.zshrc。
GITGUARDIAN_ENDPOINT：默认 https://api.gitguardian.com，通常无需设置。

可选配置文件 ~/.gitguardian/.gitguardian.yml，例如：

verbose: false
output-format: json
exit-code: true

隐私与安全

发送给 GitGuardian 的数据仅为元数据：密钥模式的哈希（非实际密钥）、文件相对路径、行号。不会发送实际密钥或凭证、文件内容、私钥、凭证。GitGuardian 企业版客户可使用本地部署扫描，不向任何地方发送数据。

密钥检测方式包括：基于熵的检测（识别高熵随机令牌）、模式匹配（已知密钥格式，如 AWS key 前缀）、公开 CVE 交叉引用、基于泄露密钥数据库训练的机器学习。

适用场景

开发者推送代码前的安全检查
对已有仓库进行密钥审计（含历史记录）
通过 pre-commit 钩子实现提交前强制拦截
Docker 镜像安全扫描
集成到 CI/CD（如 GitHub Actions / GitLab CI）中自动扫描
企业本地部署扫描（GitGuardian Enterprise）

限制与注意事项

需要 GitGuardian API Key 才能进行密钥检测。
大型仓库（如 50GB monorepo）扫描较慢，可改用 scan-staged 或指定子目录/单文件。
可能产生误报（如测试密钥），可用 ggshield secret ignore --last-found 或 ggshield secret ignore --path ./config-example.py 忽略，忽略规则写入 .gitguardian/config.json。
常见问题：ggshield: command not found（未安装或不在 PATH）；GITGUARDIAN_API_KEY not found（环境变量未设置）；401 Unauthorized（API Key 无效或过期，可用 ggshield auth status 测试并重新生成）。

技能介绍

用途