ggshield は、ローカル環境やCI環境で動作し、500種類以上のシークレットを検出するのに役立つCLIアプリケーションです。
ggshield は、py-gitguardian を介して当社の公開API を使用し、ファイルやその他のテキストコンテンツ内の潜在的な脆弱性をスキャンして検出します。
ggshield を使用したスキャンでは、呼び出し時刻、リクエストサイズ、スキャンモードなどのメタデータのみが保存されるため、シークレットがダッシュボードに表示されることはなく、ファイルやシークレットが保存されることもありません。
ggshield をインストールする最も簡単な方法です。
Linux / macOS:
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
または、curl (Windows 10+ にバンドル) を使用する場合:
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
このスクリプトは --instance や --plugin (プラグインのインストール) などのオプションを受け付けます。EUワークスペースやセルフホストインスタンスの場合は、実行前に GITGUARDIAN_INSTANCE 環境変数を設定するか、--instance <URL> を渡してください。
オプションの全リスト、他のインストール方法、アンインストール方法については、scripts/install/README.md を参照してください。
以下の方法は、代わりにCLIを手動でインストールします。
Homebrew を使用して ggshield をインストールできます:
brew install ggshield
アップグレードは Homebrew によって処理されます。
または、ggshield リリースページ からスタンドアロンの .pkg パッケージをダウンロードしてインストールすることもできます。
このパッケージは Python のインストールを必要としませんが、新しいバージョンを手動でダウンロードする必要があります。
Deb パッケージと RPM パッケージは Cloudsmith で入手できます。
セットアップ手順:
アップグレードはパッケージマネージャーによって処理されます。
ggshield は Chocolatey パッケージマネージャー から入手できます:
choco install ggshield
ggshield リリースページ から MSI インストーラーをダウンロードしてインストールします:
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
ggshield リリースページ でスタンドアロンの .zip アーカイブを提供しています。
アーカイブをディスクに解凍し、ggshield.exe ファイルを含むディレクトリを %PATH% に追加します。
このアーカイブは Python のインストールを必要としませんが、新しいバージョンを手動でダウンロードする必要があります。
ggshield は、サポートされているすべてのオペレーティングシステムに PyPI パッケージ を介してインストールできます。
サポートされているバージョンの Python (EOL ではないもの) と git が必要です (スタンドアロンパッケージを除く)。
パッケージ版の ggshield を使用しない場合は、Python リリースサイクル に従っており、EOL に達したバージョンはサポートしていないことに注意してください。
PyPI から ggshield をインストールする推奨方法は pipx を使用することです。これにより、隔離された環境にインストールされます:
pipx install ggshield
インストールをアップグレードするには、以下を実行します:
pipx upgrade ggshield
pip を使用して PyPI から ggshield をインストールすることもできますが、インストールが隔離されていないため、他のアプリケーションやパッケージが ggshield のインストールに影響を与える可能性があるため、推奨されません。この方法は、Python インストールが外部管理として宣言されている場合 (例: Debian 12 などのオペレーティングシステムでシステム Python を使用している場合) は機能しません:
pip install --user ggshield
インストールをアップグレードするには、以下を実行します:
pip install --user --upgrade ggshield
ggshield auth login を使用するggshield を使用するには、GitGuardian サーバーに対して認証を行う必要があります。そのためには、ggshield auth login コマンドを使用します。このコマンドは、個人アクセストークンのプロビジョニングと、ローカルワークステーションへの設定を自動化します。
詳細については、ggshield auth login ドキュメント を参照してください。
個人アクセストークンを手動で作成し、GITGUARDIAN_API_KEY 環境変数に保存して設定を完了することもできます。
これで ggshield を使用してシークレットを検索できるようになりました:
ggshield secret scan path -r .ggshield secret scan repo .docker コマンドが必要): ggshield secret scan docker ubuntu:22.04pip コマンドが必要): ggshield secret scan pypi flaskggshield secret scan --help の出力を確認してください。ggshield が .gitguardian.yaml (または .gitguardian.yml) 設定ファイルが非推奨の形式を使用していると報告した場合は、次のコマンドで最新バージョンに移行します:
ggshield config migrate
デフォルトでは、現在のディレクトリ内の設定ファイルを検索するため、ファイルが置かれているディレクトリから実行してください。任意の場所から実行するには、ggshield にファイルを明示的に指定します:
ggshield --config-path path/to/.gitguardian.yaml config migrate
ファイルの以前のバージョンは、その隣に .old バックアップとして保持されます。
ggshield を CI/CD ワークフロー に統合できます。
エラーを早期に検出するには、ggshield を pre-commit、pre-push、または pre-receive Git フック として使用します。
ggshield は、ユーザーと AI コーディングアシスタントの間のインタラクションをリアルタイムでスキャンし、シークレットを含むアクションが実行される前にブロックできます。
フックは ggshield install コマンドでインストールできます。
サポートされているツール: Cursor、Claude Code、Copilot Chat、Codex。
詳細については、ドキュメント をご覧ください。
シークレットが見つからなかった場合、終了コードは 0 になります:
ggshield secret scan pre-commit
ステージングされたコードまたは CI でシークレットが見つかった場合、シークレットが見つかったファイル名と、ファイル内のシークレットの位置を示すパッチを含むアラートが表示されます:
ggshield secret scan pre-commit
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
長すぎる行は、verbose モード (-v または --verbose) を使用しない限り、端末のサイズに合わせて切り詰められます。
ggshield は MIT ライセンスの下で提供されています。