GitHubはSecret Scanningのcustom patternをREST APIから作成・一覧・更新・削除できるようにした。repository、organization、enterpriseの各scopeで利用できる。独自credential形式をSecurity as Codeへ近づけられるが、dry runと最終publishは引き続きUIで行うため、APIだけで本番有効化まで完結する設計ではない。

何が変わったか

GET、POST、PATCH、DELETEのcustom patterns endpointがGAになった。pattern name、secret formatなどの定義をAPIで管理できる。GitHub公式発表では、基本CRUDが対象で、select repositoryを使ったdry runと最終publishはUIに残ると明記されている。

変更前後の差

従来はcustom patternの作成・変更を主にGitHub UIで行い、複数scopeの設定差を人手で追跡する必要があった。API追加後は、desired stateとの比較、backup、棚卸し、複数organizationへのdraft配布を自動化できる。ただしpublish approvalをAPIへ置き換えることはできない。

誰に影響するか

自社発行token、legacy API key、接続文字列、署名付きURL、社内service credentialなど、GitHub既定detectorにないsecretを検出する組織が対象である。enterprise security team、organization owner、platform engineering、internal developer platformの運用へ影響する。

期限

強制移行期限はない。既存UI運用は継続できる。まずread-only inventoryから導入し、APIによる一括変更は承認とdry runを設計してから行う。

必要な対応

pattern定義をrepositoryでversion管理し、scope、regex、前後条件、test sample、owner、目的を一つのmanifestにする。API tokenの権限を最小化し、enterprise・organization・repositoryを取り違えないようresource IDを固定する。publish前にはfalse positiveを確認し、既存history全体へalertが発生する可能性を見積もる。

実装・移行手順

  1. APIで現行custom patternを全scopeから取得する
  2. ID、name、regex、scope、publish状態をinventory化する
  3. desired stateとの差分を生成する
  4. 新patternをAPIでdraft作成する
  5. UIでdry runを実行し、最大結果とfalse positiveを確認する
  6. security approverがpublishする
  7. alert急増、owner割当、rotation capacityを監視する
  8. 変更履歴とAPI responseをaudit logへ保存する

失敗しやすい点

API作成が即publishだと誤解する、dry runを省略する、正規表現を広くしすぎる、sample stringだけで精度を判断する、同名patternを複数scopeへ重複作成する、削除をalert削除と誤認する、といった問題が起きやすい。

リスク

誤ったregexによる大量alert、API tokenの過大権限、scope誤指定、pattern削除による検出coverage低下がある。custom patternをpublishするとGit history全体が対象になるため、incident response capacityを超える可能性もある。

評価方法

  • pattern別alert件数
  • valid secret率とfalse positive率
  • dry run結果とpublish後結果の差
  • owner未割当率
  • rotation完了時間
  • scope間の定義差分
  • API同期失敗率
  • pattern変更の承認lead time

ロールバック

誤検出が多い場合はpatternをunpublishまたは削除する前に、現在定義とalert IDを保存する。修正版をdraftで作りdry runし、旧patternから切り替える。設定repositoryのcommitをrevertし、同期jobはdry-run modeへ戻す。

編集部分析

API化の価値は大量作成ではなく、設定差分を見えるようにする点にある。custom patternはcodeと同じく変更reviewが必要だが、publish後は過去historyまでscanされるため、通常のconfiguration deploymentよりblast radiusが大きい。UIに残るdry runとpublishは欠点ではなく、安全弁として扱うべきである。

実務チェックリスト

  • [ ] 全scopeの既存patternをinventory化した
  • [ ] pattern定義をversion管理した
  • [ ] API tokenを最小権限にした
  • [ ] UI dry runを必須にした
  • [ ] false positiveをreviewした
  • [ ] publish後の対応capacityを見積もった
  • [ ] rollback用に旧定義を保存した

一次情報