シークレット スキャンのカスタム パターンの定義

1 つまたは複数の正規表現を生成することで、secret scanning の機能を拡張する独自のカスタム パターンを定義できます。

この機能を使用できるユーザーについて

Secret scanningは組織が所有するリポジトリに利用できます。 詳細については、「シークレット スキャンについて」と「GitHub Advanced Security について」を参照してください。

この記事の内容

secret scanningのカスタムパターンについて

カスタム パターンを定義して、secret scanning でサポートされているデフォルトのパターンで検出されないシークレットを特定できます。 たとえば、Organizationの内部的なシークレットのパターンを持っていることもあるかもしれません。 サポートされるシークレットとサービス プロバイダーの詳細については、「secret scanning パターン」を参照してください。

Enterprise、Organization、またはリポジトリのカスタム パターンを定義できます。 Secret scanning では、Organization または Enterprise アカウントごとに最大 500 個のカスタム パターン、およびリポジトリごとに最大 100 個のカスタム パターンがサポートされます。

カスタム パターンのプッシュ保護を有効にすることもできます。 プッシュ保護の詳細については、「リポジトリと Organization のプッシュ保護」を参照してください。

カスタム パターンに正規表現を使用する方法について

secret scanning のカスタム パターンを 1 つまたは複数の正規表現として指定できます。

Secret scanning では Hyperscan ライブラリが使用され、PCRE 構文のサブセットである Hyperscan の正規コンストラクトのみがサポートされます。 Hyperscanのオプション修飾子はサポートされません。 Hyperscan パターン コンストラクトの詳細については、Hyperscan ドキュメントの「パターンのサポート」を参照してください。

UI の [その他のオプション ] セクションは、正規表現を手動で記述するのに役立ちます。

  • シークレット形式: シークレット自体の形式を記述する式。
  • シークレットの前: シークレットの前にある文字を記述する式。 既定では、これは \A|[^0-9A-Za-z] に設定されます。これは、シークレットが行の先頭にあるか、前に英数字以外の文字を付ける必要があることを意味します。
  • シークレットの後: シークレットの後に来る文字を記述する式。 既定では、これは \z|[^0-9A-Za-z] に設定されます。これは、シークレットの後に新しい行または英数字以外の文字が続く必要があることを意味します。
  • 追加の一致要件: シークレット自体が一致しなければならない、または一致してはならない 1 つまたは複数の省略可能な式。

単純なトークンの場合、通常はシークレット形式のみを指定する必要があります。 他のフィールドでは柔軟性が提供されるため、複雑な正規表現を作成せずに、より複雑なシークレットを指定できます。 カスタム パターンの例については、以下の「追加の要件を使用して指定されたカスタム パターンの例」を参照してください。

リポジトリのカスタムパターンの定義

カスタムパターンを定義する前に、リポジトリでsecret scanningが有効化されていることを確認しておかなければなりません。 詳しくは、「リポジトリのシークレット スキャンの構成」を参照してください。

  1. お使いの GitHub Enterprise Server インスタンス で、リポジトリのメイン ページへ移動します。

  2. リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

    タブを示すリポジトリ ヘッダーのスクリーンショット。 [設定] タブが濃いオレンジ色の枠線で強調表示されています。

  3. サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。

  4. [コードのセキュリティと分析] の下で、「GitHub Advanced Security」を見つけてください。

  5. [Secret scanning] の [カスタム パターン] で、 [新しいパターン] をクリックします。

  6. 新しいカスタム パターンの詳細を入力します。 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。

    1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
    2. [シークレット形式] フィールドに、シークレット パターンの形式の正規表現を入力します。
    3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
    4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。

    入力したカスタムの secret scanning パターン形式のスクリーンショット。

  7. 新しいカスタム パターンをテストする準備ができたら、アラートを作成せずにリポジトリで一致するものを特定するために、 [保存してドライ ラン] をクリックします。

  8. ドライ ランが完了すると、結果のサンプル (最大 1000 個) が表示されます。 結果をレビューし、誤検知の結果を特定します。

    ドライ ランの結果を示すスクリーンショット。

  9. 新しいカスタム パターンを編集して結果に関するすべての問題を修正してから、 [保存してドライ ラン] をクリックして変更をテストします。

  10. 新しいカスタム パターンに問題がなければ、 [パターンの発行] をクリックします。

  11. 任意で、カスタム パターンのプッシュ保護を有効にするには、 [有効にする] をクリックします。

    注: ドライ ランが成功し、パターンを発行するまで、[有効にする] ボタンは使用できません。

    プッシュ保護について詳しくは、「リポジトリと Organization のプッシュ保護」をご覧ください。

パターンが作成されたら、secret scanningはGitHubリポジトリ中に存在するすべてのブランチのGit履歴全体に対して、あらゆるシークレットをスキャンします。 シークレット スキャンニング アラート の表示については、「シークレット スキャンからのアラートの管理」を参照してください。

追加の要件を使用して指定されたカスタム パターンの例

ある会社には、5 つの特性を持つ内部トークンがあります。 さまざまなフィールドを使用して、トークンを特定する方法を次のように指定します。

特徴フィールドと正規表現
5 から 10 文字の長さシークレット形式: [$#%@AA-Za-z0-9]{5,10}
. で終わらないシークレットの後: [^\.]
数字と大文字を含む追加の要件: シークレットは [A-Z] および [0-9] と一致する必要がある
1 行に複数の小文字を含まない追加の要件: シークレットは [a-z]{2,} と一致してはならない
$%@! のいずれかを含む追加の要件: シークレットは [$%@!] と一致する必要がある

これらのトークンは、上記のカスタム パターンと一致します。

a9@AAfT!         # Secret string match: a9@AAfT
ee95GG@ZA942@aa  # Secret string match: @ZA942@a
a9@AA!ee9        # Secret string match: a9@AA

これらの文字列は、上記のカスタム パターンと一致しません。

a9@AA.!
a@AAAAA
aa9@AA!ee9
aAAAe9

Organizationのカスタムパターンの定義

カスタム パターンを定義する前に、Organization 内でスキャンするリポジトリに対して secret scanning を有効にしていることを確かめる必要があります。 Organization のすべてのリポジトリで secret scanning を有効にするには、「組織のセキュリティおよび分析設定を管理する」を参照してください。

  1. GitHub Enterprise Server の右上隅にあるプロファイル写真を選択し、次に自分の組織をクリックします。

    @octocat のプロファイル写真の下にあるドロップダウン メニューのスクリーンショット。 [Your organizations] (自分の組織) が濃いオレンジ色の枠線で囲まれています。

  2. 組織の隣の [設定] をクリックします。

  3. サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。

  4. [コードのセキュリティと分析] の下で、「GitHub Advanced Security」を見つけてください。

  5. [Secret scanning] の [カスタム パターン] で、 [新しいパターン] をクリックします。

  6. 新しいカスタム パターンの詳細を入力します。 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。

    1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
    2. [シークレット形式] フィールドに、シークレット パターンの形式の正規表現を入力します。
    3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
    4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。

    入力したカスタムの secret scanning パターン形式のスクリーンショット。

  7. 新しいカスタム パターンをテストする準備ができたら、アラートを作成せずにリポジトリの選択で一致するものを特定するために、 [保存してドライ ラン] をクリックします。

  8. ドライ ランを実行するリポジトリを選びます。

    • Organization 全体でドライ ランを実行するには、Organization のすべてのリポジトリを選びます。
    • ドライ ランを実行するリポジトリを指定するには、 [選択済みリポジトリ] を選び、最大 10 個のリポジトリを検索して選びます。

  9. 新しいカスタム パターンをテストする準備ができたら、 [実行] をクリックします。

  10. ドライ ランが完了すると、結果のサンプル (最大 1000 個) が表示されます。 結果をレビューし、誤検知の結果を特定します。

    ドライ ランの結果を示すスクリーンショット。

  11. 新しいカスタム パターンを編集して結果に関するすべての問題を修正してから、 [保存してドライ ラン] をクリックして変更をテストします。

  12. 新しいカスタム パターンに問題がなければ、 [パターンの発行] をクリックします。

  13. 任意で、カスタム パターンのプッシュ保護を有効にするには、 [Enable] (有効にする) をクリックします。 詳しくは、「リポジトリと Organization のプッシュ保護」を参照してください。

    注:

    • プッシュ保護を有効にするオプションは、公開されたパターンでのみ表示されます。
    • カスタム パターンのプッシュ保護は、プッシュ保護として secret scanning が有効になっている組織のリポジトリにのみ適用されます。 詳しくは、「リポジトリと Organization のプッシュ保護」を参照してください。
    • 一般的なカスタム パターンに対してプッシュ保護を有効にすると、共同作成者が混乱する可能性があります。

パターンが作成された後、secret scanning により、すべてのブランチの Git 履歴全体を含め、Organization 内のリポジトリですべてのシークレットがスキャンされます。 Organization の所有者とリポジトリの管理者は、シークレットが見つかるとアラートを受け、シークレットが見つかったリポジトリでアラートをレビューできます。 シークレット スキャンニング アラート の表示については、「シークレット スキャンからのアラートの管理」を参照してください。

Enterprise アカウントのカスタム パターンの定義

カスタム パターンを定義する前に、Enterprise アカウントのシークレット スキャンを必ず有効にする必要があります。 詳細については、「Enterprise での GitHub Advanced Security の有効化」を参照してください。

ノート/メモ:

  • Enterprise レベルでは、カスタム パターンの作成者のみがパターンを編集し、ドライ ランで使用できます。
  • ドライ ランは、自分が管理アクセス権を持つリポジトリでのみ実行できます。 エンタープライズ所有者が、組織内の任意のリポジトリでドライ ランを実行するためのアクセス権を必要とする場合は、組織所有者ロールが割り当てられている必要があります。 詳しくは、「Enterprise によって所有される Organization のロールを管理する」を参照してください。

  1. GitHub Enterprise Server の右上で、ご自分のプロフィール フォトをクリックしてから、 [Enterprise 設定] をクリックします。

    GitHub Enterprise Server のプロファイル写真をクリックしたときに表示されるドロップダウン メニューのスクリーンショット。 [エンタープライズ設定] オプションが濃いオレンジ色の枠線で強調表示されています。

  2. Enterprise アカウントのサイドバーで、 [ポリシー] をクリックします。 1. [ポリシー] で、 [コードのセキュリティと分析] をクリックします。

  3. [コードのセキュリティと分析] で、 [セキュリティ機能] をクリックします。

  4. [シークレット スキャン カスタム パターン] で、 [新しいパターン] をクリックします。

  5. 新しいカスタム パターンの詳細を入力します。 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。

    1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
    2. [シークレット形式] フィールドに、シークレット パターンの形式の正規表現を入力します。
    3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
    4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。

    入力したカスタムの secret scanning パターン形式のスクリーンショット。

  6. 新しいカスタム パターンをテストする準備ができたら、アラートを作成せずに Enterprise で一致するものを特定するため、 [保存してドライ ラン] をクリックします。

  7. ドライ ランを実行するリポジトリを最大 10 個検索して選択します。

  8. 新しいカスタム パターンをテストする準備ができたら、 [実行] をクリックします。

  9. ドライ ランが完了すると、結果のサンプル (最大 1000 個) が表示されます。 結果をレビューし、誤検知の結果を特定します。

    ドライ ランの結果を示すスクリーンショット。

  10. 新しいカスタム パターンを編集して結果に関するすべての問題を修正してから、 [保存してドライ ラン] をクリックして変更をテストします。

  11. 新しいカスタム パターンに問題がなければ、 [パターンの発行] をクリックします。

  12. 任意で、カスタム パターンのプッシュ保護を有効にするには、 [Enable] (有効にする) をクリックします。 詳しくは、「リポジトリと Organization のプッシュ保護」を参照してください。

    注:

    • カスタム パターンのプッシュ保護を有効にするには、エンタープライズ レベルでプッシュ保護として secret scanning を有効にする必要があります。 詳しくは、「リポジトリと Organization のプッシュ保護」を参照してください。
    • 一般的なカスタム パターンに対してプッシュ保護を有効にすると、共同作成者が混乱する可能性があります。

パターンが作成された後、secret scanningにより、すべてのブランチの Git 履歴全体を含め、GitHub Advanced Security が有効になっている Enterprise の Organization 内のリポジトリですべてのシークレットがスキャンされます。 Organization の所有者とリポジトリの管理者は、シークレットが見つかるとアラートを受け、シークレットが見つかったリポジトリでアラートをレビューできます。 シークレット スキャンニング アラート の表示については、「シークレット スキャンからのアラートの管理」を参照してください。

カスタム パターンの編集

カスタム パターンへの変更を保存すると、以前のバージョンのパターンを使用して作成されたすべての シークレット スキャンニング アラート が閉じられます。

  1. カスタム パターンが作成された場所に移動します。 カスタム パターンは、リポジトリ、Organization または Enterprise アカウントに作成できます。

  2. [Secret scanning] で、編集するカスタム パターンの右側にある をクリックします。

  3. 編集したカスタム パターンをテストする準備ができたら、アラートを作成せずに一致するものを特定するため、 [保存してドライ ラン] をクリックします。

  4. 変更を確認してテストしたら、 [Publish changes] (変更の発行) をクリックします。

  5. 任意で、カスタム パターンのプッシュ保護を有効にするには、 [有効にする] をクリックします。

    注:

    • カスタム パターンのプッシュ保護は、プッシュ保護として secret scanning が有効になっているリポジトリにのみ適用されます。 プッシュ保護の有効化の詳細については、「リポジトリと Organization のプッシュ保護」を参照してください。
    • 一般的なカスタム パターンに対してプッシュ保護を有効にすると、共同作成者が混乱する可能性があります。

    カスタム パターン ページのスクリーンショット。プッシュ保護を有効にするボタンが強調表示されています。

  6. 任意で、カスタム パターンのプッシュ保護を無効にするには、 [Disable] (無効にする) をクリックします。

    カスタム パターン ページのスクリーンショット。プッシュ保護を無効にするボタンが濃いオレンジ色の枠線で強調表示されています。

カスタムパターンの削除

  1. カスタム パターンが作成された場所に移動します。 カスタム パターンは、リポジトリ、Organization または Enterprise アカウントに作成できます。
  2. 削除するカスタム パターンの右側にある をクリックします。
  3. 確認をレビューし、カスタム パターンに関連するオープン アラートを処理する方法を選択します。
  4. [はい、このパターンを削除します] をクリックします。

カスタム パターンのメトリック

Organization の所有者と管理者アクセス許可を持つユーザーは、カスタム パターンのアクティビティの概要を見ることができます。 概要には、過去 30 日間のカスタム パターンに対するアラートとプッシュ保護アクティビティが含まれます。

注: カスタム パターンのメトリックはパブリック ベータ版であり、変更される可能性があります。

カスタム パターンのメトリックを表示する

  1. カスタム パターンが作成された場所に移動します。 カスタム パターンは、リポジトリ、Organization または Enterprise アカウントに作成できます。
  2. [Secret scanning] で、表示するカスタム パターンをクリックします。

カスタム パターンの名前の下にメトリックが表示されます。