SEDATED

目的

今日の CICD 環境で必要とされる無数のコード変更に伴い、開発者は機密情報を意図せず含むコードを絶えずプッシュしています。この潜在的な機密データの露出は組織にとって大きなリスクです（2017 OWASP Top Ten #3 - 機密データの露出）。SEDATED® は、すべての受信コード変更を自動的にレビューし、開発者に即座にフィードバックを提供することでこの問題に対処します。機密データを検出した場合、コミットが Git サーバーにプッシュされるのを防ぎます。

**注記: SEDATED® がスキャンするのは、コミットプッシュ内で追加または変更された行（パッチファイル内で + で始まる行）のみです。コミットプッシュ内で削除される行（パッチファイル内で - で始まる行）は SEDATED® ではスキャン されません。

セットアップ

1. SEDATED® をクローンする

git clone https://github.com/OWASP/SEDATED.git

cd SEDATED/

2. .example ファイルを更新する

cp /config/whitelists/commit_whitelist.txt.example /config/whitelists/commit_whitelist.txt

cp /config/whitelists/repo_whitelist.txt.example /config/whitelists/repo_whitelist.txt

cp /config/enforced_repos_list.txt.example /config/enforced_repos_list.txt

3. /config/custom_configs.sh の変数と関数をカスタマイズする（必要に応じて）

4. 組織固有の実装で SEDATED® をプッシュする

組織固有の SEDATED® 実装を、組織の希望する Git リポジトリ（GitHub、GitLab、Git など）にプッシュします。

5. pre-receive フックを SEDATED® の pre-receive.sh ファイルにポイントする

GitHub Enterprise インスタンスでこれを実行する手順は、GitHub_Enterprise_Setup.md にあります。

ローカルテスト

• GitHub Docker セットアップ - ローカルテスト用に pre-receive フックを有効にした Git サーバーとして動作する GitHub Docker コンテナをセットアップするための一般的な手順。
  • SEDATED® が設計どおりに機能するようにするには、いくつかの変更が必要です。
    • always_reject.sh は SEDATED® の pre-receive.sh スクリプトに置き換える必要があります。
    • SEDATED® に付属するファイル/フォルダ構造を同じディレクトリに含めるか、pre-receive.sh スクリプトからアクセスできるようにする必要があります。
    • 追加の微調整も必要になる場合がありますが、上記のリンク先の手順はローカルテストの良い出発点です。

ファイルの説明

pre-receive.sh

• SEDATED® の心臓部であり核心です。
• SEDATED® の regexes（config/regexes.json）と組み合わせて使用される SEDATED® pre-receive Git フックスクリプトは、Git インスタンスにプッシュされる追加/変更されたコード行のうち、ハードコードされた認証情報/機密データ（config/regexes.json で識別される）を含む行を特定し、ハードコードされた認証情報/機密データを含む行が見つかった場合、プッシュを拒否します。

/config/custom_configs.sh

• pre-receive.sh と組み合わせて使用される SEDATED® カスタム設定ファイルです。pre-receive.sh からソースされる組み込みのカスタマイズ可能な変数と関数を提供することで、組織は SEDATED® の pre-receive.sh ファイル内のソースコードを変更することなく、SEDATED® 実装をカスタマイズできます。

/config/enforced_repos_list.txt

• SEDATED®（pre-receive フック）の config/custom_configs.sh 内の use_enforced_repo_check_custom フラグが "True" に設定されている場合に使用されます。
• エンタープライズ全体で SEDATED® を「有効」にしつつ、このファイルにリストされているリポジトリにのみ選択的に「適用」できます。
• 特定の組織またはユーザー名配下のすべてのリポジトリに適用するには、適用したい組織またはユーザー名の末尾に /* を追加します。
• 組織内で SEDATED® がグローバルに有効になっていて、リポジトリが /config/enforced_repos_list.txt ファイルに含まれていない場合、プッシュする人（コマンドラインからプッシュしている場合）はカスタマイズ可能なメッセージ（/config/custom_configs.sh ファイルでカスタマイズ）を表示され、SEDATED® はプッシュに含まれるコードを一切スキャンしません。
• この機能を有効/無効にするフラグは /config/custom_configs.sh にあり、"True" または "False" に設定できます。
  • "False" - SEDATED® が「有効」なすべてのリポジトリに SEDATED® が「適用」されます。
  • "True" - SEDATED® が「有効」かつ /config/enforced_repos_list.txt にリストされているリポジトリにのみ SEDATED® が「適用」されます。それ以外の SEDATED® が「有効」であっても /config/enforced_repos_list.txt ファイルにリストされていないリポジトリからのプッシュでは、カスタムメッセージが表示されるだけで、コードはスキャンされません。
• このファイルは空でも構いません。config/custom_configs.sh の use_enforced_repo_check_custom フラグが "True" に設定されている場合にのみ存在する必要があります。

/config/regexes.json

• 機密データ/ハードコードされた認証情報をフラグ付けするために使用される正規表現（regexes）が含まれています。
• これらの正規表現は、pre-receive.sh 内の GNU grep が -P フラグを指定して使用し、Perl 互換正規表現（PCRE）として扱われます。
• 必要に応じてこのファイルに正規表現を追加/削除できます。ただし、/testing/regex_testing/regex_test_script.sh スクリプトを利用する場合は、更新された正規表現に関連するテストケースを追加/削除して /testing/regex_testing/test_cases.txt ファイルを更新する必要があります。これにより、/testing/regex_testing/regex_test_script.sh の結果が正確になります。
• このファイルに正規表現を追加/変更する場合、このファイルは JSON 形式のため、目的の正規表現によっては追加のエスケープ文字 \ が必要になる場合があります。

/config/whitelists/commit_whitelist.txt

• 誤検知が発生した場合に使用されます。このファイルにコミット ID が含まれている場合、1 つ以上のコミットをスキャン処理から除外できます。
• コミット ID は、/config/whitelists/commit_whitelist.txt.example ファイルに示されているように、このファイルでは改行区切りにする必要があります。
• このファイルは空でも構いませんが、存在する必要があります。

任意: 誤検知に遭遇した開発者には、レビューのためにこの（commit_whitelist.txt）ファイルへのプルリクエストを提出するよう依頼してください。

/config/whitelists/repo_whitelist.txt

• このファイルに含まれる (organization/username)/repository は、このリストから削除されるまで、機密データ/ハードコードされた認証情報のスキャンから完全に除外されます。
• 大規模なプッシュ（たとえばリポジトリ移行）で、SEDATED® がプッシュに含まれる新規/変更コードを 5 秒のウィンドウ内でスキャンできない場合に使用されます（5 秒のウィンドウは GitHub 固有であり、他の Git インスタンスでは異なる場合があります）。
• (organization/username)/repository 名は、/config/whitelists/repo_whitelist.txt.example ファイルに示されているように、このファイルでは改行区切りにする必要があります。
• このファイルは空でも構いませんが、存在する必要があります。

/testing/regex_testing/regex_test_script.sh

• testing/regex_testing/test_cases.txt と組み合わせて使用する SEDATED® 正規表現テストスクリプトは、config/regexes.json 内の正規表現が有効であり、意図したパターンに一致すること、また意図したとおりに除外/不一致となることをテスト/検証するための、シンプルで迅速なオフライン方法です。
  • テストケースのリスト（/testing/regex_testing/test_cases.txt）に対して正規表現をテストし、正規表現が期待どおりに機能することを確認します。
  • ポジティブテストケースとネガティブテストケースの両方のテストを含みます（/testing/regex_testing/test_cases.txt）。
  • スクリプトを実行するときは GNU grep を使用する必要があります。使用しないとスクリプトは失敗します（BSD grep には -P フラグがありません）。
  • このスクリプトで使用するテストケースは /testing/regex_testing/test_cases.txt から取得されます。

/testing/regex_testing/test_cases.txt

• /testing/regex_testing/regex_test_script.sh に渡して使用するテストケースのリストです。
• 各テストケースには >>pass または >>fail が付加されており、これにより /testing/regex_testing/regex_test_script.sh スクリプトは正規表現の期待結果を認識します。
  • >>pass は、前述の文字列を含むプッシュが SEDATED® によって受け入れられることを意味します（つまり、正規表現は前述の文字列をフラグ付けしません）。
  • >>fail は、前述の文字列を含むプッシュが SEDATED® によって拒否されることを意味します（つまり、正規表現は前述の文字列をフラグ付けします）。

カスタマイズ

カスタム変数と関数は、主要な処理をすべて行うメインの pre-receive フックファイルを変更することなく、組織が独自の SEDATED® 実装を簡単にカスタマイズできるように設計されています。すべてのカスタム変数と関数は /config/custom_configs.sh にあり、このファイルに含まれる変数の説明は以下のとおりです。

カスタム変数

• show_SEDATED_link_custom - OWASP/SEDATED GitHub リポジトリへのリンクを表示する場合は "True"（大文字小文字を区別）、それ以外の場合は "False" に設定します。
• documentation_link_custom - 開発者が拒否されたプッシュをどのように処理すべきかについての組織固有のドキュメントや、SEDATED® に関する一般的な組織固有の情報へのリンクを追加します。
  • プッシュが拒否されたときに開発者に表示されます。
  • enforced repo check が true に設定され、リポジトリが enforced_repos_list.txt ファイルに含まれていない場合に開発者に表示されます。
• use_enforced_repo_check_custom - "True" または "False"（大文字小文字を区別）。
  • このフラグの意味の詳細については、上記の /config/enforced_repos_list.txt のファイル説明を参照してください。
• enforced_repo_check_true_message_custom とカスタムメッセージ（use_enforced_repo_check_custom が "True" に設定されている場合のみ必要）。
• obfuscate_output_custom - "True" または "False"（大文字小文字を区別）。SEDATED® の出力に表示される機密データをマスクするにはこのオプションを使用します。

カスタム関数

• SET_USER_REPO_NAME_CUSTOM
  • ユーザー/組織/グループとリポジトリ名を設定します。
  • GitHub を使用している場合は、GITHUB_REPO_NAME 変数を使用してユーザー/組織/グループとリポジトリ名を設定します。
  • GitHub を使用していない場合は、これらの名前を取得するためにカスタム変数を設定できます。
  • 提供されている非 GitHub 名は、バニラ Git で名前を取得するだけのためのセットアップですが、さまざまな実装（Git SCM）に基づいて調整が必要な場合があります。
• PRINT_ERROR_MESSAGE_CUSTOM
  • エラーが発生したときにカスタムエラーメッセージを出力できます。
• EXIT_SEDATED_CUSTOM
  • SEDATED® を終了するときに追加のカスタムアクションを実行します（例: ログ記録、メトリクス送信など）。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。
• UNABLE_TO_ACCESS_REPO_WHITELIST_CUSTOM
  • SEDATED® がリポジトリホワイトリストファイルにアクセスできない場合に、追加のカスタムアクションを実行します（例: エラーメッセージの出力、ログ記録、メトリクス送信など）。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。
• PUSH_ACCEPTED_CUSTOM
  • プッシュが受け入れられたときに追加のカスタムアクションを実行します（例: ログ記録、メトリクス送信など）。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。
• UNABLE_TO_ACCESS_REGEXES_CUSTOM
  • SEDATED® が regexes.json ファイルにアクセスできない場合に、追加のカスタムアクションを実行します。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。
  • SEDATED® は regexes にアクセスできない場合、exit 1 してエラーメッセージを出力します。ただし、必要に応じてこれらの場合に追加のカスタムアクションを実行できます（例: 追加のエラーメッセージの出力、ログ記録、メトリクス送信など）。
• PUSH_REJECTED_WITH_VIOLATIONS_CUSTOM
  • 違反を含むためにプッシュが拒否された場合に、追加のカスタムアクションを実行します（例: ログ記録、メトリクス送信など）。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。
• UNABLE_TO_ACCESS_COMMIT_WHITELIST_CUSTOM
  • SEDATED® がコミットホワイトリストファイルにアクセスできない場合に、追加のカスタムアクションを実行します（例: ログ記録、メトリクス送信など）。
  • 追加アクションはデフォルトで : 「何もしない」になっており、変更する必要はありません。

互換性

Git バージョン管理システムを利用する SCM ツールとのみ互換性があります。

• GitHub
  • 完全にテスト済み（Enterprise v2.15.3）。
  • SEDATED® GitHub Enterprise セットアップ.
• GitLab
  • 予備的にテスト済み。
  • ユーザー/組織とリポジトリ名を設定するには、SET_USER_REPO_NAME_CUSTOM の変更が必要です。
• Git
  • 予備的にテスト済み。
  • すべての SEDATED® ファイル/フォルダ（ドキュメントフォルダ/ファイルを除く）を .git/hooks/ ディレクトリに配置する必要があります。
  • pre-receive.sample から .sample を削除し、SEDATED® の pre-receive.sh ファイルから、.sample ファイルから作成したばかりの pre-receive ファイルにコードをコピーします。
  • 実装によっては、git-template などを使用するとよいでしょう。
• その他の Git SCM ツール
  • 未テスト。
  • ユーザー/組織とリポジトリ名を設定するには、SET_USER_REPO_NAME_CUSTOM の変更が必要になる可能性が高いです。
  • 動作させるには追加の変更が必要になる場合があります。

貢献

このプロジェクトへの貢献を歓迎します！

以下のいずれかの方法で貢献できます：

• 改善のアイデアを私たちに提出してください（SEDATED® のコードベース内でアイデアを現実のものにする挑戦を引き受けたいコミュニティ内の誰かに提出しても構いません）。SEDATED® を改善できると思う点と、それがコードベース内で実際にどう実現できると思うかを詳しく説明して、issue を提起 してください。
• SEDATED® をより良くするためのコード変更を含むプルリクエストを提出してください。レビュー、テスト、マージを行います。:)

著作者

• Dennis Kennedy
• Simeon Cloutier

ライセンス

SEDATED® は BSD 3-Clause "New" or "Revised" ライセンス の下でライセンスされています。

**SEDATED® は、ハードコードされた認証情報、キー、シークレットなどのすべてのインスタンスをフラグ付けすることを保証しません。正規表現パターンマッチングを使用しており、ほとんどのインスタンスを検出できるほど優れていますが、完全ではありません。SEDATED® をさらに良くするためのアイデアやプルリクエストはいつでも歓迎します。