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-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 — 複数のメンテナーがいる場合にのみ提案します。単独の場合はスキップします。
• 連絡先メールアドレス — セキュリティ／行動規範の報告先メールアドレスを確認します。提示されなかった場合は、{{CONTACT_EMAIL}} というプレースホルダーをそのまま記載した CODE_OF_CONDUCT.md または SECURITY.md を作成せず、これら2つのファイルを用意する前に停止して確認します。

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 がサポートする言語がない

codeql.yml を用意する際は、リポジトリで検出した CodeQL 対応言語を使って、language マトリックス内の {{CODEQL_LANGUAGES}} を置換します（カンマ区切りで引用符付き。例："python", "go"）。

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

# Private vulnerability reporting
gh api -X PUT "repos/$REPO/private-vulnerability-reporting"

プライベートな脆弱性報告を有効にできない場合は、SECURITY.md を作成する前に、実在する連絡先メールアドレスをユーザーに確認してください。プレースホルダーの報告先に置き換えてはいけません。

プライベートリポジトリでは、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 と、head SHA をチェックアウトする actions/checkout を組み合わせた危険なパターン、および ${{ ... }} を使って 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])}'
gh api "repos/$REPO/private-vulnerability-reporting"
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 つは同時に使用できません。ユーザーが先にデフォルトを有効にしていると、ワークフローファイルと競合します。
• Token-Permissions の監査：softprops/action-gh-release などのアクションや、多くの公開アクションには contents: write が必要です。すべてのワークフローを読み取り専用にするようユーザーに伝えるのではなく、該当箇所を示して説明してください。
• pull_request_target はデフォルトで危険です：フォークからの PR でシークレットにアクセスする目的だけで使用しないでください。このスキルではその使用を検出します。ユーザーは、別の workflow_run またはラベル付き PR のパターンにリファクタリングしてください。
• OSSF バッジは自己申告です：バッジに合格しているということは、メンテナーが質問に回答したことを意味するのであり、監査が実施されたことを意味するものではありません。これは目安であって、保証ではありません。
• 小規模または新しいリポジトリの Scorecard スコア：Maintained チェックには 90 日間の活動が必要です。新しいリポジトリは、一定期間が経過するまでスコアが低くなります。これは不具合ではなく、仕様です。
• ピン留めされたワークフローのメンテナンス：スキャフォールディングされたワークフローでは、レビュー済みのコミット SHA を使用しています。Dependabot はバージョンコメント付きで SHA の更新を提案できます。マージ前にこれらの PR をレビューし、チェックサムまたはピン留めの根拠を最新の状態に保ってください。

参考資料

• references/scorecard-checks.md — Scorecard の全 18 項目のチェック、その測定内容、修正の指針をまとめた表です。
• 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 のルールを、具体例とともに説明します。