Allstar

[!IMPORTANT] OpenSSF がホストする Allstar GitHub App は廃止されました。 Allstar 自体（OpenSSF Scorecard サブプロジェクト）は引き続きメンテナンスされていますが、 現在は自分で実行する必要があります。GitHub Action として実行するか、 サービスデーモンとして実行するかのいずれかです。

詳細は ossf/allstar#881 を参照してください。

ホスト型アプリに依存していた組織は、ホスト型アプリからの移行を参照してください。

概要

• Allstar とは？

Allstar の新機能

• whats-new.md

不要な Issue の無効化

• Allstar が作成した不要な Issue が届くのですが、どうすればいいですか？

はじめに

• 背景
• 組織レベルのオプション
• インストールオプション
  • GitHub App を作成する
  • .allstar 管理リポジトリを作成する
  • Allstar を GitHub Action として実行する
  • Allstar をサービスデーモンとして実行する
• ホスト型アプリからの移行

ポリシーとアクション

• アクション
• ポリシー

上級者向け

• 設定定義
• 設定例
• Allstar の独自インスタンスを実行する

コントリビュート

• コントリビューション

概要

Allstar とは？

Allstar は、GitHub 組織またはリポジトリがセキュリティのベストプラクティスに準拠しているかを継続的に監視する GitHub App です。Allstar がセキュリティポリシーの違反を検出すると、リポジトリまたは組織のオーナーに警告するための Issue を作成します。一部のセキュリティポリシーでは、Allstar は違反の原因となったプロジェクト設定を自動的に変更し、期待される状態に戻すこともできます。

Allstar の目標は、プロジェクトのセキュリティに影響を与えるファイルと設定をきめ細かく制御できるようにすることです。組織レベルとリポジトリレベルの両方で監視するセキュリティポリシーと、ポリシー違反の処理方法を選択できます。また、新しいポリシーを開発したり、コントリビュートしたりすることもできます。

Allstar は OpenSSF Scorecard プロジェクトの一部として開発されています。

Allstar の新機能

不要な Issue の無効化

Allstar が作成した不要な Issue が届く場合は、こちらの手順に従ってオプトアウトしてください。

はじめに

背景

Allstar は高度に設定可能です。制御には主に 3 つのレベルがあります。

• 組織レベル: 組織の管理者は、Allstar を有効にする対象を選択できます:
  • 組織内のすべてのリポジトリ;
  • 一部をオプトアウトしたものを除く、ほとんどのリポジトリ;
  • オプトインした少数のリポジトリのみ。

これらの設定は、組織の .allstar リポジトリで行われます。

• リポジトリレベル: Allstar を使用する組織のリポジトリメンテナは、自分のリポジトリを組織レベルの適用からオプトインまたはオプトアウトできます。注: これらのリポジトリレベルの制御は、組織レベルの設定で「リポジトリオーバーライド」が許可されている場合にのみ機能します。これらの設定は、リポジトリの .allstar ディレクトリで行われます。

• ポリシーレベル: 管理者またはメンテナは、特定のリポジトリで有効にするポリシーと、ポリシー違反時に Allstar が実行するアクションを選択できます。これらの設定は、組織の .allstar リポジトリ（管理者）またはリポジトリの .allstar ディレクトリ（メンテナ）のいずれかのポリシー yaml ファイルで行われます。

組織レベルのオプション

組織レベルで Allstar をインストールする前に、Allstar を実行するリポジトリのおおよその数を決定する必要があります。これにより、オプトイン戦略とオプトアウト戦略のどちらを選択するかの判断に役立ちます。

• オプトイン戦略では、Allstar を実行したいリポジトリを手動で追加できます。リポジトリを指定しない場合、Allstar はインストールされていても実行されません。総リポジトリのうち少数のリポジトリにのみポリシーを適用したい場合、またはより多くのリポジトリで有効にする前に単一のリポジトリで Allstar を試してみたい場合は、オプトイン戦略を選択してください。v4.3 リリース以降、類似した名前の複数のリポジトリを簡単に追加できるようにグロブがサポートされています。

• オプトアウト戦略（推奨）は、すべてのリポジトリで Allstar を有効にし、Allstar の適用からオプトアウトするリポジトリを手動で選択できます。すべてのパブリックリポジトリまたはすべてのプライベートリポジトリをオプトアウトすることもできます。組織内のすべてのリポジトリで Allstar を実行したい場合、または少数のリポジトリや特定のタイプ（パブリック vs プライベートなど）のリポジトリのみをオプトアウトしたい場合は、このオプションを選択してください。v4.3 リリース以降、類似した名前の複数のリポジトリを簡単に追加できるようにグロブがサポートされています。

インストールオプション

Allstar は GitHub App として組織に作用します。アプリを作成し、そのアプリとして認証するプロセスを実行します。したがって、セットアップはすべてのデプロイメントに共通する 2 つのステップ、つまりアプリの作成と管理リポジトリの作成であり、その後、実行方法を選択します:

Action は 2 つのうちでオーバーヘッドが低く、ほとんどの組織がここから始めるべきです。ポリシー設定を変更することなく、後でデーモンに移行できます。

GitHub App を作成する

App は、組織内に一連の権限を持つユーザーに似た ID です。Allstar は、コンプライアンスを検出するためにほとんどの設定とファイルコンテンツへの読み取りアクセス、および Issue を作成して block アクションをサポートするために Issue とチェックへの書き込みアクセスが必要です。

オペレーター手順 - GitHub App の作成に従い、App ID と秘密鍵を記録してください。両方の実行モードでこれらが必要です。

.allstar 管理リポジトリを作成する

Allstar は、組織内の .allstar という名前のリポジトリから設定を読み取ります。

最も速い作成方法はサンプルからです:

1. サンプルリポジトリを開き、「Use this template」ボタンをクリックします
2. Repository Name フィールドに .allstar と入力します
3. 「Create repository from template」をクリックします

これにより、オプトアウト戦略と issue アクションを使用して、すべてのリポジトリで現在のすべての Allstar ポリシーが有効になります。これらは後で変更できます。

最初からきめ細かく制御する場合（オプトインまたはオプトアウト戦略の選択と、個々のポリシーファイルの自動作成）は、代わりに手動インストール手順に従ってください。

Allstar を GitHub Action として実行する

このオプションは、GitHub Actions を使用してスケジュールされたジョブとして Allstar を実行するため、GitHub 自体以外に運用するインフラストラクチャはありません。

GitHub Actions インストール手順に従って、.allstar リポジトリに定期的な Action を設定し、それを強化し、結果を監視します。

Allstar をサービスデーモンとして実行する

このオプションは、Allstar を常駐プロセスとして実行し、スケジュールではなく継続的に違反を検出して解決します。

プロセスの実行、シークレットの管理、サイジング、および利用可能な環境変数については、オペレーター手順を参照してください。

ホスト型アプリからの移行

組織が OpenSSF ホスト型アプリを使用していた場合、設定はそのまま引き継がれます。.allstar 管理リポジトリ、allstar.yaml、およびすべてのポリシーファイルは変更なしで機能し続けます。置き換えるのは、それらを読み取るプロセスだけです。

移行するには:

1. 独自の GitHub App を作成し、ホスト型アプリと同じリポジトリアクセスで組織にインストールします。
2. 既存の .allstar リポジトリはそのままにしておきます。
3. Allstar を Action としてまたはデーモンとして実行します。
4. 組織から allstar-app をアンインストールします（Settings -> GitHub Apps にまだ表示されている場合）。

ホスト型アプリが以前に作成した Issue はリポジトリに残ります。独自のインスタンスは、同じ allstar ラベル（または設定した issueLabel）で Issue を識別するため、違反が解決されると重複を作成するのではなく、それらの Issue を引き継いでクローズします。

ポリシーとアクション

アクション

各ポリシーには、Allstar がリポジトリの非準拠を検出したときに実行するアクションを設定できます。

• log: これはデフォルトのアクションであり、実際にはすべてのアクションで実行されます。すべてのポリシー実行結果と詳細がログに記録されます。ログは現在アプリオペレーターのみが表示でき、公開の計画は議論中です。
• issue: このアクションは GitHub Issue を作成します。ポリシーごとに 1 つの Issue のみが作成され、テキストはポリシー違反の詳細を説明します。Issue がすでに開いている場合、更新がない状態で 24 時間ごとにコメントで ping されます（現在ユーザー設定は不可）。ポリシー結果が変更されると、Issue に新しいコメントが残され、Issue 本文にリンクされます。違反が対処されると、Issue は Allstar によって 5〜10 分以内に自動的にクローズされます。
• fix: このアクションはポリシー固有です。ポリシーは、ポリシー違反を修正するために GitHub 設定を変更します。すべてのポリシーがこれをサポートできるわけではありません（以下を参照）。

提案されているが、まだ実装されていないアクション。定義は将来追加されます。

• block: Allstar は GitHub ステータスチェックを設定し、チェックが失敗した場合にリポジトリ内の PR のマージをブロックできます。
• email: Allstar はリポジトリ管理者にメールを送信します。
• rpc: Allstar は組織固有のシステムに rpc を送信します。

アクション設定

issue アクションを設定するために 2 つの設定が利用可能です:

• issueLabel は組織レベルとリポジトリレベルで利用できます。これを設定すると、Allstar が Issue を識別するために使用するデフォルトの allstar ラベルが上書きされます。

• issueRepo は組織レベルで利用できます。これを設定すると、組織内で作成されるすべての Issue が指定されたリポジトリに強制的に作成されます。

ポリシー

Allstar アプリの有効化設定と同様に、すべてのポリシーは、組織の .allstar リポジトリまたはリポジトリの .allstar ディレクトリのいずれかの yaml ファイルで有効化および設定されます。アプリと同様に、ポリシーはデフォルトでオプトインであり、デフォルトの log アクションは目に見える結果を生成しません。すべてのポリシーを有効にする簡単な方法は、各ポリシーに対して以下の内容の yaml ファイルを作成することです:```yaml optConfig: optOutStrategy: true action: issue

各ポリシーにおける`fix`アクションの動作の詳細は以下に示します。以下に記載がない場合、`fix`アクションは適用されません。

### ブランチ保護

このポリシーの設定ファイル名は`branch_protection.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig)です。

ブランチ保護ポリシーは、GitHubの[ブランチ保護設定](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)が指定された設定に従って正しく構成されているかをチェックします。Issueのテキストには、どの設定が正しくないかが記載されます。設定の修正方法については、[GitHubのドキュメント](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)を参照してください。

`fix`アクションは、指定されたポリシー設定に準拠するようにブランチ保護設定を変更します。

### バイナリアーティファクト

このポリシーの設定ファイル名は`binary_artifacts.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig)です。

このポリシーは、[scorecardのチェック](https://github.com/ossf/scorecard/#scorecard-checks)を組み込んでいます。準拠するには、リポジトリからバイナリアーティファクトを削除してください。scorecardの結果は冗長になることがあるため、詳細な情報をすべて確認するには[scorecard自体](https://github.com/ossf/scorecard)を実行する必要がある場合があります。

### CODEOWNERS

このポリシーの設定ファイル名は`codeowners.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig)です。

このポリシーは、リポジトリに[`CODEOWNERS`ファイル](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)が存在するかをチェックします。

### 外部コラボレーター

このポリシーの設定ファイル名は`outside.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig)です。

このポリシーは、[外部コラボレーター](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization)がリポジトリに対して管理者(デフォルト)またはプッシュ(オプション)アクセス権を持っているかをチェックします。このアクセス権を持つべきなのは組織メンバーのみです。そうでない場合、信頼できないメンバーが管理者レベルの設定を変更したり、悪意のあるコードをコミットしたりできるためです。

### SECURITY.md

このポリシーの設定ファイル名は`security.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig)です。

このポリシーは、リポジトリに`SECURITY.md`のセキュリティポリシーファイルがあり、それが空でないことをチェックします。作成されたIssueには、リポジトリにセキュリティポリシーをコミットするのに役立つ[GitHubタブ](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)へのリンクが含まれます。

### 危険なワークフロー

このポリシーの設定ファイル名は`dangerous_workflow.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig)です。

このポリシーは**すべての**ブランチに対して実行されます。根拠は[こちら](https://github.com/ossf/allstar/issues/569)です。

このポリシーは、GitHub Actionsのワークフロー設定ファイル(`.github/workflows`)をチェックし、既知の危険な動作に一致するパターンがないかを確認します。このチェックの詳細については、[OpenSSF Scorecardのドキュメント](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)を参照してください。

### 汎用Scorecardチェック

このポリシーの設定ファイル名は`scorecard.yaml`で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig)です。

このポリシーは、`checks`設定にリストされている任意のscorecardチェックを実行します。実行されるすべてのチェックは、`threshold`設定以上のスコアを持つ必要があります。各チェックの詳細については、[OpenSSF Scorecardのドキュメント](https://github.com/ossf/scorecard/blob/main/docs/checks.md)を参照してください。

#### SARIFアップロード

Scorecardポリシーは、結果を[SARIF](https://sarifweb.azurewebsites.net/)として各リポジトリの**Security > Code Scanning**タブにオプションでアップロードできます。これにより、組織管理者は、リポジトリごとのワークフロー設定を必要とせずに、他のセキュリティツール(CodeQL、Dependabotなど)と並んでScorecardの検出結果を可視化できます。

SARIFアップロードを有効にするには、`scorecard.yaml`に`upload`フィールドを追加します。```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

要件:

• Allstar GitHub App には、Code scanning alerts リポジトリ権限が Read & write に設定されている必要があります（API スコープ: security_events）。これは Allstar が通常必要とする権限には含まれていないため、SARIF アップロードを有効にする前に アプリに追加してください。
• SARIF アップロードは非ブロッキングです。アップロードが失敗した場合（例: 権限不足）、 ポリシーチェックは通常どおり続行されます。
• 変更検出はリポジトリの HEAD コミット SHA を比較し、前回のアップロード以降に リポジトリへのプッシュがない場合はスキャンとアップロードをスキップします。

SARIF アップロードは、Allstar の実行方法の両方で機能します。サービス デーモン として、または GitHub Action として。

GitHub Actions

このポリシーの設定ファイル名は actions.yaml で、設定定義は こちら です。

このポリシーは、各リポジトリの GitHub Actions ワークフロー設定ファイル (.github/workflows)（場合によってはワークフロー実行）をチェックし、ポリシーの 組織レベル設定で定義されたルール（例: 必須、拒否）に沿っていることを確認します。

Repository Administrators

このポリシーの設定ファイル名は admin.yaml で、設定定義は こちら です。

このポリシーは、デフォルトですべてのリポジトリにユーザーまたはグループが管理者として 割り当てられている必要があることをチェックします。ユーザーが管理者になることを許可するかどうか （チームではなく）をオプションで設定できます。

今後のポリシー

• dependabot が有効になっていることを確認します。
• 依存関係が固定/フリーズされていることをチェックします。

設定リポジトリの例

使用中の Allstar 設定の例として、このリポジトリ を 参照してください。組織管理者として、組織内での Allstar の使用方法に関する情報を含む README.md を検討してください。

詳細

設定定義

• 組織レベルの有効化設定
• リポジトリ上書きの有効化設定

セカンダリの組織レベル設定場所

デフォルトでは、上記の allstar.yaml などの組織レベル設定ファイルは、.allstar リポジトリにあることが想定されています。このリポジトリが存在しない場合、.github リポジトリの allstar ディレクトリがセカンダリの場所として使用されます。明確にするため、 allstar.yaml の場合:

これは、以下で説明する個々のポリシーの組織レベル設定ファイルにも当てはまります。

組織リポジトリ内のリポジトリポリシー設定

Allstar は、組織の .allstar リポジトリ内の、リポジトリと同じ名前のディレクトリの下にある リポジトリレベルのポリシー設定も探します。この設定は、「リポジトリ上書き」が 無効になっている場合でも使用されます。

たとえば、Allstar は特定のリポジトリ myapp のポリシー設定を次の順序で検索します:

組織レベルのベースおよびマージ設定の場所

組織レベルの Allstar およびポリシー設定ファイルでは、ベースとなる Allstar 設定を含む 別のリポジトリを指定するために、baseConfig フィールドを指定できます。これは例で説明するのが 最もわかりやすいでしょう。

複数の GitHub 組織があるが、単一の Allstar 設定を維持したいとします。メインの組織は 「acme」で、リポジトリ acme/.allstar には allstar.yaml が含まれています:```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

You also have a satellite GitHub organization named "acme-sat". You want to
re-use the main config, but apply some changes on top by disabling Allstar on
certain repositories. The repository `acme-sat/.allstar` contains
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

これは、acme/.allstar のすべての設定をベース設定として使用しますが、その上に現在のファイルの変更を適用します。この適用方法は JSON Merge Patch として説明されています。baseConfig は GitHub の <org>/<repository> である必要があります。

コントリビューション

CONTRIBUTING.md を参照してください。