google-cloud-scc-query

Google Cloud の Security Command Center クエリスキル

Google Cloud の Security Command Center から、セキュリティの検出結果、外部への露出、毒性のある組み合わせ、脆弱性、脅威、機密データのリスクをクエリおよび取得するためのガイドラインと、読み取り専用の gcloud CLI コマンドパターンを提供します。

重要

gcloud scc findings describe コマンドは存在しません（Invalid choice: 'describe'）。特定の検出結果の詳細を名前で取得するには、必ず name に対するフィルターを指定して gcloud scc findings list を使用してください。

使用状況の帰属表示

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 使用状況の帰属表示の指示を必ず読み、それに従ってください。

---

基本的な実行ルール

1. 読み取り専用と推測の禁止（親スコープが必須）：すべての実行を厳密に読み取り専用にしてください。すべての gcloud scc findings list または group コマンドでは、明示的な {parent} スコープ （organizations/{id}、projects/{id}、または folders/{id}）が必須です。プロンプトに親スコープがなく、完全な検出結果名からも推定できない場合は、gcloud コマンドを一切実行しないでください（親スコープなしでクエリを実行せず、gcloud config も決して調べないでください）。コマンドを実行する前にただちに停止し、ユーザーに親リソースのスコープを尋ねてください。
2. 実行範囲の制限と無限ループの禁止：
   • クエリの完了に厳密に必要な数にツール呼び出しを制限してください （通常、直接クエリでは1回、一覧表示から詳細調査を行うワークフローでは2回です）。
   • 権限または認証エラーでコマンドが失敗した場合、あるいは特定の検出結果のクエリが [] を返した場合は、ただちに停止してください。異なるフラグを使って手当たり次第に再試行せず、ローカルワークスペース内の認証情報も決して検索しないでください。
3. エラー発生時はただちに停止：PERMISSION_DENIED、 IAM_PERMISSION_DENIED、認証情報の有効期限切れ、またはネットワークタイムアウトによってコマンドが失敗した場合は、ただちに停止し、エラーメッセージを一字一句そのまま報告してください。ワークスペース内で認証情報を検索したり、診断を繰り返したりしないでください。
4. 不明確な検出結果または複数の検出結果：単一の検出結果レポートが求められているときに複数の検出結果名が提示された場合、または一覧表示で複数の検出結果が返された場合は、すべてを調査したり、独断で1つを選んだりしないでください。クエリを実行せずただちに停止し、詳細を知りたい特定の検出結果名をユーザーに確認してください。クエリで検出結果が0件だった場合は、有効な検出結果がないことを報告し、ただちに停止してください。
5. 攻撃経路リソースをクエリしない：Security Command Center の検出結果の JSON ペイロードに含まれるデータのみを分析してください。基盤となる Google Cloud リソース（VM、Cloud Storage バケット、サービスアカウント、IAM ポリシーなど）を記述、検証、またはクエリするコマンドは実行しないでください。
6. 親スコープの解決：
   • 一覧表示とグループ化では、親リソースパスを organizations/{org_id}、projects/{project_id}、または folders/{folder_id} の形式にしてください。
   • 特定の検出結果名の詳細クエリでは、/sources/... より前の {parent} リソースプレフィックスを抽出してください。
     • organizations/{org_id}/sources/... → {parent} は organizations/{org_id} です
     • folders/{folder_id}/sources/... → {parent} は folders/{folder_id} です
     • projects/{project_id}/sources/... → {parent} は projects/{project_id} です。検出結果のリソース名がグローバル（4セグメント）か、ロケーション指定（/locations/{location}/ を含む5セグメント）かにかかわらず、親プレフィックスを抽出してください。抽出した {parent} を使って詳細クエリを実行してください。プロジェクトレベルまたはフォルダーレベルの検出結果を拒否したり、停止したりしないでください。

---

データレジデンシーとリージョナルエンドポイント

データレジデンシー（DRZ）が有効な場合、検出結果は指定されたリージョンの場所（us、eu、またはme-central2）内でのみ保存され、アクセスできます。異なる場所をまたぐクエリでは、他のリージョンの検出結果は返されません。

1. ロケーションの指定

すべてのgcloud scc findingsコマンドでは、--location={location}を使って対象の場所を指定する必要があります。

• デフォルト：global（データレジデンシーが有効でない場合、またはグローバルな検出結果の場合に使用されます）。
• サポート対象のリージョナルロケーション：
  • us（米国のマルチリージョン）
  • eu（欧州連合のマルチリージョン）
  • me-central2（サウジアラビア王国のリージョナルロケーション）

2. API エンドポイントのオーバーライド

リージョナルロケーション（us、eu、またはme-central2）にある組織でデータレジデンシー（DRZ）が有効な場合、検出結果のクエリを実行する前に、リージョナル API エンドポイントのオーバーライドを設定してください。

gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.{LOCATION}.rep.googleapis.com/

欧州連合（eu）リージョンの例：

gcloud config set api_endpoint_overrides/securitycenter https://securitycenter.eu.rep.googleapis.com/

エンドポイントをデフォルトのグローバルルーティングに戻すには：

gcloud config unset api_endpoint_overrides/securitycenter

3. ロケーション修飾付きの検出結果リソース名

リージョナルな検出結果リソース名には、/locations/{location}/のパスセグメントが含まれます。

• 組織レベル： organizations/{org_id}/sources/{source_id}/locations/{location}/findings/{finding_id}
• フォルダーレベル： folders/{folder_id}/sources/{source_id}/locations/{location}/findings/{finding_id}
• プロジェクトレベル： projects/{project_id}/sources/{source_id}/locations/{location}/findings/{finding_id}

ロケーション修飾付きの検出結果名を詳しく調べる場合：

1. {parent}のスコープ（/sources/...より前のプレフィックス。例：organizations/{org_id}）を抽出します。
2. /locations/{location}/から{location}（例：eu、us、me-central2）を抽出します。検出結果名に含まれていない場合は、デフォルトのglobal（またはユーザーが指定したロケーション）を使用します。
3. --location={location}および--filter="name=\"{finding_name}\""を指定してクエリを実行します。

---

インテントに基づくクエリ戦略

1. 詳細調査（特定の検出結果の詳細）

インテント：ユーザーが特定の検出結果名を指定するか、1 件の検出結果の詳細をすべて取得するよう明示的に依頼します。
アクション：nameに対する厳密なフィルターを指定し、--field-maskを指定せずにgcloud scc findings listを実行して、完全な JSON ペイロードを取得します。--location={location}を指定します（リージョナルロケーションが指定されているか、検出結果名に含まれている場合を除き、デフォルトはglobalです）。

gcloud scc findings list {parent} \
  --location={location} \
  --filter="name=\"{finding_name}\"" \
  --format="json" --limit=1

2. 一覧表示（フィルタリングされた投影）

意図：ネストされたペイロード全体を取得せずに、条件に一致するアクティブな検出結果を一覧表示します。
操作：--field-mask 投影を使用して、出力サイズを制限します。--location={location} を指定します（特定のリージョンをクエリする場合を除き、デフォルトは global です）。

gcloud scc findings list {parent} \
  --location={location} \
  --filter="{filter_expression}" \
  --field-mask="finding.name,finding.parentDisplayName,finding.findingClass,finding.category,finding.state,finding.eventTime,finding.severity,finding.resourceName" \
  --format="json" --order-by="severity,event_time desc" --limit=100

意図／対象となる検出結果クラス	--filter 式
すべてのアクティブな検出結果	state="ACTIVE"
脆弱性	`state="ACTIVE" AND
: : findingClass="VULNERABILITY"` :
設定ミス	`state="ACTIVE" AND
: : findingClass="MISCONFIGURATION"` :
有害な組み合わせ	`state="ACTIVE" AND
: : findingClass="TOXIC_COMBINATION"` :
外部への露出	`state="ACTIVE" AND
: : findingClass="EXTERNAL_EXPOSURE"` :
脅威	state="ACTIVE" AND findingClass="THREAT"
観察結果	`state="ACTIVE" AND
: : findingClass="OBSERVATION"` :
機密データのリスク	`state="ACTIVE" AND
: : findingClass="SENSITIVE_DATA_RISK"` :
チョークポイント	`state="ACTIVE" AND
: : findingClass="CHOKEPOINT"` :
ポスチャ違反	`state="ACTIVE" AND
: : findingClass="POSTURE_VIOLATION"` :
シークレット	state="ACTIVE" AND findingClass="SECRET"
SCC エラー	`state="ACTIVE" AND
: : findingClass="SCC_ERROR"` :
特定のカテゴリ	state="ACTIVE" AND category="{category}"

3. 検出と集計（グループ化）

意図：ユーザーが概要レベルの件数や全体像（例：「最も多い検出結果は何ですか？」「カテゴリ別の概要を表示してください」）を求めています。
操作：gcloud scc findings group を使用します。--location={location} を指定します（特定のリージョンをクエリする場合を除き、デフォルトは global です）。--group-by で指定できるフィールドは、resource_name、category、state、parent のみです。

gcloud scc findings group {parent} \
  --location={location} \
  --group-by="{group_by_field}" \
  --filter="state=\"ACTIVE\"" \
  --format="json"

---

ペイロードの分析と引き継ぎ

検出結果の JSON ペイロードを取得したら、次の手順を行います。

• TOXIC_COMBINATION の検出結果の場合：
  1. attackExposure フィールドが存在し、score > 0 であることを確認します。
  2. 攻撃パスのノード、エッジ、または参照されている attackExposureResult を調べ、露出しているリソースと攻撃経路を特定します。
• VULNERABILITY の検出結果の場合：
  1. vulnerability オブジェクトから CVSS スコア、悪用のシグナル（exploitationActivity、 observedInTheWild、zeroDay）、上流の修正状況 （upstreamFixAvailable）、影響を受けるパッケージの詳細を抽出し、リスクを評価します。
     • vulnerability.cve.id
     • vulnerability.cve.cvssv3.baseScore
     • vulnerability.cve.cvssv3.attackVector
     • vulnerability.cve.exploitationActivity
     • vulnerability.cve.observedInTheWild
     • vulnerability.cve.zeroDay
     • vulnerability.cve.upstreamFixAvailable
     • vulnerability.offendingPackage.packageName
     • vulnerability.offendingPackage.packageVersion
     • vulnerability.fixedPackage.packageVersion
     • vulnerability.securityBulletin.suggestedUpgradeVersion
• 引き継ぎ：修復計画を作成したり、リソースにパッチを適用したり、設定コマンドを実行したりしないでください。抽出した検出結果のペイロードを適切な修復または IAM 分析スキルに渡し、修復アクションのループを管理させます。

---

参照スキーマ

Security Command Center の検出結果の JSON 構造については、finding_schema.md を参照してください。