Nick2bad4u/GitHub-Security-CodeScanning-Alerts-Skill

GitHub セキュリティアラート管理スキル

概要

このスキルは、ユーザーが GitHub リポジトリのセキュリティアラートを調査または管理したい場合に使用します。対象は以下の通りです:

• コードスキャンアラート
• Dependabot アラート
• Dependabot マルウェアアラート
• シークレットスキャンアラート
• シークレットスキャンアラートの位置情報
• シークレットスキャンのスキャン履歴
• リポジトリのセキュリティ設定概要
• リポジトリ間での生の GitHub セキュリティ API 検査
• オフライントリアージまたはレポート作成のための一括アラートエクスポート
• 大量クリーンアップワークフローのための一括アラート更新

バンドルされているヘルパーはリポジトリに依存しません:

• --repo で任意のローカルチェックアウトを指定
• git リモートから owner/repo と GitHub ホストを自動検出
• もしくは --repository owner/repo で明示的に指定
• 環境変数を介して認証し、トークンをコマンドラインに記載しない
• カスタム環境用に API または Web のベース URL をオプションで上書き可能

互換性

Python 3 が必要です。 GITHUB_TOKEN や GH_TOKEN などの環境変数でトークンを指定し、GitHub REST API を直接使用します。 GitHub.com および標準の GHES API ベース URL（git リモートから自動導出）をサポートし、未対応の機能に対しては生の API フォールバックも提供します。

呼び出しのヒント

ターゲットがローカルチェックアウトの場合は repo を使用します（デフォルトは .）。 自動検出が不十分な場合は、必要に応じて repository、api_base_url、web_base_url、token_env の各値をオプションで指定できます。 一般的なコマンドには、summary、export-alerts、bulk-update-alerts、repo-security-overview、list-code-scanning、show-code-scanning、update-code-scanning、list-dependabot、show-dependabot、update-dependabot、list-malware、show-malware、update-malware、list-secret-scanning、show-secret-scanning、update-secret-scanning、list-secret-locations、secret-scan-history、api-call などがあります。

セキュリティモデル

GitHub トークンをコマンド引数に直接貼り付けないでください。 ユーザーが明示的に非編集済みの秘密情報値を要求し、その露出リスクを確認した場合を除き、--show-secret-values を使用しないでください。編集済みのアラートメタデータ、シークレットの位置情報、有効性、解決状態を優先してください。修復のために非編集出力が必要な場合でも、秘密情報をチャット、Issue コメント、PR、コミット、ログ、保存されたレポートに貼り付けないでください。

推奨パターン:

$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText

リポジトリが異なる環境変数名を使用している場合は、事前にその変数をエクスポートするか、--token-env で変数名を指定してください。

例:

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --token-env GITHUB_TOKEN

共通 CLI オプション

• repo: ターゲットリポジトリのチェックアウト内のパス（デフォルト .）
• repository: オプションの明示的な owner/repo 上書き
• api_base_url: オプションの明示的な API ベース URL 上書き
• web_base_url: レンダリングされたリンク用のオプションの明示的な Web ベース URL 上書き
• token_env: トークンを含む環境変数名（オプション、フォールバック用に繰り返し指定可能）
• json: オプションの機械可読出力フラグ

マルウェアアラートに関する重要な注意点

GitHub はマルウェアの発見を Dependabot マルウェアアラート として表示します。

GitHub には、専用の REST サーフェスを持つ独立したリポジトリアラートファミリーはありません。そのため、バンドルされているヘルパーはマルウェアを Dependabot アラートのフィルタリングされたサブセットとして扱い、各アラートのアドバイザリ GHSA を GitHub Advisory Database と相互参照して、タイプが malware であるアドバイザリを特定します。

つまり:

• list-malware、show-malware、update-malware は Dependabot アラート API を基に動作します
• マルウェアの分類は、アドバイザリデータベースエンドポイントが利用可能な GitHub.com で最も強力です
• ターゲットホストでアドバイザリタイプの参照が利用できない場合、ヘルパーは推測せずにその状態を報告します

クイックスタート

1. 現在のセキュリティ状態を確認する

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."

2. リポジトリのセキュリティ設定概要を表示する

python "<path-to-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."

2.5 一括トリアージのために全アラートセットをエクスポートする

python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json

3. コードスキャン一覧の例

共通入力（repo、repository、api_base_url、web_base_url、token_env、json）に加え、コードスキャンのフィルター（state、severity、tool_name、tool_guid、ref、pr）を使用します。 出力はレンダリングされたテキストまたは機械可読な JSON として code_scanning_alerts を返します。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --severity high,error

3.5 一括却下または一括再オープン

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Accepted until the next dependency refresh." --limit 25 --dry-run --json

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface secret-scanning --select-state open --target-state resolved --resolution used_in_tests --limit 25 --dry-run --json

4. コードスキャンアラートを却下または再オープンする

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after manual review." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open

5. Dependabot 一覧の例

共通入力に加え、Dependabot フィルター（state、severity、ecosystem、package、manifest、has、assignee、scope）を使用します。 出力はレンダリングされたテキストまたは機械可読な JSON として dependabot_alerts を返します。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --has patch

6. Dependabot アラートを却下または再オープンする

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted until next quarterly upgrade." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open

7. マルウェア一覧の例

共通入力に加え、Dependabot ベースのマルウェアフィルター（state、severity、ecosystem、package、manifest、has）を使用します。 出力として malware_alerts と、アドバイザリタイプ分類の lookup_failures を返します。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --state open

8. シークレットスキャン一覧の例

共通入力に加え、シークレットスキャンフィルター（state、secret_type、resolution、assignee、validity、リーク/マルチリポジトリフラグ）を使用します。 出力はシークレット値がデフォルトで編集された secret_scanning_alerts を返します。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open

シークレット値はデフォルトで非表示になります。ユーザーが明示的に非編集出力の必要性を確認しない限り、このデフォルトを維持してください。

9. シークレットスキャンアラートを解決または再オープンする

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revoked and rotated." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open

10. シークレットの位置情報とスキャン履歴を表示する

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11
python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "."

11. 未対応の機能には生の API フォールバックを使用する

python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/code-scanning/default-setup

ワークフロー

1. 認証を安全に解決する。
   • 環境変数（例：GITHUB_TOKEN）を推奨します。
   • 必要に応じて、シークレットマネージャーから環境変数に読み込んでください。
   • トークンをログやチャット出力に絶対に表示しないでください。
2. ターゲットリポジトリを解決する。
   • --repo と git リモートからの自動検出を推奨します。
   • ローカルチェックアウトが利用できない場合や非標準の場合は --repository owner/repo にフォールバックします。
3. 現在の結果を確認する。
   • 最初に summary を実行します。
   • より詳細なマルチサーフェス JSON スナップショットが必要な場合は export-alerts を使用します。
   • 対象のアラートファミリーに対して list/show コマンドを使用します。
   • 有効化や利用可能なセキュリティ設定に関する質問には repo-security-overview を使用します。
4. 結果を分類する。
   • 適切な場合は、コードや依存関係設定の実際の欠陥を修正します。
   • 明確な正当性がある場合のみ却下します。
   • 以前の却下や解決がもはや有効でない場合は、アラートを再オープンします。
   • リポジトリに数十から数百の、すでにレビュー済みで誤ってトリアージされたアラートがあり、同じアクションが必要な場合は bulk-update-alerts を使用します。
5. 変更を慎重に適用する。
   • リスクの高い変更には、まず --dry-run を推奨します。
   • 簡潔で実行可能な却下または解決コメントを追加します。
   • 書き込み操作には対応する GitHub 権限が必要であることに注意してください。
6. 変更後の状態を確認する。
   • 該当する list/show コマンドを再実行します。
   • コードや依存関係の修正の場合、アラートが自然に消えると予想される場合は、次の GitHub 分析サイクルを待ちます。

バンドルリソース

ヘルパースクリプト

scripts/manage_github_security_alerts.py は、GitHub リポジトリセキュリティアラート用のリポジトリ依存のないヘルパーです。

サポートされているコマンド:

• summary
• export-alerts
• bulk-update-alerts
• repo-security-overview
• list-code-scanning
• show-code-scanning
• update-code-scanning
• list-dependabot
• show-dependabot
• update-dependabot
• list-malware
• show-malware
• update-malware
• list-secret-scanning
• show-secret-scanning
• update-secret-scanning
• list-secret-locations
• secret-scan-history
• api-call

実装モジュール:

• github_security_api.py
• github_security_cli.py
• github_security_common.py
• github_security_operations.py
• github_security_render.py

使用例:

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after review." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted temporarily." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revoked and rotated." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json