allstar
v4.2
Allstar は、GitHub 組織またはリポジトリがセキュリティのベスト プラクティスに従っていることを継続的に監視する GitHub アプリです。 Allstar がセキュリティ ポリシー違反を検出すると、リポジトリまたは組織の所有者に警告する問題が作成されます。一部のセキュリティ ポリシーについては、Allstar は違反の原因となったプロジェクト設定を自動的に変更し、予期した状態に戻すこともできます。
Allstar の目標は、プロジェクトのセキュリティに影響を与えるファイルと設定を細かく制御できるようにすることです。組織レベルとリポジトリ レベルの両方で監視するセキュリティ ポリシーと、ポリシー違反の処理方法を選択できます。新しいポリシーを開発または貢献することもできます。
Allstar は、OpenSSF Scorecard プロジェクトの一部として開発されました。
Allstar によって作成された不要な問題が発生している場合は、次の手順に従ってオプトアウトしてください。
Allstar は高度な設定が可能です。コントロールには主に 3 つのレベルがあります。
これらの構成は、組織の.allstarリポジトリで行われます。
リポジトリ レベル: Allstar を使用する組織のリポジトリ管理者は、リポジトリを組織レベルの適用に含めるか除外するかを選択できます。注: これらのリポジトリレベルのコントロールは、組織レベルの設定で「リポジトリの上書き」が許可されている場合にのみ機能します。これらの構成は、リポジトリの.allstarディレクトリで行われます。
ポリシー レベル:管理者またはメンテナは、特定のリポジトリでどのポリシーを有効にするか、ポリシーに違反した場合に Allstar が実行するアクションを選択できます。これらの構成は、組織の.allstarリポジトリ (管理者) またはリポジトリの.allstarディレクトリ (メンテナ) のいずれかにあるポリシー yaml ファイルで行われます。
Allstar を組織レベルでインストールする前に、Allstar を実行するリポジトリのおおよその数を決定する必要があります。これは、オプトイン戦略とオプトアウト戦略のどちらかを選択するのに役立ちます。
オプトイン戦略を使用すると、Allstar を実行するリポジトリを手動で追加できます。リポジトリを指定しない場合、Allstar はインストールされていても実行されません。全体のリポジトリのうち少数のリポジトリにのみポリシーを適用したい場合、または他のリポジトリで Allstar を有効にする前に 1 つのリポジトリで Allstar を試したい場合は、オプトイン戦略を選択します。 v4.3 リリース以降、類似した名前を持つ複数のリポジトリを簡単に追加できるグロブがサポートされています。
オプトアウト戦略 (推奨) では、すべてのリポジトリで Allstar が有効になり、Allstar の強制をオプトアウトするリポジトリを手動で選択できるようになります。すべてのパブリック リポジトリまたはすべてのプライベート リポジトリをオプトアウトすることも選択できます。組織内のすべてのリポジトリで Allstar を実行する場合、または少数のリポジトリまたは特定の種類のリポジトリ (パブリックまたはプライベート) のみをオプトアウトする場合は、このオプションを選択します。 v4.3 リリース以降、類似した名前を持つ複数のリポジトリを簡単に追加できるグロブがサポートされています。
| オプトアウト (推奨) optOutStrategy = true | オプトイン optOutStrategy = false | |
|---|---|---|
| デフォルトの動作 | すべてのリポジトリが有効になっています | 有効なリポジトリはありません |
| リポジトリを手動で追加する | リポジトリを手動で追加すると、それらのリポジトリで Allstar が無効になります | リポジトリを手動で追加すると、それらのリポジトリで Allstar が有効になります |
| 追加の構成 | optOutRepos: Allstar はリストされたリポジトリで無効になります optOutPrivateRepos: true の場合、Allstar はすべてのプライベート リポジトリで無効になります optOutPublicRepos: true の場合、Allstar はすべてのパブリック リポジトリで無効になります (optInRepos: この設定は無視されます) | optInRepos: Allstar はリストされたリポジトリで有効になります (optOutRepos: この設定は無視されます) |
| リポジトリの上書き | true の場合: リポジトリは、独自のリポジトリ ファイルの設定を使用して、組織の Allstar 施行をオプトアウトできます。そのリポジトリに適用される組織レベルのオプトイン設定は無視されます。 false の場合: リポジトリは、組織レベルで設定されている Allstar 強制をオプトアウトできません。 | true の場合: リポジトリが組織レベルでリポジトリ用に設定されていない場合でも、リポジトリは組織の Allstar 施行をオプトインできます。そのリポジトリに適用される組織レベルのオプトアウト設定は無視されます。 false の場合: Allstar 施行が組織レベルで設定されていない場合、Repos は Allstar 施行をオプトインできません。 |
クイックスタート オプションと手動インストール オプションの両方に、Allstar アプリのインストールが含まれます。要求された権限を確認できます。アプリは、セキュリティ コンプライアンスを検出するために、ほとんどの設定およびファイル コンテンツへの読み取りアクセスを要求します。問題への書き込みアクセスを要求し、問題を作成してblockアクションを許可できるようにチェックします。
このインストール オプションにより、組織内のすべてのリポジトリでオプトアウト戦略を使用して Allstar が有効になります。現在のすべてのポリシーが有効になり、Allstar は問題を提出することでポリシー違反を警告します。これは Allstar の使用を開始する最も迅速かつ簡単な方法であり、後で構成を変更することもできます。
労力: 非常に簡単
手順:
.allstarと入力します。それでおしまい！現在の Allstar ポリシーはすべて、すべてのリポジトリで有効になります。ポリシーに違反した場合、オールスターは問題を作成します。
構成を変更するには、手動のインストール手順を参照してください。
このインストール オプションでは、オプトインまたはオプトアウト戦略に従って構成ファイルを作成する手順を説明します。このオプションを使用すると、最初から構成をより詳細に制御できます。
労力: 中程度
手順:
各ポリシーには、コンプライアンス違反のリポジトリが検出されたときに Allstar が実行するアクションを設定できます。
log : これはデフォルトのアクションであり、実際にはすべてのアクションに対して実行されます。すべてのポリシーの実行結果と詳細がログに記録されます。現在、ログはアプリ運営者のみに表示されており、公開する計画は検討中です。issue : このアクションにより、GitHub の問題が作成されます。ポリシーごとに作成される問題は 1 つだけであり、テキストにはポリシー違反の詳細が説明されます。問題がすでに未解決の場合は、更新なしで 24 時間ごとにコメント付きで ping が送信されます (現時点ではユーザーが構成できません)。ポリシーの結果が変更された場合、問題に対して新しいコメントが残され、問題の本文にリンクされます。違反が解決されると、問題は 5 ～ 10 分以内に Allstar によって自動的にクローズされます。fix : このアクションはポリシー固有です。ポリシーは、ポリシー違反を修正するために GitHub 設定に変更を加えます。すべてのポリシーがこれをサポートできるわけではありません (以下を参照)。提案されているが、まだ実装されていないアクション。定義は将来追加される予定です。
block : Allstar は GitHub ステータス チェックを設定し、チェックが失敗した場合にリポジトリ内の PR がマージされるのをブロックできます。email : Allstar はリポジトリ管理者に電子メールを送信します。rpc : Allstar は、rpc を組織固有のシステムに送信します。問題アクションを構成するには、次の 2 つの設定を使用できます。
issueLabel 、組織レベルおよびリポジトリ レベルで使用できます。これを設定すると、Allstar が問題を識別するために使用するデフォルトのallstarラベルがオーバーライドされます。
issueRepo組織レベルで利用できます。これを設定すると、組織内で作成されたすべての課題が指定されたリポジトリに強制的に作成されます。
Allstar アプリの有効化構成と同様に、すべてのポリシーは、組織の.allstarリポジトリまたはリポジトリの.allstarディレクトリのいずれかにある yaml ファイルを使用して有効化および構成されます。アプリと同様に、ポリシーはデフォルトでオプトインされており、デフォルトのlogアクションでも目に見える結果は生成されません。すべてのポリシーを有効にする簡単な方法は、次の内容を含む yaml ファイルをポリシーごとに作成することです。
optConfig:
optOutStrategy: true
action: issue
各ポリシーに対するfixアクションがどのように機能するかについては、以下で詳しく説明します。以下を省略した場合、 fixアクションは適用されません。
このポリシーの構成ファイルの名前はbranch_protection.yamlで、構成定義はここにあります。
ブランチ保護ポリシーは、GitHub のブランチ保護設定が指定された構成に従って正しくセットアップされているかどうかをチェックします。問題文には、どの設定が間違っているかが説明されています。設定の修正については、GitHub のドキュメントを参照してください。
fixアクションにより、指定されたポリシー構成に準拠するようにブランチ保護設定が変更されます。
このポリシーの構成ファイルの名前はbinary_artifacts.yamlで、構成定義はここにあります。
このポリシーには、スコアカードからのチェックが組み込まれています。コンプライアンスを達成するには、リポジトリからバイナリ アーティファクトを削除します。スコアカードの結果は冗長になる場合があるため、すべての詳細情報を表示するにはスコアカード自体を実行する必要がある場合があります。
このポリシーの構成ファイルの名前はcodeowners.yamlで、構成定義はここにあります。
このポリシーは、リポジトリ上にCODEOWNERSファイルが存在するかどうかを確認します。
このポリシーの構成ファイルの名前はoutside.yamlで、構成定義はここにあります。
このポリシーは、外部コラボレーターがリポジトリへの管理者 (デフォルト) アクセス権またはプッシュ (オプション) アクセス権を持っているかどうかを確認します。組織のメンバーのみがこのアクセス権を持つ必要があります。そうしないと、信頼できないメンバーが管理者レベルの設定を変更し、悪意のあるコードをコミットする可能性があります。
このポリシーの構成ファイルの名前はsecurity.yamlで、構成定義はここにあります。
このポリシーは、リポジトリのSECURITY.mdにセキュリティ ポリシー ファイルがあること、およびそれが空ではないことをチェックします。作成された問題には、セキュリティ ポリシーをリポジトリにコミットするのに役立つ [GitHub] タブへのリンクが含まれます。
このポリシーの構成ファイルの名前はdangerous_workflow.yamlで、構成定義はここにあります。
このポリシーは、GitHub Actions ワークフロー構成ファイル ( .github/workflows ) をチェックして、既知の危険な動作に一致するパターンがないかどうかを確認します。このチェックの詳細については、OpenSSF スコアカードのドキュメントを参照してください。
このポリシーの構成ファイルの名前はscorecard.yamlで、構成定義はここにあります。
このポリシーは、 checks構成にリストされているスコアカード チェックを実行します。実行されるすべてのチェックのスコアがthreshold設定以上である必要があります。各チェックの詳細については、OpenSSF スコアカードのドキュメントを参照してください。
このポリシーの構成ファイルの名前はactions.yamlで、構成定義はここにあります。
このポリシーは、各リポジトリ内の GitHub Actions ワークフロー構成ファイル ( .github/workflows ) (および場合によってはワークフローの実行) をチェックして、それらが組織レベルの構成で定義されたルール (require、deny など) に準拠していることを確認します。ポリシー。
このポリシーの構成ファイルの名前はadmin.yamlで、構成定義はここにあります。
このポリシーは、デフォルトですべてのリポジトリにユーザーまたはグループが管理者として割り当てられている必要があることを確認します。ユーザーが (チームではなく) 管理者になることを許可するかどうかをオプションで構成できます。
使用されている Allstar 構成の例として、このリポジトリを参照してください。組織管理者は、組織内で Allstar がどのように使用されているかに関する情報が記載された README.md を検討してください。
デフォルトでは、上記のallstar.yamlファイルなどの組織レベルの設定ファイルは.allstarリポジトリにあることが想定されています。このリポジトリが存在しない場合は、 .githubリポジトリのallstarディレクトリが 2 番目の場所として使用されます。明確にするために、 allstar.yamlの場合:
| 優先順位 | リポジトリ | パス |
|---|---|---|
| 主要な | .allstar | allstar.yaml |
| 二次 | .github | allstar/allstar.yaml |
これは、以下で説明するように、個々のポリシーの組織レベルの設定ファイルにも当てはまります。
Allstar は、リポジトリと同じ名前のディレクトリの下にある、組織の.allstarリポジトリ内のリポジトリ レベルのポリシー設定も検索します。この設定は、「リポジトリ オーバーライド」が無効になっているかどうかに関係なく使用されます。
たとえば、Allstar は、特定のリポジトリmyappのポリシー設定を次の順序で検索します。
| リポジトリ | パス | 状態 |
|---|---|---|
myapp | .allstar/branch_protection.yaml | 「リポジトリのオーバーライド」が許可されている場合。 |
.allstar | myapp/branch_protection.yaml | いつでも。 |
.allstar | branch_protection.yaml | いつでも。 |
.github | allstar/myapp/branch_protection.yaml | .allstarリポジトリが存在しない場合。 |
.github | allstar/branch_protection.yaml | .allstarリポジトリが存在しない場合。 |
組織レベルの Allstar およびポリシー設定ファイルの場合、 baseConfigフィールドを指定して、Allstar の基本設定を含む別のリポジトリを指定できます。これについては、例を挙げて説明するのが最も分かりやすいでしょう。
複数の GitHub 組織があるが、単一の Allstar 構成を維持したいとします。メインの組織は「acme」で、リポジトリacme/.allstarにはallstar.yaml含まれています。
optConfig :
optOutStrategy : true
issueLabel : allstar-acme
issueFooter : Issue created by Acme security team. 「acme-sat」という名前のサテライト GitHub 組織もあります。メインの設定を再利用したいが、特定のリポジトリで Allstar を無効にして、いくつかの変更を上に適用したいと考えています。リポジトリacme-sat/.allstarにはallstar.yamlが含まれています。
baseConfig : acme/.allstar
optConfig :
optOutRepos :
- acmesat-one
- acmesat-twoこれにより、 acme/.allstarのすべての構成が基本構成として使用されますが、現在のファイルの変更は基本構成に加えて適用されます。これを適用する方法を JSON マージ パッチと呼びます。 baseConfig GitHub <org>/<repository>である必要があります。
CONTRIBUTING.md を参照してください。
