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ライブラリを利用し、Hyperscanの正規構造のみをサポートします。これはPCRE構文のサブセットです。 Hyperscanのオプション修飾子はサポートされません。 Hyperscanのパターン構造に関する詳しい情報については、Hyperscanのドキュメンテーションの「Pattern support」を参照してください。
リポジトリのカスタムパターンの定義
カスタムパターンを定義する前に、リポジトリでsecret scanningが有効化されていることを確認しておかなければなりません。 詳しい情報については「リポジトリでのsecret scanningの設定」を参照してください。
-
GitHub.comで、リポジトリのメインページにアクセスしてください。
-
リポジトリ名の下で Settings(設定)をクリックしてください。
-
In the "Security" section of the sidebar, click Code security and analysis.
-
Under "Code security and analysis", find "GitHub Advanced Security."
-
"Secret scanning"の下の"Custom patterns(カスタムパターン)"の下で、 New pattern(新規パターン)をクリックしてください。
-
新しいカスタムパターンの詳細を入力します。
- 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
- [More options ]をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を提供できます。
- サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認してください。
-
新しいカスタムパターンをテストする準備ができたら、アラートを作成することなくリポジトリ内のマッチを特定するために、Save and dry run(保存してdry run)をクリックしてください。
-
dry runが終了すると、結果のサンプル(最大1000)が表示されます。 結果をレビューし、誤検知の結果を確認してください。
-
結果に問題があれば修正するために新しいカスタムパターンを編集し、その変更をテストするためにSave and dry run(保存してdry run)をクリックしてください。
Note: The dry run feature is currently in beta and subject to change.
-
新しいカスタムパターンに満足したら、Publish pattern(パターンの公開)をクリックしてください。
パターンを作成したら、secret scanningはGitHubリポジトリ中に存在するすべてのブランチのGit履歴全体に対して、あらゆるシークレットをスキャンします。 secret scanningアラートの表示に関する詳しい情報については「secret scanningからのアラートの管理」を参照してください。
追加要件を使って指定されるカスタムパターンの例
ある企業は、5文字の内部トークンを持っています。 その企業では、以下のようなトークンの特定方法を指定するため、様々なフィールドを使います。
特徴 | フィールドと正規表現 |
---|---|
長さが5から10文字 | シークレットフォーマット: [$#%@AA-Za-z0-9]{5,10} |
. で終わらない | シークレットの後: [^\.] |
数字と大文字を含む | 追加要件: シークレットは[A-Z] と[0-9] にマッチしなければならない |
1行に複数の小文字を含んではならない | 追加要件: シークレットは[a-z]{2,} にマッチしてはならない |
$%@! のいずれかを含む | 追加要件: シークレットは[$%@!] にマッチしなければならない |
以下のトークンは、上記のカスタムパターンにマッチします。
a9@AAfT! # マッチするシークレット文字列: a9@AAfT
ee95GG@ZA942@aa # マッチするシークレット文字列: @ZA942@a
a9@AA!ee9 # マッチするシークレット文字列: a9@AA
以下の文字列は、上記のカスタムパターンにマッチしません。
a9@AA.!
a@AAAAA
aa9@AA!ee9
aAAAe9
Organizationのカスタムパターンの定義
カスタムパターンを定義する前に、Organizationの中のスキャンしたいリポジトリでsecret scanningが有効化されていることを確認しなければなりません。 Organization内のすべてのリポジトリでsecret scanningを有効化するには、「Organizationのセキュリティと分析設定の管理」を参照してください。
-
In the top right corner of GitHub.com, click your profile photo, then click Your organizations.
-
Organizationの隣のSettings(設定)をクリックしてください。
-
In the "Security" section of the sidebar, click Code security and analysis.
-
Under "Code security and analysis", find "GitHub Advanced Security."
-
"Secret scanning"の下の"Custom patterns(カスタムパターン)"の下で、 New pattern(新規パターン)をクリックしてください。
-
新しいカスタムパターンの詳細を入力します。
- 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
- [More options ]をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を提供できます。
- サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認してください。
-
新しいカスタムパターンをテストする準備ができたら、アラートを作成することなく選択したリポジトリ内のマッチを特定するために、Save and dry run(保存してdry run)をクリックしてください。
-
dry runを実行したいリポジトリを最大10個まで検索して選択してください。
-
カスタムパターンをテストする準備ができたら、Dry runをクリックしてください。
-
dry runが終了すると、結果のサンプル(最大1000)が表示されます。 結果をレビューし、誤検知の結果を確認してください。
-
結果に問題があれば修正するために新しいカスタムパターンを編集し、その変更をテストするためにSave and dry run(保存してdry run)をクリックしてください。
Note: The dry run feature is currently in beta and subject to change.
-
新しいカスタムパターンに満足したら、Publish pattern(パターンの公開)をクリックしてください。
パターンを作成すると、secret scanningはすべてのブランチのGit履歴全体を含めて、Organization内のリポジトリでシークレットをスキャンします。 Organizationのオーナーとリポジトリの管理者は、シークレットが見つかるとアラートを受け、シークレットが見つかったリポジトリでアラートをレビューできます。 secret scanningアラートの表示に関する詳しい情報については「secret scanning空のアラートの管理」を参照してください。
Enterpriseアカウントでのカスタムパターンの定義
カスタムパターンを定義する前に、Enterpriseアカウントでシークレットスキャンニングを有効化しておかなければなりません。 詳しい情報については「EnterpriseでのGitHub Advanced Securityの有効化」を参照してください。
ノート:
- Enterpriseレベルでは、カスタムパターンを編集でき、dry runで使えるのはカスタムパターンの作者だけです。
- Enterpriseオーナーは、アクセスできるリポジトリ上でのみdry runを利用できますが、必ずしもEnterprise内のすべてのOrganizationやリポジトリにアクセスできるわけではありません。
-
GitHub.comの右上で、自分のプロフィール写真をクリックし、続いてYour enterprises(自分のEnterprise)をクリックしてください。
-
Enterpriseのリストで、表示したいEnterpriseをクリックしてください。
-
Enterpriseアカウントのサイドバーで、 Policies(ポリシー)をクリックしてください。
-
Policies(ポリシー)の下で、"Advanced Security"をクリックしてください。
-
Under "GitHub Advanced Security", click the Security features tab.
-
"Secret scanning custom patterns(シークレットスキャンニングのカスタムパターン)"の下で、New pattern(新規パターン)をクリックしてください。
-
新しいカスタムパターンの詳細を入力します。
- 少なくともパターンの名前と、シークレットパターンのフォーマットとして正規表現を提供しなければなりません。
- [More options ]をクリックして、シークレットのフォーマットのその他の周辺コンテンツあるいは追加のマッチ要件を提供できます。
- サンプルのテスト文字列を指定し、設定内容が期待するパターンにマッチすることを確認してください。
-
新しいカスタムパターンをテストする準備ができたら、アラートを作成することなくEnterprise内のマッチを特定するために、Save and dry run(保存してdry run)をクリックしてください。
-
dry runを実行したいリポジトリを最大10個まで検索して選択してください。
-
カスタムパターンをテストする準備ができたら、Dry runをクリックしてください。
-
dry runが終了すると、結果のサンプル(最大1000)が表示されます。 結果をレビューし、誤検知の結果を確認してください。
-
結果に問題があれば修正するために新しいカスタムパターンを編集し、その変更をテストするためにSave and dry run(保存してdry run)をクリックしてください。
Note: The dry run feature is currently in beta and subject to change.
-
新しいカスタムパターンに満足したら、Publish pattern(パターンの公開)をクリックしてください。
パターンを作成すると、secret scanningはすべてのブランチのGit履歴全体を含めて、GitHub Advanced Securityが有効化されたEnterpriseのOrganization内のリポジトリでシークレットをスキャンします。 Organizationのオーナーとリポジトリの管理者は、シークレットが見つかるとアラートを受け、シークレットが見つかったリポジトリでアラートをレビューできます。 secret scanningアラートの表示に関する詳しい情報については「secret scanning空のアラートの管理」を参照してください。
カスタムパターンの編集
カスタムパターンに変更を保存すると、パターンの以前のバージョンを使って作成されたすべてのsecret scanningアラートはクローズされます。
- カスタムパターンが作成された場所にアクセスしてください。 カスタムパターンは、リポジトリ、Organization、Enterpriseアカウントで作成できます。
- リポジトリあるいはOrganizationの場合は、カスタムパターンが作成されたリポジトリもしくはOrganizationの"Security & analysis(セキュリティと分析)" 設定を表示させてください。 詳しい情報については上の「リポジトリのカスタムパターンの定義」あるいは「Organizationのカスタムパターンの定義」を参照してください。
- Enterpriseの場合は、"Policies(ポリシー)"の下で"Advanced Security(高度なセキュリティ)"を表示させ、Security features(セキュリティの機能)をクリックしてください。 詳しい情報については、上記の「Enterpriseアカウントでのカスタムパターンの定義」を参照してください。
- "Secret scanning"の下で、編集したいカスタムパターンの右のをクリックしてください。
- 編集された新しいカスタムパターンをテストする準備ができたら、アラートを作成することなくマッチを特定するために、Save and dry run(保存してdry run)をクリックしてください。
- 変更をレビューしてテストしたら、Save changes(変更を保存)をクリックしてください。
カスタムパターンの削除
-
カスタムパターンが作成された場所にアクセスしてください。 カスタムパターンは、リポジトリ、Organization、Enterpriseアカウントで作成できます。
- リポジトリあるいはOrganizationの場合は、カスタムパターンが作成されたリポジトリもしくはOrganizationの"Security & analysis(セキュリティと分析)" 設定を表示させてください。 詳しい情報については上の「リポジトリのカスタムパターンの定義」あるいは「Organizationのカスタムパターンの定義」を参照してください。
- Enterpriseの場合は、"Policies(ポリシー)"の下で"Advanced Security(高度なセキュリティ)"を表示させ、Security features(セキュリティの機能)をクリックしてください。 詳しい情報については、上記の「Enterpriseアカウントでのカスタムパターンの定義」を参照してください。
-
削除したいカスタムパターンの右でをクリックしてください。
-
確認したら、そのカスタムパターンに関連するオープンなアラートを処理方法を選択してください。
-
Yes, delete this pattern(はい、このパターンを削除してください)をクリックしてください。