gh-code-scanning

GitHub コードスキャンスキル

概要

GitHub のコードスキャンアラートは、CodeQL や Scorecard などの静的解析ツールによって生成され、GitHub の Security タブに表示されます。GitHub の Security タブにはデフォルトの MCP ツールセットからアクセスできないため、このスキルではすべての読み取り操作用のスクリプトを提供します。

前提条件

要件	詳細
pwsh	PowerShell 7 以降。https://learn.microsoft.com/powershell からインストールしてください
gh CLI	インストール済みで PATH に設定されていること。https://cli.github.com からインストールしてください
認証	gh auth login を実行するか、GH_TOKEN を設定してください。security_events スコープが必要です
スコープ	プライベートリポジトリでは security_events、パブリックリポジトリのみの場合は public_repo

repo スコープでも security_events の要件を満たせます。gh CLI が認証を自動的に処理するため、コマンドでトークンを明示的に渡す必要はありません。

Get-CodeScanningAlerts.ps1 は起動時に両方の前提条件を検証し、いずれかの確認に失敗した場合は、該当するエラーメッセージを表示して中止します。

クイックスタート

このコマンドを実行すると、オープンなコードスキャンアラートを件数の多い順に並べたグループ別の概要を取得できます。リポジトリのコードスキャン状況をトリアージする際は、まずこのコマンドを実行することを推奨します。

pwsh scripts/Get-CodeScanningAlerts.ps1 -Owner "{owner}" -Repo "{repo}" -OutputFormat Json

このコマンドは、発生件数の降順で並べたアラートグループの JSON 配列を返します。結果をプログラムで処理する場合は、必ず -OutputFormat Json を使用してください。

パラメーターリファレンス

パラメーター	型	必須	デフォルト	説明
-Owner	String	はい		リポジトリを所有する GitHub の組織またはユーザー
-Repo	String	はい		リポジトリ名
-OutputFormat	String	いいえ	Table	出力形式。エージェントがプログラムで処理する場合は必ず Json を使用してください。GroupedJson は Json の別名として使用できます
-Branch	String	いいえ	main	アラート結果の対象とするブランチ
-IncludeDismissedStillDetected	Switch	いいえ		ブランチ上で引き続き検出されている却下済みアラートも、Kind を dismissed-still-detected に設定したグループとして報告します

これらのパラメーターは Get-CodeScanningAlerts.ps1 に適用されます。-s {severity} や -d などの bash スクリプトのフラグについては、以下の「スクリプトリファレンス」セクションを参照してください。

スクリプトリファレンス

Get-CodeScanningAlerts.ps1

オープンなコードスキャンアラートを、発生件数の降順でグループ化して並べ替えます。

# JSON output for programmatic consumption
pwsh scripts/Get-CodeScanningAlerts.ps1 -Owner "{owner}" -Repo "{repo}" -OutputFormat Json

# Scope to a specific branch
pwsh scripts/Get-CodeScanningAlerts.ps1 -Owner "{owner}" -Repo "{repo}" -Branch "{branch}" -OutputFormat Json

# Also report dismissed alerts that are still detected
pwsh scripts/Get-CodeScanningAlerts.ps1 -Owner "{owner}" -Repo "{repo}" -OutputFormat Json -IncludeDismissedStillDetected

get-code-scanning-alerts.sh

オープンなコードスキャンアラートを、発生件数の降順でグループ化して並べ替えます。jq が必要です。

# JSON output for programmatic consumption
bash scripts/get-code-scanning-alerts.sh -o "{owner}" -r "{repo}"

# Scope to a specific branch
bash scripts/get-code-scanning-alerts.sh -o "{owner}" -r "{repo}" -b "{branch}"

# Filter by severity
bash scripts/get-code-scanning-alerts.sh -o "{owner}" -r "{repo}" -s critical

# Also report dismissed alerts that are still detected
bash scripts/get-code-scanning-alerts.sh -o "{owner}" -r "{repo}" -d

このスキルを使用する場合

コードスキャンアラートの読み取りのみを行うタスクで、このスキルを使用してください。コードスキャンアラートの一覧表示とグループ化に対応している方法は、Get-CodeScanningAlerts.ps1 のみです。一覧表示やグループ化の代替手段として gh api を使用してはいけません。

GitHub MCP サーバーで code_security ツールセットが設定されている場合、gh api を使わずにコードスキャンアラートへの読み取り専用アクセスが可能です。toolsets: all または明示的なツールセット設定で有効にしてください。

コードスキャンアラート

オープンアラートの一覧表示とグループ化

必ず -OutputFormat Json を指定して実行します。JSON 出力を解析し、ユーザーに提示してください。

pwsh scripts/Get-CodeScanningAlerts.ps1 -Owner "{owner}" -Repo "{repo}" -OutputFormat Json

main 以外のブランチを対象にするには、-Branch {branch} を使用します。

JSON 出力の形式

-OutputFormat Json は、グループオブジェクトの配列を返します。

[
  {
    "RuleDescription": "Empty except",
    "RuleId": "py/empty-except",
    "Tool": "CodeQL",
    "SecuritySeverity": null,
    "Severity": "warning",
    "Count": 23,
    "AffectedPaths": [
      "scripts/plugins/Sync-PluginManifest.ps1",
      "scripts/linting/Validate-MarkdownFrontmatter.py"
    ],
    "HasFilePaths": true,
    "AlertUrl": "https://github.com/microsoft/hve-core/security/code-scanning/42",
    "FindingDescription": "'except' clause does nothing but pass and there is no explanatory comment."
  },
  {
    "RuleDescription": "Code injection",
    "RuleId": "actions/code-injection/medium",
    "Tool": "CodeQL",
    "SecuritySeverity": "medium",
    "Severity": "error",
    "Count": 2,
    "AffectedPaths": [
      ".github/workflows/validate.yml"
    ],
    "HasFilePaths": true,
    "AlertUrl": "https://github.com/microsoft/hve-core/security/code-scanning/17",
    "FindingDescription": "Potential code injection in ${{ inputs.version }}, which may be controlled by an external user."
  },
  {
    "RuleDescription": "Branch-Protection",
    "RuleId": "BranchProtectionID",
    "Tool": "Scorecard",
    "SecuritySeverity": "high",
    "Severity": "error",
    "Count": 1,
    "AffectedPaths": [],
    "HasFilePaths": false,
    "AlertUrl": "https://github.com/microsoft/hve-core/security/code-scanning/1",
    "FindingDescription": "score is 9: branch protection is not maximal on development and all release branches"
  }
]

SecuritySeverity は、セキュリティ分類のないコード品質ルールでは null になります。フォールバックとして、Severity（セキュリティ以外のルールの重大度で、error、warning、note、none のいずれか）が使用できます。AffectedPaths は常に、番兵文字列を除外した、重複のないソート済みファイルパスの JSON 配列です。アラートに関連するソースファイルがない場合（たとえば BranchProtectionID）、HasFilePaths は false、AffectedPaths は [] になります。AlertUrl は、GitHub の Security タブにあるアラートへの直接リンクです。FindingDescription は、最新のアラートメッセージのテキストです。

-IncludeDismissedStillDetected（bash では -d）を指定すると、ブランチ上の最新のインスタンスが fixed ではない却下済みアラートが、オープンアラートのグループの後に別グループとして追加されます。これらのグループには Kind（dismissed-still-detected）と DismissedReason が追加されます。オープンアラートのグループに変更はありません。却下してもアラートは解決されないため、再オープンして修正するアラートとして提示してください。

単一アラートの詳細を取得する

この呼び出しは1件のレコードを返します。一覧表示やグループ化の処理ではなく、上記の gh api の制限にも抵触しません。

gh api repos/{owner}/{repo}/code-scanning/alerts/{alert_number}

影響を受けるファイルパスの一覧表示

-OutputFormat Json を指定し、各ルールグループの AffectedPaths フィールドを読み取ります。JSON 出力には、各グループについて、RuleDescription、RuleId、Tool、SecuritySeverity、Severity、Count、AffectedPaths（重複のないソート済みファイルパス）、HasFilePaths（ブール値。関連するソースファイルがないリポジトリレベルのルールでは false）、AlertUrl（文字列。GitHub の Security タブにあるアラートへの直接リンク）、FindingDescription（文字列。分析ツールから返される最新のアラートメッセージのテキスト）が含まれます。

主なフィールド

これらは GitHub API のレスポンスのフィールドパスであり、出力オブジェクトのプロパティではありません。グループ化された出力オブジェクトのフィールド名は、上記の JSON 出力の形式のセクションに記載されています。

• rule.security_severity_level：セキュリティの重大度レベル。critical、high、medium、low のいずれかです。コード品質ルールでは null です
• rule.severity：セキュリティ以外のルールの重大度。error、warning、note、none のいずれかで、常に値が設定されています
• rule.id：重複排除や相互参照に使用するルール識別子
• tool.name：アラートを生成した分析ツール（たとえば CodeQL）
• most_recent_instance.location.path：最新のアラート発生箇所のソースファイルパス

解決ポリシー

アラートはコードまたは設定で解決してください。誤検知やテストコードの場合も含め、アラートを却下したり、却下を提案したりしないでください。検出結果をすぐに修正できない場合、メンテナーはレビュー済みで有効期限付きの追跡対象例外を追加できます。アラートはオープンのままです。このポリシーを採用するリポジトリでは、コードスキャンアラートのライフサイクルに関するドキュメントにその内容を記載します。hve-core については、https://github.com/microsoft/hve-core/blob/main/docs/security/code-scanning-alert-lifecycle.md を参照してください。

コードスキャン分析

これらの呼び出しで取得するのは分析メタデータであり、アラート一覧ではありません。また、上記の gh api の制限にも抵触しません。

最近の分析を一覧表示する

main ブランチで実行された直近10件の CodeQL 実行を返します。

gh api repos/{owner}/{repo}/code-scanning/analyses \
  -f tool_name=CodeQL \
  -f ref=refs/heads/main \
  -f per_page=10

主なフィールド

• created_at：分析実行のタイムスタンプ
• results_count：生成されたアラートの数
• rules_count：評価されたルールの数
• tool.version：分析ツールのバージョン
• warning / error：分析中に報告された問題

バックログ課題の作成

作成前の重複チェック

新しい課題を作成する前に、タイトルと埋め込みの自動化マーカーを使用して既存の課題を検索します。

existing=$(gh issue list --repo "{owner}/{repo}" \
  --search "\"[Security] {rule_description}\" in:title" \
  --state open --json number --jq '.[0].number // empty')
if [[ -z "$existing" ]]; then
  gh issue create --repo "{owner}/{repo}" \
    --title "[Security] {rule_description}" \
    --label "security" \
    --body "
## Code Scanning Alert: {rule_description}

**Rule:** \`{rule_id}\`
$([ -n "{severity}" ] && echo "**Severity:** {severity}")
**Tool:** {tool}
**Affected files:** {count} occurrences

### Affected paths
{affected_paths}
"
fi

自動化マーカー `` は課題本文に埋め込まれ、重複排除の基準として機能します。すべての {placeholders} を、アラートグループ化 JSON 出力の実際の値に置き換えてください。

トラブルシューティング

症状	考えられる原因	対処方法
gh CLI not found. Install it from https://cli.github.com	gh CLI が PATH にない	https://cli.github.com からインストールし、ターミナルを開き直します
gh CLI is not authenticated. Run 'gh auth login'	gh の認証が完了していない	gh auth login を実行し、security_events スコープが付与されていることを確認します
HTTP 403 Resource not accessible by integration	トークンに security_events スコープがない	再認証します：gh auth refresh -s security_events を実行するか、適切なスコープを持つ GH_TOKEN を設定します
空の結果 []	ref の形式が間違っているか、そのブランチにアラートがない	-f ref= を省略して全ブランチを検索するか、main だけでなく refs/heads/main 形式を使用します
bash: jq: command not found	jq がインストールされていない	brew install jq（macOS）、apt-get install jq（Debian/Ubuntu）、または https://jqlang.github.io/jq/ からインストールします