Scorecard Governance — 手動設定ガイド

OpenSSF Scorecard が指摘する 5 件のガバナンス項目は、いずれもリポジトリ設定 / 運用変更が必要で、PR では解消できません。各項目の対応コストと手順をまとめます。

サマリ

1. BranchProtection — master ブランチ保護

Scorecard 指摘: branch protection not enabled for branch 'master'

手順（GitHub UI）

1. Settings → Branches を開く
2. Add branch protection rule をクリック
3. Branch name pattern: master
4. 以下にチェック（推奨セット）:
   • ✅ Require a pull request before merging
     • ✅ Require approvals (count: 1 以上) — これで CodeReview alert も解消
     • ✅ Dismiss stale pull request approvals when new commits are pushed
   • ✅ Require status checks to pass before merging
     • ✅ Require branches to be up to date before merging
     • 必須チェック追加: Lint & Type Check, Test / Python 3.11, Test / Python 3.12, Build package
   • ✅ Require linear history（推奨）
   • ✅ Do not allow bypassing the above settings（管理者にも適用）
5. Create をクリック

gh api -X PUT repos/killertcell428/aigis/branches/master/protection \
  -F required_status_checks.strict=true \
  -F 'required_status_checks.contexts[]=Lint & Type Check' \
  -F 'required_status_checks.contexts[]=Test / Python 3.11 (ubuntu-latest)' \
  -F 'required_status_checks.contexts[]=Test / Python 3.12 (ubuntu-latest)' \
  -F 'required_status_checks.contexts[]=Build package' \
  -F enforce_admins=true \
  -F required_pull_request_reviews.required_approving_review_count=1 \
  -F required_pull_request_reviews.dismiss_stale_reviews=true \
  -F restrictions= \
  -F required_linear_history=true \
  -F allow_force_pushes=false \
  -F allow_deletions=false

現状（2026-05-19 時点）と Scorecard alert #8 の扱い

本リポは既に以下の Branch Protection を有効化済（gh api repos/killertcell428/aigis/branches/master/protection で確認）:

• ✅ Required status checks (strict): Lint & Type Check, Test / Python 3.11, Test / Python 3.12
• ✅ Required signatures (signed commits)
• ✅ Enforce admins
• ✅ Required linear history
• ✅ Required conversation resolution
• ✅ allow_force_pushes = false / allow_deletions = false
• ✅ dismiss_stale_reviews = true / require_code_owner_reviews = true
• ⚠️ required_approving_review_count = 0 — 1 人開発のため意図的

Scorecard alert #8 Branch-Protection (High) が残っているのは、最後の required_approving_review_count = 0 に起因する。これは「自分の PR を自分でマージできる必要がある」というソロ開発の現実的制約で、外部コントリビュータが現れたら approval=1 に上げる方針。Won't fix として dismiss する。

dismiss 文言テンプレ:

Won't fix — solo developer repo. Branch protection enforces status
checks, signed commits, linear history, and admin enforcement; only
required_approving_review_count is 0 (would block all merges otherwise).
Will raise to 1 once a second maintainer joins.
See docs/scorecard-governance-setup.html §1.

2. Maintained — リポジトリ作成から90日未満

Scorecard 指摘: Repository was created within the last 90 days

これは「メンテされていることの証拠が不足している」という指摘で、リポジトリが 90 日以上経過して継続的にコミットがあれば自動的に解消されます。対応不要。

気になる場合の対応

Scorecard alert を Code scanning UI から Dismiss → Won't fix で消すこともできます（コメント例: "Repo just created; will resolve naturally with time."）。

3. CodeReview — 30 changeset 中 0 件が approved review

Scorecard 指摘: Found 0/30 approved changesets

BranchProtection で Require approvals (1+) を有効化し、今後のマージは PR 経由＋承認必須にすれば、徐々に approved changeset が積み上がってスコアが上がります。BranchProtection の設定と同時に解決可能。

4. CIIBestPractices — OpenSSF Best Practices バッジ未取得

Scorecard 指摘: no effort to earn an OpenSSF best practices badge detected

手順

1. bestpractices.dev にアクセス
2. GET YOUR BADGE NOW → GitHub でログイン
3. Submit a New Project をクリック
4. プロジェクト情報入力:
   • URL: https://github.com/killertcell428/aigis
   • Description: "LLM guardrail / prompt injection detection toolkit"
5. 67 個の質問に回答（"passing" レベルなら数十分）。多くは既にこのリポで満たしている内容（README、LICENSE、CI、テストカバレッジ等）
6. 取得後、バッジを README に貼る（例:）

   [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<ID>/badge)](https://www.bestpractices.dev/projects/<ID>)

このバッジが README に存在するだけで Scorecard はパスを検出します。

5. Fuzzing — fuzzer 統合なし

Scorecard 指摘: no fuzzer integrations found

このリポの主要コードパス（detector regex / decoder pipeline）はファジング対象として有意義です。ただし統合には数日の作業が必要。

推奨アプローチ: Atheris (Python ネイティブ)

Google の Atheris を使うと、Python 関数を libFuzzer ハーネスで fuzz できます。

1. fuzz/ ディレクトリ作成
2. 例: fuzz/fuzz_scan.py

   import atheris
   import sys
   with atheris.instrument_imports():
       from aigis import scan
   
   def TestOneInput(data: bytes):
       try:
           text = data.decode("utf-8", errors="replace")
       except Exception:
           return
       scan(text)
   
   atheris.Setup(sys.argv, TestOneInput)
   atheris.Fuzz()

3. CI に .github/workflows/cifuzz.yml を追加（OSS-Fuzz の CIFuzz アクション利用が標準）
4. 本格運用するなら OSS-Fuzz へ申請

後回しでOK。先に他の項目を片付けてから検討。

6. 受容方針 — Token-Permissions (job-level) と Pinned-Dependencies (local install)

Scorecard が High / Medium で機械的に検出するが、構成上「これ以上絞れない／絞ると別のリスクが増える」種類のアラートを明示的に受容する方針を以下に定める。新しいアラートが同じカテゴリで上がった場合、本セクションに照らして dismiss 可否を判断する。

6.1 Token-Permissions: job-level contents: write は許容、top-level は禁止

方針:

• すべての workflow は top-level で permissions: contents: read（または最小権限）を設定する。
• write 権限は 必要な job の permissions: ブロックでのみ付与する。
• 上記を満たしていれば、Scorecard が job-level write を High として検出しても dismiss 可。

根拠:

• GitHub Actions の GITHUB_TOKEN は job 単位でスコープされるため、job-level に絞った時点で他 job への漏出は防げる。
• Scorecard の Token-Permissions チェックは write の出現を機械的にカウントするため、正しいスコープであっても High として残る既知の挙動。
• これを完全に消すには Deploy Key / GitHub App Token に置き換える必要があるが、シークレット管理コスト・監査トレイル変更のデメリットが運用上のリスク低減を上回る。

対応済アラート:

dismiss 文言テンプレ（Code scanning UI で使用）:

Won't fix — job-level permissions are correctly scoped per
docs/scorecard-governance-setup.html §6.1.
Top-level is contents:read; this job's write scope is the
minimum required for its function.

6.2 Pinned-Dependencies: ローカルソースの pip install は許容

方針:

• PyPI / 外部 registry から取得する依存は version pin を必須とし、可能なら hash pin（--require-hashes）を導入する。
• ローカルソース (pip install .) は hash pin 不要として受容する。
• コンテナイメージは digest pin を必須とする (§ Dockerfile / .clusterfuzzlite/Dockerfile ともに digest pin 済)。

根拠:

• ローカルソース install はネットワークから wheel/sdist を取得しないため、サプライチェーン経由の改ざんリスクが存在しない。
• fuzz harness の build 環境内で完結しており、攻撃面が無い。

対応済アラート:

dismiss 文言テンプレ:

Won't fix — installs local source only (no PyPI download),
no supply-chain surface. See docs/scorecard-governance-setup.html §6.2.

6.3 判断保留

以下は受容も修正もせず、運用コストとのトレードオフを継続検討する:

• #174 Dockerfile:6 の pip install pip==26.1.1 build==1.5.0 の hash pin 化。pip-compile --generate-hashes 運用が現実的か要検討。

完了確認

すべて設定後、Scorecard を再実行して結果を確認できます:

# GitHub Actions の Scorecard workflow を手動実行
gh workflow run scorecard.yml -R killertcell428/aigis

# または scorecard CLI（要 GITHUB_AUTH_TOKEN）
docker run -e GITHUB_AUTH_TOKEN=ghp_xxx \
  gcr.io/openssf/scorecard:stable \
  --repo=github.com/killertcell428/aigis

Code scanning UI でアラートが Closed に変わります（次回スキャン後）。

Generated 2026-05-11 — Aigis governance setup guide