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 替代。