GitGuardian ggshield

ggshield：GitGuardian でコードを保護

重要

macOS：1.54.0 にアップグレードすると、ggshield-py の Keychain プロンプトが表示されます。これは、パフォーマンス改善の一環として、保存済みのトークンを読み取るようになった2つ目のバイナリです。常に許可をクリックしてください。再度尋ねられることはありません。

ggshield は、ローカル環境または CI 環境で実行され、500 種類以上のシークレットの検出を支援する CLI アプリケーションです。

ggshield は、py-gitguardian を介して公開 APIを使用し、ファイルやその他のテキストコンテンツをスキャンして潜在的な脆弱性を検出します。

ggshield を使用したスキャンでは、呼び出し時刻、リクエストサイズ、スキャンモードなどのメタデータのみが保存されるため、シークレットがダッシュボードに表示されることはなく、ファイルやシークレットが保存されることもありません。

目次

• インストール
  • インストールスクリプト（推奨）
  • macOS
    • Homebrew
    • スタンドアロン .pkg パッケージ
  • Linux
    • Deb および RPM パッケージ
  • Windows
    • Chocolatey
    • MSI インストーラー
    • スタンドアロン .zip アーカイブ
  • すべてのオペレーティングシステム
    • pipx を使用
    • pip を使用
• 初期設定
  • ggshield auth login を使用
  • 手動設定
• はじめに
  • シークレット
  • レガシー設定ファイルの移行
• インテグレーション
  • AI コーディングアシスタント
• 詳細情報
• 出力
• 関連するオープンソースプロジェクト
• ライセンス

インストール

インストールスクリプト（推奨）

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 を手動でインストールします。

macOS

Homebrew

Homebrew を使用して ggshield をインストールできます。

brew install ggshield

アップグレードは Homebrew によって処理されます。

スタンドアロン .pkg パッケージ

または、ggshield のリリースページからスタンドアロンの .pkg パッケージをダウンロードしてインストールできます。

このパッケージのインストールに Python は不要ですが、新しいバージョンは手動でダウンロードする必要があります。

Linux

Deb および RPM パッケージ

Deb および RPM パッケージは Cloudsmith で入手できます。

セットアップ手順：

• Deb パッケージ
• RPM パッケージ

アップグレードはパッケージマネージャーによって処理されます。

Windows

Chocolatey

ggshield は Chocolatey パッケージマネージャーから入手できます。

choco install ggshield

MSI インストーラー

ggshield のリリースページから MSI インストーラーをダウンロードして、インストールします。

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi

単体の .zip アーカイブ

ggshield のリリースページで、単体の .zip アーカイブを提供しています。

アーカイブをディスク上に展開し、ggshield.exe ファイルを含むディレクトリを %PATH% に追加します。

このアーカイブでは Python のインストールは_不要_ですが、新しいバージョンを手動でダウンロードする必要があります。

すべてのオペレーティングシステム

ggshield は、PyPI パッケージを使って、サポート対象のすべてのオペレーティングシステムにインストールできます。

サポート対象の Python バージョン（EOL に達していないもの）（単体パッケージを除く）と git が必要です。

ggshield のパッケージ版を使用しない場合は、Python のリリースサイクルに従っており、EOL に達したバージョンはサポートしていないことにご注意ください。

pipx を使用する

PyPI から ggshield をインストールする際は、pipx の使用をおすすめします。pipx を使うと、分離された環境にインストールできます。

pipx install ggshield

インストールをアップグレードするには、次を実行します。

pipx upgrade ggshield

pip を使用する

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 のドキュメントをご覧ください。

認証後、ggshield machine setup を実行して AI と git フックを設定し、 ハニートークンを設置して、最初のスキャンの前にマシンを Endpoints ページに 登録します。登録には、現在のユーザー、または root として実行する場合は すべてのハニートークン対象ユーザーが含まれます。登録はベストエフォートで 行われ、最大 5 秒かかります。また、コマンドの終了コードには影響しません。

ggshield secret scan pre-commit、pre-push、ai-hook のスキャンでも、 マシンのホスト名が送信されます。GitGuardian はこのホスト名から、これらの フックのユーザーを登録します。他のスキャンコマンドではホスト名は送信されず、 単体インストールおよびプラットフォーム固有の pip インストールで実行される ネイティブ AI フックもホスト名を送信しません。

CI では、ggshield はマシンを登録せず、ホスト名も送信しません。ほかの環境で 両方を無効にするには、.gitguardian.yaml で endpoint_registration: false を 設定するか、GGSHIELD_NO_ENDPOINT_REGISTRATION に空でない値を設定します。

手動セットアップ

個人用アクセストークンを手動で作成し、セットアップを完了するために環境変数 GITGUARDIAN_API_KEY に保存することもできます。

使ってみる

シークレット

ggshield を使用して、以下の場所にあるシークレットを検索できます。

• ファイル内：ggshield secret scan path -r .
• リポジトリ内：ggshield secret scan repo .
• Docker イメージ内（docker コマンドが使用可能である必要があります）：ggshield secret scan docker ubuntu:22.04
• Pypi パッケージ内（pip コマンドが使用可能である必要があります）：ggshield secret scan pypi flask
• その他については、詳細を確認するために ggshield secret scan --help の出力をご覧ください。

レガシー設定ファイルの移行

.gitguardian.yaml（または .gitguardian.yml）設定ファイルで非推奨の形式が使われていると ggshield が報告した場合は、次のコマンドで最新バージョンに移行してください。

ggshield config migrate

デフォルトでは、現在のディレクトリ内の設定ファイルが検索されるため、ファイルを含むディレクトリから実行してください。任意の場所から実行するには、ggshield にファイルを明示的に指定します。

ggshield --config-path path/to/.gitguardian.yaml config migrate

以前のバージョンのファイルは、同じ場所に .old バックアップとして保存されます。

インテグレーション

CI/CD ワークフローに ggshield を統合できます。

エラーを早期に検出するには、ggshield をpre-commit、pre-push、または pre-receive Git フックとして使用してください。

AI コーディングアシスタント

ggshield は、あなたと AI コーディングアシスタントとのやり取りをリアルタイムでスキャンし、シークレットを含むアクションが実行される前にブロックできます。

ggshield install コマンドでフックをインストールできます。

対応ツール：Cursor、Claude Code、Copilot Chat、Codex、 Mistral Vibe 2.21+。

詳細情報

詳しくは、ドキュメントをご覧ください。

出力

シークレットが見つからない場合、終了コードは 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 | }

-v または --verbose で詳細モードを使用しない限り、長すぎる行はターミナルのサイズに合わせて切り詰められます。

関連するオープンソースプロジェクト

• truffleHog
• gitleaks
• gitrob
• git-hound
• AWS git-secrets
• detect-secrets

ライセンス

ggshield は MIT ライセンスです。