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

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

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

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

カスタムパターンの正規表現構文

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

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

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

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

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

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

ご自分のエンタープライズで、リポジトリのメインページへ移動します。
リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウンメニューを選び、 [設定] をクリックします。
サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。
[コードのセキュリティと分析] の下で、「GitHub Advanced Security」を見つけてください。
[Secret scanning] の [カスタムパターン] で、 [新しいパターン] をクリックします。
新しいカスタムパターンの詳細を入力します。少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
2. [Secret format] (シークレットの形式) フィールドに、シークレットパターンの形式を表す正規表現を入力します。
3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。
新しいカスタムパターンをテストする準備ができたら、アラートを作成せずにリポジトリで一致するものを特定するために、 [保存してドライラン] をクリックします。
ドライランが完了すると、結果のサンプル (最大 1000 個) が表示されます。結果をレビューし、誤検知の結果を特定します。
新しいカスタムパターンを編集して結果に関するすべての問題を修正してから、 [保存してドライラン] をクリックして変更をテストします。

注: ドライラン機能は現在ベータ版であり、変更されることがあります。
新しいカスタムパターンに問題がなければ、 [パターンの発行] をクリックします。

パターンが作成されたら、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 を有効にしていることを確かめる必要があります。組織のすべてのリポジトリで secret scanning を有効にするには、「Organization のセキュリティおよび分析設定を管理する」を参照してください。

注: ドライラン機能がないため、Organization 全体に対して定義する前に、リポジトリでカスタムパターンをテストすることをお勧めします。そうすることで、過剰な誤検知シークレットスキャンアラートを作成しないようにすることができます。

GitHub AE の右上隅にあるプロファイル写真をクリックし、 [自分の Organization] をクリックします。
組織の隣の [設定] をクリックします。
サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。
[コードのセキュリティと分析] の下で、「GitHub Advanced Security」を見つけてください。
[Secret scanning] の [カスタムパターン] で、 [新しいパターン] をクリックします。
新しいカスタムパターンの詳細を入力します。少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
2. [Secret format] (シークレットの形式) フィールドに、シークレットパターンの形式を表す正規表現を入力します。
3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。
新しいカスタムパターンをテストする準備ができたら、アラートを作成せずにリポジトリの選択で一致するものを特定するために、 [保存してドライラン] をクリックします。
ドライランを実行するリポジトリを最大 10 個検索して選択します。
新しいカスタムパターンをテストする準備ができたら、 [ドライラン] をクリックします。
ドライランが完了すると、結果のサンプル (最大 1000 個) が表示されます。結果をレビューし、誤検知の結果を特定します。
新しいカスタムパターンを編集して結果に関するすべての問題を修正してから、 [保存してドライラン] をクリックして変更をテストします。

注: ドライラン機能は現在ベータ版であり、変更されることがあります。
新しいカスタムパターンに問題がなければ、 [パターンの発行] をクリックします。

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

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

注:

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

GitHub AE の右上で、ご自分のプロファイル写真をクリックしてから、 [Enterprise 設定] をクリックします。
Enterprise アカウントのサイドバーで、 [ポリシー] をクリックします。
[ ポリシー] で、 [高度なセキュリティ] をクリックします。
[GitHub Advanced Security] の [セキュリティ機能] タブをクリックします。
[シークレットスキャンカスタムパターン] で、 [新しいパターン] をクリックします。
新しいカスタムパターンの詳細を入力します。少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
1. [Pattern name] (パターン名) フィールドにパターンの名前を入力します。
2. [Secret format] (シークレットの形式) フィールドに、シークレットパターンの形式を表す正規表現を入力します。
3. [その他のオプション ] をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を指定できます。
4. サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認できます。
新しいカスタムパターンをテストする準備ができたら、アラートを作成せずに Enterprise で一致するものを特定するため、 [保存してドライラン] をクリックします。
ドライランを実行するリポジトリを最大 10 個検索して選択します。
新しいカスタムパターンをテストする準備ができたら、 [ドライラン] をクリックします。
ドライランが完了すると、結果のサンプル (最大 1000 個) が表示されます。結果をレビューし、誤検知の結果を特定します。
新しいカスタムパターンを編集して結果に関するすべての問題を修正してから、 [保存してドライラン] をクリックして変更をテストします。

注: ドライラン機能は現在ベータ版であり、変更されることがあります。
新しいカスタムパターンに問題がなければ、 [パターンの発行] をクリックします。

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

カスタムパターンの編集

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

カスタムパターンが作成された場所に移動します。カスタムパターンは、リポジトリ、Organization または Enterprise アカウントに作成できます。
- リポジトリまたは Organization の場合、カスタムパターンが作成されたリポジトリまたは Organization の [セキュリティと分析] 設定を表示します。詳しくは、「リポジトリのカスタムパターンの定義」または「組織のカスタムパターンの定義」を参照してください。
- Enterprise の場合、[ポリシー] の下にある [高度なセキュリティ] 領域を表示してから、 [セキュリティ機能] をクリックします。詳細については、上記の「Enterprise アカウントのカスタムパターンの定義」を参照してください。
[Secret scanning] で、編集するカスタムパターンの右側にあるをクリックします。
編集したカスタムパターンをテストする準備ができたら、アラートを作成せずに一致するものを特定するため、 [保存してドライラン] をクリックします。
変更を確認してテストしたら、 [Publish changes] (変更の発行) をクリックします。

カスタムパターンの削除

カスタムパターンが作成された場所に移動します。カスタムパターンは、リポジトリ、Organization または Enterprise アカウントに作成できます。
- リポジトリまたは Organization の場合、カスタムパターンが作成されたリポジトリまたは Organization の [セキュリティと分析] 設定を表示します。詳しくは、「リポジトリのカスタムパターンの定義」または「組織のカスタムパターンの定義」を参照してください。
- Enterprise の場合、[ポリシー] の下にある [高度なセキュリティ] 領域を表示してから、 [セキュリティ機能] をクリックします。詳細については、上記の「Enterprise アカウントのカスタムパターンの定義」を参照してください。
削除するカスタムパターンの右側にあるをクリックします。
確認をレビューし、カスタムパターンに関連する開いているアラートを処理する方法を選択します。
[はい、このパターンを削除します] をクリックします。

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

この記事の内容

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