Allstar は、GitHub 組織またはリポジトリがセキュリティのベストプラクティスに準拠しているかを継続的に監視する GitHub アプリです。Allstar がセキュリティポリシーの違反を検出すると、Issue を作成してリポジトリまたは組織の所有者に警告します。一部のセキュリティポリシーでは、Allstar は違反の原因となったプロジェクト設定を自動的に変更し、期待される状態に戻すこともできます。
Allstar の目標は、プロジェクトのセキュリティに影響を与えるファイルや設定をきめ細かく制御できるようにすることです。セキュリティポリシーを組織レベルとリポジトリレベルの両方で監視するかどうか、およびポリシー違反の処理方法を選択できます。また、新しいポリシーを開発したり、既存のポリシーに貢献したりすることもできます。
Allstar は OpenSSF Scorecard プロジェクトの一部として開発されています。
Allstar によって不要な Issue が作成されている場合は、これらの手順 に従ってオプトアウトしてください。
Allstar は高度に構成可能です。主に3つのレベルの制御があります。
これらの設定は、組織の .allstar リポジトリで行われます。
リポジトリレベル: Allstar を使用している組織のリポジトリメンテナは、リポジトリを組織レベルの強制ルールからオプトインまたはオプトアウトすることを選択できます。注: これらのリポジトリレベルの制御は、組織レベルの設定で「リポジトリオーバーライド」が許可されている場合にのみ機能します。これらの設定は、リポジトリの .allstar ディレクトリで行われます。
ポリシーレベル: 管理者またはメンテナは、特定のリポジトリで有効にするポリシーと、ポリシー違反時に Allstar が実行するアクションを選択できます。これらの設定は、組織の .allstar リポジトリ（管理者）またはリポジトリの .allstar ディレクトリ（メンテナ）にあるポリシー yaml ファイルで行われます。
組織レベルで Allstar をインストールする前に、Allstar を実行するリポジトリのおおよその数を決定する必要があります。これにより、オプトイン戦略とオプトアウト戦略のどちらを選択するかを決めるのに役立ちます。
オプトイン戦略 では、Allstar を実行させたいリポジトリを手動で追加できます。リポジトリを指定しない場合、インストールされていても Allstar は実行されません。ポリシーを全リポジトリのうち少数にのみ適用したい場合、またはより多くのリポジトリで有効にする前に単一のリポジトリで Allstar を試してみたい場合は、オプトイン戦略を選択してください。v4.3リリース以降、グロブを使用して類似した名前の複数のリポジトリを簡単に追加できます。
オプトアウト戦略（推奨） では、すべてのリポジトリで Allstar が有効になり、Allstar の強制ルールからオプトアウトするリポジトリを手動で選択できます。すべてのパブリックリポジトリ、またはすべてのプライベートリポジトリをオプトアウトすることもできます。組織内のすべてのリポジトリで Allstar を実行したい場合、または少数のリポジトリや特定のタイプ（例: 公開 vs 非公開）のリポジトリのみをオプトアウトしたい場合は、このオプションを選択してください。v4.3リリース以降、グロブを使用して類似した名前の複数のリポジトリを簡単に追加できます。
クイックスタート と 手動インストール の両方のオプションでは、Allstar アプリ を GitHub 組織にインストールします。Allstar アプリは OpenSSF によって運用されており、ほとんどのオープンソースリポジトリに適した選択肢です。要求される権限を確認できます。アプリは、セキュリティコンプライアンスを検出するために、ほとんどの設定とファイルコンテンツへの読み取りアクセスを要求します。Issue とチェックへの書き込みアクセスを要求し、Issue を作成して block アクションを許可できるようにします。
OpenSSF 運用の Allstar アプリを使用したくない場合は、Allstar をセルフホスト して、独自の Allstar アプリを作成できます。これにより、アプリを直接制御できますが、アプリの設定、セキュリティ保護、監視、および保守を行う必要があります。
OpenSSF 管理の Allstar アプリの使用を妨げる特定のセキュリティまたはコンプライアンスの制約がない限り、クイックスタートまたは手動インストールをお勧めします。
このインストールオプションでは、組織内のすべてのリポジトリでオプトアウト戦略を使用して Allstar を有効にします。現在のすべてのポリシーが有効になり、Allstar はポリシー違反を Issue の提出によって警告します。これは Allstar を使い始めるための最も迅速かつ簡単な方法であり、後でいつでも設定を変更できます。
手間: 非常に簡単
手順:
.allstar と入力しますこれで完了です! 現在のすべての Allstar ポリシー がすべてのリポジトリで有効になりました。ポリシー違反がある場合、Allstar は Issue を作成します。
設定を変更するには、手動インストールの手順 を参照してください。
このインストールオプションでは、オプトイン戦略またはオプトアウト戦略に従って設定ファイルを作成する手順を説明します。このオプションでは、最初からより詳細な設定制御が可能です。
手間: 中程度
手順:
本当に必要な場合のみセルフホストしてください! Allstar アプリは設定、セキュリティ保護、および継続的なメンテナンスが必要です。新しい Allstar バージョンがリリースされたら、セルフホストソリューションをアップグレードする必要があります。
2 つのセルフホストアプローチを説明します。
このインストールオプションでは、GitHub Actions を使用してスケジュールジョブとして Allstar を実行します。
手間: 高い
GitHub Actions インストール手順 に従って:
.allstar コントロールリポジトリを作成します。（OpenSSF 管理の Allstar アプリを組織にインストールする手順は無視してください。）.allstar に定期的な GitHub Action を設定して、Allstar をバッチモードで実行します。このインストールオプションでは、Allstar を永続的なプロセスとして実行します。
手間: 非常に高い
詳細については、オペレーター向け手順 を参照してください。Allstar アプリの作成、シークレットの管理、利用可能な環境変数などが含まれます。
各ポリシーは、リポジトリが準拠していないことを検出したときに Allstar が実行するアクションを設定できます。
log: これがデフォルトのアクションで、実際にはすべてのアクションで行われます。すべてのポリシー実行結果と詳細がログに記録されます。ログは現在アプリオペレーターのみが表示でき、これらを公開する計画については議論中です。issue: このアクションは GitHub Issue を作成します。1つのポリシーにつき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)です。
このポリシーは[スコアカードのチェック](https://github.com/ossf/scorecard/#scorecard-checks)を組み込んでいます。準拠するには、リポジトリからバイナリアーティファクトを削除してください。スコアカードの結果は冗長になる可能性があるため、詳細情報をすべて確認するには、[スコアカード自体](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スコアカードのドキュメント](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)を参照してください。
### 汎用スコアカードチェック
このポリシーの設定ファイルは `scorecard.yaml` という名前で、[設定定義はこちら](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig)です。
このポリシーは、`checks` 設定にリストされているすべてのスコアカードチェックを実行します。実行されるすべてのチェックは、`threshold` 設定以上のスコアを持っている必要があります。各チェックの詳細については、[OpenSSFスコアカードのドキュメント](https://github.com/ossf/scorecard/blob/main/docs/checks.md)を参照してください。
#### SARIFアップロード
スコアカードポリシーは、オプションで結果を[SARIF](https://sarifweb.azurewebsites.net/)として各リポジトリの **Security > Code Scanning** タブにアップロードできます。これにより、組織管理者はリポジトリごとのワークフロー設定を必要とせずに、他のセキュリティツール（CodeQL、Dependabotなど）と一緒にスコアカードの結果を可視化できます。
SARIFアップロードを有効にするには、`scorecard.yaml` に `upload` フィールドを追加します：```yaml
optConfig:
optOutStrategy: true
action: issue
checks:
- Binary-Artifacts
- Signed-Releases
threshold: 8
upload:
sarif: true
必要条件:
security_events）。
セルフホスト運用者は、この権限を GitHub App に追加する必要があります。OpenSSF が運用するパブリック Allstar App には、まだこの権限は含まれていません。SARIF のアップロードは、セルフホストデプロイモード（サービスデーモンとしての実行、または GitHub Action としての実行）の両方で機能します。
このポリシーの設定ファイルは actions.yaml という名前で、設定定義はこちら です。
このポリシーは、各リポジトリの GitHub Actions ワークフロー設定ファイル（.github/workflows）（場合によってはワークフロー実行）をチェックし、ポリシーの組織レベル設定で定義されたルール（例：必須、拒否）に準拠していることを確認します。
このポリシーの設定ファイルは admin.yaml という名前で、設定定義はこちら です。
このポリシーは、デフォルトですべてのリポジトリに管理者としてユーザーまたはグループが割り当てられていることを確認します。ユーザーが管理者になることを許可するかどうか（チームではなく）をオプションで設定できます。
Allstar 設定の使用例として、このリポジトリ を参照してください。組織の管理者として、Allstar が組織内でどのように使用されているかについての情報を含む README.md を検討してください。
デフォルトでは、上記の allstar.yaml などの組織レベルの設定ファイルは、.allstar リポジトリに配置されることが想定されています。このリポジトリが存在しない場合、.github リポジトリの allstar ディレクトリが二次的な場所として使用されます。明確にするため、allstar.yaml の場合：
| 優先順位 | リポジトリ | パス |
|---|---|---|
| 優先 | .allstar | allstar.yaml |
| 二次 | .github | allstar/allstar.yaml |
これは、後述する個々のポリシーの組織レベルの設定ファイルにも当てはまります。
Allstar は、組織の .allstar リポジトリ内の、リポジトリと同じ名前のディレクトリにあるリポジトリレベルのポリシー設定も検索します。この設定は、"repo override" が無効になっているかどうかに関係なく使用されます。
たとえば、Allstar は特定のリポジトリ myapp のポリシー設定を以下の順序で検索します。
組織レベルの Allstar およびポリシー設定ファイルでは、フィールド baseConfig を指定して、ベース Allstar 設定を含む別のリポジトリを指定できます。これは例で説明するのが最適です。
複数の GitHub 組織があるが、単一の Allstar 設定を維持したいとします。メインの組織は "acme" で、リポジトリ acme/.allstar に allstar.yaml が含まれています：```yaml
optConfig:
optOutStrategy: true
issueLabel: allstar-acme
issueFooter: Issue created by Acme security team.
また、サテライトのGitHub Organization「acme-sat」があります。メインの設定を再利用したいが、特定のリポジトリでAllstarを無効にすることでいくつかの変更を適用したいとします。リポジトリ `acme-sat/.allstar` には `allstar.yaml` が含まれています：```yaml
baseConfig: acme/.allstar
optConfig:
optOutRepos:
- acmesat-one
- acmesat-two
これは acme/.allstar のすべての設定をベース設定として使用し、その上で現在のファイルの変更をベース設定に適用します。この適用方法は JSON Merge Patch として説明されています。baseConfig は GitHub の <org>/<repository> でなければなりません。
CONTRIBUTING.md をご覧ください。
| オプトアウト（推奨） 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 強制ルールにオプトインできない。 |
| リポジトリ | パス | 条件 |
|---|
myapp | .allstar/branch_protection.yaml | "repo override" が許可されている場合。 |
.allstar | myapp/branch_protection.yaml | 常に。 |
.allstar | branch_protection.yaml | 常に。 |
.github | allstar/myapp/branch_protection.yaml | .allstar リポジトリが存在しない場合。 |
.github | allstar/branch_protection.yaml | .allstar リポジトリが存在しない場合。 |