oss-hygiene

oss-hygiene

公開されている GitHub リポジトリを、GitHub Community Standards のベースラインと OpenSSF Scorecard のサプライチェーンベースラインに適合させ、OpenSSF Best Practices Badge の取得に向けて準備します。

これは /gh-bootstrap と併用するもので、別の課題に対応します。gh-bootstrap はマージに関する設定を整え、oss-hygiene はコントリビューター向けの環境とサプライチェーンに関する設定を整えます。

このスキルの用途

対象	スキル
マージボタン、ブランチ保護、リリースノートの設定	/gh-bootstrap
コミュニティ用ファイル、サプライチェーンのチェック、OSSF の取り組み状況	/oss-hygiene（このスキル）
多数のリポジトリにまたがる組織全体の設定をコードで管理	/safe-settings
タスクごとの PR／Issue／CI 運用	/gh

まず /gh-bootstrap を実行して main を保護し、その後 /oss-hygiene を実行して、コントリビューターが参加しやすいようにし、サプライチェーンのチェックで PR を制御します。

設定される内容

このスキルは、相互に独立した 3 つの領域に対応します。すべてのファイルを assets/ のテンプレートと比較し、既存のファイルを上書きする前に確認を求めます。

領域 1 — GitHub Community Standards

リポジトリの Insights にある「Community Standards」タブには、次のファイルが表示されます。ファイルがない場合、チェックリストは不合格になります。

ファイル	元となるアセット	目的
README.md	（ひな形は作成しません — リポジトリ独自のファイルです）	有無の確認のみ
LICENSE	（ひな形は作成しません — ライセンスを選択する必要があります）	有無の確認のみ
CODE_OF_CONDUCT.md	assets/CODE_OF_CONDUCT.md	Contributor Covenant 2.1
CONTRIBUTING.md	assets/CONTRIBUTING.md	Issue の作成、PR の送信、テストの実行方法
SECURITY.md	assets/SECURITY.md	脆弱性の報告（非公開のアドバイザリー）
.github/ISSUE_TEMPLATE/bug_report.yml	assets/.github/ISSUE_TEMPLATE/bug_report.yml	構造化されたバグ報告フォーム
.github/ISSUE_TEMPLATE/feature_request.yml	assets/.github/ISSUE_TEMPLATE/feature_request.yml	構造化された機能リクエストフォーム
.github/ISSUE_TEMPLATE/config.yml	assets/.github/ISSUE_TEMPLATE/config.yml	空の Issue を無効化し、連絡先へのリンクを設定
.github/PULL_REQUEST_TEMPLATE.md	assets/.github/PULL_REQUEST_TEMPLATE.md	PR チェックリスト

LICENSE がない場合、黙ってひな形を作成しないでください。ライセンスの選択（MIT、Apache-2.0、AGPL-3.0 など）は判断が必要です。不足していることを示し、ユーザーに https://choosealicense.com/ を案内してください。

README がない、または内容が薄い場合は警告を表示しますが、自動生成はしないでください。README の内容はプロジェクトの声を表すものです。

Surface 2 — サプライチェーン（Scorecard のチェック項目）

OpenSSF Scorecard は約 18 項目の自動チェックを実行します。このスキルでは、ひな形で対応できる項目を組み込みます。

Scorecard のチェック項目	リスク	対応
Security-Policy	中	SECURITY.md（Surface 1）
License	低	LICENSE（Surface 1。表面上のみ）
Dependency-Update-Tool	高	assets/.github/dependabot.yml
Branch-Protection	高	/gh-bootstrap のルールセットで対応
Code-Review	高	/gh-bootstrap の PR ルールで対応
CI-Tests	低	リポジトリの既存 CI
Token-Permissions	高	既存のワークフローで permissions: ブロックを監査し、結果のみ報告
Dangerous-Workflow	重大	監査のみ — pull_request_target と、head ref の actions/checkout の併用に警告
SAST	中	assets/.github/workflows/codeql.yml（該当する場合）
Pinned-Dependencies	中	結果のみ報告 — ピン留めはエコシステムごとに異なり、議論の余地があるため
Maintained	高	受動的 — 実際の活動を通じて評価
Binary-Artifacts	高	ツリー内の .so、.dll、.jar、.exe、.zip、.tgz をスキャンして警告
Vulnerabilities	高	受動的 — Dependabot のアラートで対応
Signed-Releases	高	結果のみ報告 — sigstore の組み込み方法はプロジェクト固有
Fuzzing	中	結果のみ報告 — 言語固有
Packaging	中	結果のみ報告 — リリースパイプラインによって異なる
Contributors	低	受動的
CII-Best-Practices	低	Surface 3

さらに、リポジトリのファイルには追加されない GitHub ネイティブの Code Security 機能があります。

機能	有効化方法	対応
Dependabot アラート	リポジトリの Settings → Advanced Security（公開リポジトリでは自動的に有効）	API で確認
Secret scanning アラート（ユーザー向け）	リポジトリの Settings → Advanced Security（公開リポジトリでは無料、オプトイン）	API で有効化
Push protection（secret scanning）	リポジトリの Settings → Advanced Security	API で有効化
Dependency graph	リポジトリの Settings → Security（公開リポジトリでは自動的に有効）	API で確認
Dependency Review Action	assets/.github/workflows/dependency-review.yml	ひな形を作成
Scorecard の公開	assets/.github/workflows/scorecard.yml	ひな形を作成（バッジ用に SARIF をアップロード）

Surface 3 — OpenSSF Best Practices Badge

このバッジは https://www.bestpractices.dev で自己申告します。このスキルでは記入しません。プロジェクトのオーナーが記入する必要があります。このスキルで行うことは次のとおりです。

1. リポジトリにすでにバッジがあるか確認します（README 内のバッジ URL を検索します）。
2. リポジトリ URL をあらかじめ入力した登録リンクを表示します。
3. README にバッジの Markdown を追加するよう提案します（assets/README-badge-snippet.md）。

このバッジは Scorecard の CII-Best-Practices チェックを有効にするものです。進行中の段階でも登録すれば、最小限の手間でスコアを上げられます。

プロトコル

1. 対象範囲を確認し、現在の状態を調べる

gh auth status
gh repo view --json nameWithOwner,visibility,isPrivate,licenseInfo,description
gh api "repos/$REPO/community/profile" --jq '{
  health_percentage,
  files: (.files | to_entries | map(select(.value != null)) | from_entries | keys)
}'
gh api "repos/$REPO/vulnerability-alerts" 2>/dev/null && echo "dependabot alerts: ON" || echo "dependabot alerts: OFF"
gh api "repos/$REPO" --jq '{
  secret_scanning: .security_and_analysis.secret_scanning.status,
  push_protection: .security_and_analysis.secret_scanning_push_protection.status
}'

すべての判断事項を含めた質問を、一度だけ、まとめてユーザーに尋ねます。順番に質問してはいけません。ユーザーが「デフォルトで進めて」と返信すれば、スキルをそのまま実行できるようにします。以下の項目に限定し、5項目を超えないようにします。

• 公開範囲 — このスキルは公開リポジトリ向けに設計されています。プライベートリポジトリでは一部を利用できます（コミュニティファイルは利用可能、シークレットスキャンには Advanced Security が必要、Scorecard の公開にはバッジを表示するための公開設定が必要です）。
• ライセンス — licenseInfo が null の場合、選択肢を提示し、ユーザーがライセンスを選ぶまで停止します。
• CodeQL の適用可否 — リポジトリに CodeQL がサポートする言語（actions、c-cpp、csharp、go、java-kotlin、javascript-typescript、python、ruby、swift）のコードが含まれているかを確認します。含まれていない場合は、CodeQL ワークフローをスキップします。該当するのが CI ヘルパースクリプト（例：.github/scripts/*.py）だけの場合は、質問を強制せず、推奨事項を提示します。これらはプロジェクトのコードではないため、デフォルトではスキップし、ユーザーが希望する場合にのみ有効にします。
• FUNDING.yml — ユーザーがスポンサーシップを受け付けるか確認します。受け付ける場合は、プラットフォームとハンドル名（GitHub Sponsors、Buy Me a Coffee、Ko-fi、OpenCollective など）を尋ねます。
• CODEOWNERS — リポジトリに複数のメンテナーがいる場合にのみ提案します。単独の場合はスキップします。

2. コミュニティファイルを雛形から作成する

assets/ 内の各ファイルについて、次の順番で実行します。

CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
.github/ISSUE_TEMPLATE/bug_report.yml
.github/ISSUE_TEMPLATE/feature_request.yml
.github/ISSUE_TEMPLATE/config.yml
.github/PULL_REQUEST_TEMPLATE.md

既存ファイルがある場合は差分を確認します。異なる場合は、上書き前にユーザーに確認します。{{REPO}}、{{OWNER}}、{{CONTACT_EMAIL}} のプレースホルダーを置換します。

CONTRIBUTING.md には汎用的なひな型が含まれています。マージ後にプロジェクト固有の内容に調整するようユーザーに勧めます。

3. サプライチェーンのワークフローを雛形から作成する

アセット	配置先	スキップする条件
assets/.github/dependabot.yml	.github/dependabot.yml	なし（常に有用）
assets/.github/workflows/dependency-review.yml	.github/workflows/dependency-review.yml	Code Security が有効でないプライベートリポジトリ
assets/.github/workflows/scorecard.yml	.github/workflows/scorecard.yml	プライベートリポジトリ（バッジの表示には公開設定が必要）
assets/.github/workflows/codeql.yml	.github/workflows/codeql.yml	CodeQL がサポートする言語がリポジトリにない場合

dependabot.yml は、リポジトリで検出した言語のパッケージ（package.json、Cargo.toml、pyproject.toml、go.mod、Gemfile、composer.json、pom.xml などを確認）に加え、ワークフローのアクションのバージョンを最新に保つための github-actions エコシステムのエントリーを含むよう設定します。

マニフェストの検出範囲。 プロジェクトのソースルートにあるマニフェストのみを対象とし、.github/scripts/、.devcontainer/、tools/ci/、その他の CI ヘルパー用パスにあるものは対象にしません。プロジェクトのルートにある pyproject.toml は対象ですが、ワークフローにハードコードされた pip install foo==1.2.3 の行は対象外です。実際のトップレベルマニフェストがなければ、Dependabot はそれを追跡できません。言語の使用箇所が CI ヘルパーコードだけの場合は、そのエコシステムをスキップし、生成する dependabot.yml に理由を説明する1行コメントを追加します（例：「トップレベルの Python マニフェストはなく、Python コードは .github/scripts/ 内にのみ存在します」）。これは、ステップ1で CodeQL の適用可否を判断する際と同じヒューリスティックです。

4. GitHub 標準のセキュリティ機能を切り替える

gh api を使用して有効化または状態を確認します（冪等性があるため、再実行しても変更はありません）。

# Automated security fixes / Dependabot security updates
gh api -X PUT "repos/$REPO/automated-security-fixes"

# Vulnerability alerts (Dependabot alerts)
gh api -X PUT "repos/$REPO/vulnerability-alerts"

# Secret scanning alerts for users + push protection
gh api -X PATCH "repos/$REPO" \
  -F security_and_analysis[secret_scanning][status]=enabled \
  -F security_and_analysis[secret_scanning_push_protection][status]=enabled

プライベートリポジトリでは、GitHub Code Security が有料で有効化されていない場合、これらの操作で 403 エラーが発生することがあります。エラーにするのではなく、その旨を提示してスキップします。

5. 既存のワークフローで Token-Permissions と Dangerous-Workflow を監査する

これは検出であり、変更ではありません。このスキルは .github/workflows/*.yml の各ファイルを読み取ります。

• Token-Permissions： トップレベルの permissions: ブロックがないワークフロー、または permissions: write-all を使用しているワークフローにフラグを立てます。安全なデフォルトとして permissions: { contents: read } を提案し、各ジョブに必要な権限のみを追加します。
• Dangerous-Workflow： pull_request_target と、actions/checkout によるヘッド SHA のチェックアウトを組み合わせた危険なパターン、および ${{ ... }} を使用して github.event.* の入力をシェルスクリプトに埋め込むパターンにフラグを立てます。

検出結果を表示し、自動編集はしません。これらは慎重に変更する必要があるため、ユーザーが確認できるようにします。

6. OpenSSF Best Practices Badge の手順を案内する

適用せず、表示してください。登録後に <owner>、<repo>、プロジェクト ID を置き換えてください。assets/README-badge-snippet.md を読み、ステップ 3 で CodeQL をスキップした場合は、と のマーカーの間にあるブロックを削除してください。このマーカーは、曖昧さなくスニペットを条件に応じて削除できるようにするためのものです。

Register at: https://www.bestpractices.dev/en/projects/new
Repo URL:    https://github.com/<owner>/<repo>
Once you have a project ID, paste this into README.md:

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/<owner>/<repo>/badge)](https://scorecard.dev/viewer/?uri=github.com/<owner>/<repo>)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<id>/badge)](https://www.bestpractices.dev/projects/<id>)

このスキルは、ユーザーに代わってプロジェクトを登録しません。登録は、ユーザーが回答に証明を与える必要のある、認証と判断を伴う手順です。

7. 検証して報告する

コミュニティプロフィールとワークフローファイルを読み直してください。簡潔な概要を表示してください。

gh api "repos/$REPO/community/profile" --jq '{health_percentage, missing: ([.files | to_entries[] | select(.value == null) | .key])}'
ls .github/workflows/ | sort

概要では、以下を明記してください。

• 作成したもの（既存のものがある場合は差分も）
• すでに適切だったもの（変更なし）
• スキップしたものとその理由（LICENSE がない、プライベートリポジトリ、CodeQL 対応言語がないなど）
• OSSF バッジの登録リンク

冪等性

• ファイル：上書き前に差分を確認し、内容が異なる場合は確認してください。
• API の切り替え：PUT／PATCH は冪等です。
• ワークフローの監査：読み取り専用のため、再実行しても同じ結果が再表示されるだけです。
• 削除は禁止：以前の実行で成果物（名前の異なる古いワークフローなど）が残っている場合は、それを提示してユーザーに判断を委ねてください。

このスキルの対象外

• ライセンスの選定：不足を示すだけで、選定はしません
• README の作成：内容はプロジェクトの意向に委ねます
• 組織全体に適用するコミュニティファイル：その場合は /safe-settings を使用してください
• ブランチ保護／マージキュー：その場合は /gh-bootstrap を使用してください
• Sigstore によるリリース署名：言語やパイプラインに依存するため、対象外です
• OSSF Best Practices Badge の質問票への回答：これはメンテナーによる証明です
• 依存関係のピン留め：エコシステムごとに異なり、意見が分かれることもよくあります
• ファジングのセットアップ：言語に依存します

注意事項

• デフォルトのコミュニティヘルスファイル：ユーザーまたは組織が、これらのファイルを含む .github リポジトリを持っている場合、そのファイルは独自のコピーを持たないすべてのリポジトリに適用されます。リポジトリ内にファイルを作成すると組織のデフォルトが上書きされるため、リポジトリごとの上書きを意図している場合にのみ作成してください。
• Dependency Review Action：パブリックリポジトリでは無料で利用でき、プライベートリポジトリでは GitHub Advanced Security がある場合にのみ利用できます。プライベートかつ無料プランでは、ワークフローは必ず失敗します。
• Scorecard ワークフロー：scorecard.dev への OIDC 公開には id-token: write が必要です。アセットには適切な権限が設定されています。初回実行で 403 エラーによりワークフローが失敗する場合、ユーザーの組織レベルで OIDC が制限されています。
• CodeQL のセットアップモード：default セットアップは GitHub の UI（Settings → Code security → CodeQL → Set up）で設定します。アセットでは advanced セットアップ（ワークフローファイル）を使用します。この 2 つは併用できません。ユーザーが先に default を有効にしている場合、ワークフローファイルと競合します。
• Token-Permissions 監査：softprops/action-gh-release などのアクションや、多くの公開アクションには contents: write が必要です。すべてのワークフローを読み取り専用にするようユーザーに指示しないでください。問題を指摘し、説明してください。
• pull_request_target はデフォルトで危険です：フォークからの PR でシークレットにアクセスする目的だけで使用しないでください。このスキルは該当箇所を警告します。ユーザーは workflow_run またはラベル付き PR のパターンに分けてリファクタリングしてください。
• OSSF バッジは自己申告です：バッジに合格していることは、メンテナーが質問に回答したことを意味し、監査が実施されたことを意味するものではありません。これは指標であり、保証ではありません。
• 小規模または新しいリポジトリの Scorecard スコア：Maintained チェックには 90 日間の活動が必要です。新しいリポジトリのスコアは、経過期間が条件を満たすまで低くなります。これは不具合ではなく、仕様です。
• 作成したワークフローが自分自身に対して Pinned-Dependencies を検出する：dependency-review.yml、scorecard.yml、codeql.yml は、OSSF の参照テンプレートに合わせて読みやすさを保つため、可変タグ（@v4、@v2、@v3）を使用します。Scorecard の Pinned-Dependencies チェックは、初回実行時にこれらを検出します。意図的なトレードオフとして、このスキルで作成する Dependabot がタグを自動的に最新の状態に保ちますが、SHA のピン留めは気付かないうちに古くなります。Pinned-Dependencies のスコアを満点にしたい場合は、最初の Dependabot PR がマージされた後に、新しい 3 つのワークフローファイルをコミット SHA でピン留めしてください。その後、Dependabot がピン留めされた状態を維持します。

参考資料

• references/scorecard-checks.md — 18 項目すべての Scorecard チェック、その評価対象、修正方法のヒントをまとめた表。
• references/badge-criteria.md — OpenSSF Best Practices Badge の合格基準と、リポジトリ内の成果物との対応。
• references/community-standards.md — GitHub 独自のチェックリストと、各ファイルの検出方法。
• references/dependabot.md — dependabot.yml スキーマのリファレンスと、エコシステムごとの例。
• references/workflow-hardening.md — Token-Permissions と Dangerous-Workflow ルールの具体例。