security-workflows

appbrew の Organization rulesets から、全リポジトリに課す共通のセキュリティ workflow を置くリポジトリです。 各リポジトリに workflow ファイルを置く必要はありません。

ruleset から使えるように、このリポジトリは public にしています。 GitHub の仕様で、workflow を置くリポジトリの公開範囲は、使う側と同じか、それより広くなければならないためです。

Betterleaks（.github/workflows/betterleaks.yml）

PR とマージキューで、その変更で増えたコミットに秘密情報（トークンやパスワード）が含まれていないかを検査します。 見つかるとジョブが失敗し、PR をマージできません。

検出されたとき

PR コメントに検出箇所、ルール名、対象コミット、対処方法を表示します。秘密値やコードの抜粋はコメントに載せません。 generic-password を含むすべての既定ルールについて、検出時に CI が失敗する判定は変えません。

誤検知の場合は、リポジトリ直下の .betterleaksignore に、その項目の識別子を1行ずつ追記します。 識別子は PR コメントからコピーできます。誤検知と確認したものだけを追加し、除外理由を PR に記載してレビューを受けてください。

<コミットのSHA>:<ファイルのパス>:<ルール名>:<行番号>

例: d16c50bbde90264d6f4a695763d67a74f330770f:config/example.env:github-pat:1

ignore の追加は追加コミットを通常の push で反映できます。履歴の書き換えや force-push は不要です。 検査対象リポジトリの最新コミットにある .betterleaksignore を読み、PR 内の過去コミットの検出にも適用します。

本物の秘密情報なら、まず発行元で無効化・ローテーションし、該当コミットから値を取り除きます。 コミットから消すだけでは足りません。push した時点で GitHub に届いているためです。 後続コミットで値を削除しても、検査対象の過去コミットに残っていれば検出されます。 履歴を書き換える場合は、共同作業者の変更とブランチの保護設定を確認してください。

行単位の betterleaks:allow コメントも使用できますが、後続コミットで追加しても過去コミットの検出は消えません。 すでに CI で検出された誤検知には .betterleaksignore の追記を使えます。

自動コメントの動作

• 検出時は新しい案内を投稿してから、以前の Betterleaks 自動コメントを OUTDATED として折りたたみます。
• 再検査で検出がなくなった場合は、以前の自動コメントを RESOLVED として折りたたみます。これは検査結果の解消を示すもので、秘密情報の失効を確認するものではありません。
• 実行エラーは検出と区別し、CI ログの確認と再実行を案内します。
• 最新の PR コミットと一致しない実行結果ではコメントを更新しません。
• コメントには先頭50件まで表示します。文字数の上限に達した場合は50件未満になることがあります。残りは CI ログで確認してください。
• fork や Dependabot の PR など、書き込み権限がない場合はコメントできません。同じ案内を Actions の Scan for secrets ジョブの Summary に残します。通知の成否は検査の合否に影響しません。
• マージキューでは Summary に記録し、PR コメントは投稿しません。

秘密値を含み得る生の JSON レポートは runner の一時ディレクトリだけに置き、artifact や別ジョブには渡しません。 通知ジョブは検査対象のコードを checkout・実行せず、検出箇所の情報だけを受け取ります。

設定

• 検査ルールは Betterleaks の既定のルールです。検査される側の .betterleaks.toml は読みません。PR が自分の検査ルールを弱められないようにするためです。
• 見つけた値が本物かを外部の API に問い合わせる機能（--validation）は使いません。
• スキャン・通知ともに ubuntu-slim を使います。スキャンは従来どおり15分、通知は5分でタイムアウトします。
• 検出時の終了コードを 10、実行エラーを 1 として案内を分けます。どちらもスキャンジョブは失敗します。

ローカルでの確認

Node.js で、workflow 内のコメント生成・投稿処理とスキャンの終了コード処理を検証できます。

node --test tests/betterleaks.test.cjs

鍵や証明書のファイルの検査（key-files ジョブ）

Betterleaks はバイナリのファイルを読み飛ばすので、証明書や鍵ストアの中身は検査できません。 そこで、同じ workflow の key-files ジョブで、次の拡張子のファイルを PR のコミットで追加・変更していないかを検査します。

.p12、.pfx、.pkcs12、.jks、.keystore、.bks、.jceks（大文字と小文字は区別しません）

見つかるとジョブが失敗します。PR 内の各コミットを見るので、後続のコミットでファイルを削除しても検出は残ります。 すでにリポジトリにあるファイルは、PR で変更しない限り検出しません。

• 本物の鍵や証明書なら、まず発行元で失効・再発行してから、コミットから取り除きます。

• 開発用の署名鍵のようにリポジトリに置いてよいファイルなら、.betterleaksignore に次の形式で1行を追記します。行は Actions の Summary からコピーできます。

  <コミットのSHA>:<ファイルのパス>:binary-key-file:0
  

  ファイルのパスだけの除外（コミットの SHA を省いた形）は受け付けません。同じパスのファイルを、あとで本物の鍵に差し替えても検出するためです。

このジョブはファイル名の一覧だけを使うので、checkout ではファイルの中身を取得しません（sparse checkout）。

node --test tests/key-files.test.cjs