OpenClaw ggshield Scanner 技能指南

OpenClaw ggshield Scanner 技能概述

ggshield Scanner 技能将 GitGuardian 强大的密钥检测引擎引入你的 OpenClaw 工作流。无需记忆 ggshield CLI 的各种参数和输出格式，你可以用自然语言让 OpenClaw 扫描代码中的泄露密钥。

ggshield 能检测超过 500 种硬编码密钥——API 密钥、数据库凭证、云服务令牌、私钥等。OpenClaw ggshield scanner 技能将这些能力封装成对话式交互，让你轻松按需执行扫描、设置 pre-commit 钩子、解读扫描结果，全程无需离开开发流程。

典型工作流程：

1. 让 OpenClaw 扫描你的项目中是否存在密钥泄露。
2. Agent 针对你的代码库或指定文件运行 ggshield secret scan。
3. 结果以可读的摘要形式返回，高亮显示检测到的密钥、类型和位置——无需手动解析 CLI 输出。

无论是审计现有仓库还是为开发流程添加密钥扫描，这个技能都能帮你完成。搭配 1Password 技能使用，打造完整的密钥管理工作流。

ggshield Scanner 技能安装前的准备

在安装 ggshield Scanner 技能之前，请确保你已准备好：

• OpenClaw 已安装并运行（v1.0+）
• ggshield 已安装——官方安装指南
• Python 3.9+（如果通过 pip/pipx 安装）或使用独立安装包
• Git 已安装，用于仓库扫描
• clawhub CLI 已安装，用于技能管理——安装指南

使用你偏好的方式安装 ggshield：

# macOS (Homebrew)
brew install gitguardian/tap/ggshield

# 所有平台 (pipx — 推荐)
pipx install ggshield

# 所有平台 (pip)
pip install --user ggshield

验证安装：

ggshield --version

如何安装 ggshield Scanner 技能

使用一条命令安装 ggshield Scanner 技能：

npx clawhub@latest install ggshield-scanner

验证安装结果：

clawhub list

你应该能在已安装技能列表中看到 ggshield-scanner。该技能需要 ggshield 在你的 PATH 中可用。

ggshield Scanner 技能配置指南

GitGuardian 认证

ggshield Scanner 技能需要 GitGuardian API 密钥来进行密钥检测。你可以通过两种方式认证：

交互式登录（推荐用于本地开发）：

ggshield auth login

这会打开浏览器并自动生成个人访问令牌（PAT）。

环境变量（推荐用于 CI/CD）：

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

环境变量配置

| 变量 | 是否必需 | 说明 | |------|---------|------| | GITGUARDIAN_API_KEY | 是 | GitGuardian 个人访问令牌 | | GITGUARDIAN_INSTANCE | 否 | 自托管 GitGuardian 实例的 URL |

重要提示： 不要将 API 密钥硬编码在配置文件中。使用环境变量或密钥管理器，如 1Password 或 Bitwarden。

Pre-commit 钩子设置

在密钥提交前进行拦截：

# 为当前仓库安装钩子
ggshield install --mode local

# 为所有仓库全局安装钩子
ggshield install --mode global

ggshield Scanner 技能使用示例

1. 扫描项目目录中的密钥

你： "扫描我的项目目录，检查是否有硬编码的密钥"

Agent 运行 ggshield secret scan path -r . 扫描你的工作目录，返回检测到的密钥摘要，包括文件路径、行号和密钥类型。如果没有发现密钥，你会收到一份确认代码安全的报告。

2. 审计 Git 仓库历史

你： "检查我的整个 git 历史中是否有泄露的密钥"

Agent 运行 ggshield secret scan repo . 扫描仓库中的所有提交。这对于审计旧代码库或确保之前提交的密钥已被正确轮换和移除非常有用。

3. 部署前扫描 Docker 镜像

你： "扫描 nginx:latest Docker 镜像中是否有密钥"

Agent 执行 ggshield secret scan docker nginx:latest 检查 Docker 镜像的所有层。这可以捕获在构建过程中被打包进容器镜像的密钥——这是生产环境中凭证泄露的常见来源。

4. 设置 Pre-commit 保护

你： "安装一个 pre-commit 钩子来阻止密钥被提交"

Agent 运行 ggshield install --mode local 为你的仓库添加 git pre-commit 钩子。之后每次提交都会自动扫描，包含密钥的提交会在进入仓库前被拦截。

安全与最佳实践

使用 ggshield Scanner 技能时，请遵循以下安全准则：

• 默认使用只读扫描。 该技能应仅扫描和报告——避免在未仔细审查每个发现的情况下自动修复。
• 确认前先审查。 当 Agent 建议移除或轮换检测到的密钥时，先验证发现是否为真阳性。
• 立即轮换暴露的密钥。 如果 ggshield 在仓库历史中检测到真实密钥，请立即轮换凭证——仅删除提交是不够的。
• 启用 pre-commit 钩子。 预防优于检测。使用 ggshield install 设置钩子，在密钥进入版本控制前拦截。
• 保持 ggshield 更新。 新的密钥检测模式会定期添加。运行 pipx upgrade ggshield 或 brew upgrade ggshield 保持最新。

常见错误与故障排除

"Error: Invalid API key"

GitGuardian API 密钥缺失或已过期。使用 ggshield auth login 重新认证，或验证 GITGUARDIAN_API_KEY 环境变量设置是否正确。在 GitGuardian 控制台中检查令牌是否已被撤销。

"Error: ggshield command not found"

ggshield 未安装或不在 PATH 中。使用 pipx install ggshield 或 brew install gitguardian/tap/ggshield 安装。如果通过 pip 安装，确保 Python 脚本目录在 PATH 中。

"Error: Docker is not available"

Docker 镜像扫描需要运行中的 Docker 守护进程。启动 Docker Desktop 或 Docker 服务后重试。如果只需扫描源代码，使用 ggshield secret scan path 或 ggshield secret scan repo 替代。