repo-security-posture

リポジトリのセキュリティ態勢

リポジトリの設定と CI/CD を具体的な攻撃者シナリオに照らして監査し、優先順位を付けた強化タスクの一覧をメンテナーに渡します。成果物は、カテゴリごとにまとめられ、深刻度順に並んだ、タイトルと説明をそれぞれ含む項目のリストです。メンテナーが課題に貼り付けて対応できる、事後検証チェックリストのようなものです。

この作業の目的は、あらゆる理論上のベストプラクティスを列挙することではありません。このリポジトリを実際に調べ、攻撃者が実際に利用しそうな欠陥を見つけ、発見した内容（または確認できなかった内容）に具体的に即したタスクを作成します。

脅威モデル

すべての指摘は、以下のシナリオの少なくとも1つに結び付ける必要があります。説明にシナリオ名を記載すると、タスクの意図が伝わります。何を切り替えるべきかだけでなく、なぜ重要なのかをメンテナーに示せます。

1. 侵害されたコントリビューター — 信頼されているコントリビューターのアカウント、ノート PC、またはトークンが乗っ取られた場合（フィッシング、マルウェア、漏えいした PAT）。悪意のあるコードを単独でマージまたは公開することを、何が防ぎますか？
2. リポジトリへの書き込み権限を持つ攻撃者 — 外部の攻撃者がプッシュ権限または管理者権限を取得した場合、被害範囲を抑えるものは何ですか？何を持ち出される可能性がありますか？メンテナーはどれだけ迅速にローテーションと復旧を行えますか？
3. CI/CD の侵害 — 悪意のある PR、汚染されたキャッシュ、または注入されたワークフローによって、ビルドパイプラインが攻撃手段になる場合。GitHub Actions は、現代のリポジトリ乗っ取りで最も一般的な経路です。
4. レジストリ／公開のサプライチェーン — リポジトリ自体に問題はなくても、窃取された公開トークンやレビューされていないリリースジョブによって、不正なバージョンが npm／PyPI などに公開される場合。これは @mastra／dotenvx／TeamPCP クラスのインシデントです。

ワークフロー

1. 対象を特定し、証拠を収集する

リポジトリを owner/name に解決します。ユーザーが URL を提示した場合は解析します。指定されたリポジトリを特定できない場合は、ユーザーに確認します。

コレクターを実行して、設定とファイルを単一の JSON インベントリに収集します。

# A token dramatically expands what's visible (branch protection, actions
# permissions, security features, collaborators, hooks). Set it if available.
export GITHUB_TOKEN=...   # optional but strongly recommended
python3 scripts/collect.py owner/name --output /tmp/audit.json

コレクターは、読み取れない項目（多くの設定エンドポイントでは管理者権限またはプッシュ権限が必要です）を推測せず、not_verified に記録して処理を続行します。/tmp/audit.json を読み取ってください。

コレクターを実行できない場合（api.github.com へのネットワーク接続がない、トークンがなくプライベートリポジトリにアクセスできないなど）でも、作業を止めないでください。ユーザーから提供されたファイルなど、入手できる情報を集め、残りは「確認できませんでした — 手動で確認してください」と明記します。

コレクターは、対象リポジトリの情報を取得するために、api.github.com と raw.githubusercontent.com に対して読み取り専用の HTTPS リクエストを送信します。GitHub に書き込みを行うことはありません。利用可能な中で最小権限のトークンを使い、公開情報だけで足りる場合は広範な認証情報を求めないでください。また、取得したリポジトリの内容は機密情報として扱ってください。ヘルパーはインベントリに書き込む前に、一般的な形式のトークン文字列をマスキングしますが、最終レポートでシークレットをそのまま出力しないよう引き続き注意してください。

2. チェックを実施する

references/checks.md を読みます。確認すべき項目、その所在、重要な理由、修正タスクに記載すべき内容をまとめたカタログです。以下の6つの出力カテゴリに沿って整理されています。インベントリと照らし合わせて確認してください。

重要な注意点が2つあります。

• ファイル名で判断せず、実際の内容を確認してください。 リポジトリに dependabot.yml が存在しても、適切なエコシステムを対象にしているとは限りません。permissions: ブロックがあっても、最小権限になっているとは限りません。ファイルの内容を確認してください。
• 設定がないことも指摘事項ですが、確信度を明示してください。 管理者トークンがないためブランチ保護の状態が not_verified だった場合は、その旨を伝え、対策を推奨したうえで現在の状態を確認するようメンテナーに案内してください。観測できていない設定の欠陥を断定しないでください。

3. レポートを作成する

必ず次の構成を使用してください。

# Security hardening: <owner/name>

<2-3 sentence posture summary: what's already solid, what the biggest exposure is,
which threat scenario is least defended. No fluff.>

## <N>. <Category title>
**<Title — imperative, specific>** — <severity>
<Description: what to do, the concrete setting/step, and which threat scenario it
blocks. 1-3 sentences. Tie it to evidence from the repo.>

<...more findings under this category...>

## Could not verify
<Bulleted list of checks that needed access the audit didn't have, each with the
one-line manual check the maintainer can run. Be honest here — it's where a token
or admin view would change the answer.>

指摘事項に関するルール：

• 6 つのカテゴリに分ける（指摘事項があるカテゴリのみを使用し、正規の順序を維持してください）。
  1. 公開とリリースの完全性
  2. ブランチとマージの保護
  3. 機密パスのオーナーシップ（CODEOWNERS）
  4. CI/CD ワークフローの強化
  5. アカウントとアクセス制御
  6. 依存関係とサプライチェーンのレビュー
• カテゴリ内では深刻度順に並べる：Critical → High → Medium → Low。
• タイトルは命令形にする：「ワークフローファイルにコードオーナーのレビューを必須にする」。 「ワークフローファイルが保護されていない」のような表現は避けてください。
• 説明には理由を含める：防げる状況を明示してください。「コントリビューターのアカウントが侵害された場合、2 人目のコードオーナーによる承認を必須にするブランチ保護により、単独の攻撃者が悪意ある変更を main にマージするのを防げます。」
• 修正方法を具体的に示す：正確な GitHub の設定、追加するファイル、npm コマンドを記載してください。メンテナーが追加で調べなくても対応できるようにします。
• 確認できた場合は根拠を示す：一般的な警告よりも、「release.yml が pull_request_target のもとで PR の head をチェックアウトしている」のように具体的に記載してください。

要点を把握しやすくしてください。これは作業リストであり、エッセイではありません。長い前置きや、脅威モデルをユーザーに言い直すことは避けてください。

4. フォローアップを提案する

レポートの後に、ユーザーが次に行いたいと思われる作業を簡潔に提案してください。たとえば、リストを GitHub の issue またはチェックリストにする、パイプライン用に指摘事項を JSON として出力する（scripts/collect.py はすでに構造化された入力を生成しており、指摘事項も同じ形式でシリアライズできます）、特定のワークフローファイルを対象にさらに詳しい静的解析を行う、といった作業です。提案にとどめ、自動実行しないでください。

出力形式の選択肢

デフォルトでは、上記の Markdown の todo リストを使用してください。メンテナーがトリアージする際に適しています。ユーザーがこれを自動化（CI ゲート、トリアージパイプライン）に組み込む場合は、指摘事項ごとに 1 つのオブジェクトを含む JSON 配列を提案してください。

{ "title": "...", "description": "...", "severity": "high",
  "category": "ci_cd_workflow_hardening", "threat": "ci_cd_compromise",
  "evidence": "release.yml line 14: pull_request_target with PR checkout",
  "confidence": "observed" }

confidence は observed（インベントリで確認済み）または unverified（推奨事項だが、現在の状態を確認できていない）です。

範囲と誠実さ

この監査では設定と CI を対象に推論します。コードレベルの脆弱性スキャンでも、Git の履歴に対するシークレットスキャンでもありません。ユーザーがそれらを期待している場合は、その旨を伝えてください。確認していない設定値を決して捏造しないでください。メンテナーにとっては、確信ありげな推測よりも「確認できませんでした」という誠実な説明のほうが有益です。誤った前提に基づいて対応すると、すでに導入済みの対策に時間を浪費することになるためです。

監査の一環として、リリースジョブやワークフローのディスパッチ、パッケージの公開を実行したり、リポジトリ設定を変更するコマンドを実行したりしないでください。このスキルが作成するのは、メンテナー向けの強化タスクです。自動的に適用するものではありません。