Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

スキルをスキャンしてセキュリティ上の問題がないか確認する

Agent Registry を使用すると、スタンドアロンスキルの自動セキュリティスキャンを構成し、組織ポリシーサービスを使用して組織全体にスキャンポリシーを適用できます。また、セキュリティ検出結果をトリアージして、侵害されたスキルがエージェントに到達しないようにすることもできます。

スキルリビジョンをアップロードすると、Agent Registry は SKILL.md 指示ファイル、オプションのスクリプト、サポートアセットをスキャンして、不正なデータ引き出し、認証情報の漏洩、プロンプトインジェクションなどのセキュリティリスクを検出します。

スキルセキュリティスキャンでは、大規模言語モデル（LLM）を使用して、指示、コードロジック、セマンティックインテントを評価します。LLM 分析は確率論的であるため、スキャンで偽陽性または偽陰性が発生する可能性があり、実行ごとに結果が異なる場合があります。また、検出結果の詳細が不正確で、ハルシネーションが発生する可能性があります。デベロッパーは、修正変更を適用する前に、スキャン結果を確認して検証する必要があります。

始める前に

Agent Registry を設定する。
単一プロジェクトの設定の場合は、Agent Registry が有効になっているガバナンスプロジェクトのプロジェクト ID を取得します。複数のプロジェクトに管理境界を構成した場合は、境界全体の検出と登録に管理プロジェクトの ID を使用するか、単一プロジェクトのオペレーションにメンバープロジェクト ID を指定します。
Agent Registry にスタンドアロンスキルを登録します。
このドキュメントの Google Cloud CLI コマンドを使用するには、gcloud CLI 環境を設定します。

必要なロール

Agent Registry でスキャンとトリアージの検出結果を構成するために必要な権限を取得するには、Agent Registry が有効になっているガバナンスプロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

スキルスキャンを構成する: Agent Registry ユーザー（roles/agentregistry.user）
スキルとスキルリビジョンを表示する: Agent Registry API 閲覧者（roles/agentregistry.viewer）
セキュリティ検出結果を表示して一覧表示する: Agent Registry API 管理者（roles/agentregistry.admin）
組織レベルまたはフォルダレベルでスキャンポリシーを適用する: 組織ポリシー管理者（roles/orgpolicy.policyAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

他の Agent Registry ロールにも、スキャンの構成とスキルの表示に必要な権限が含まれている場合があります。詳細については、Agent Registry のロールと権限をご覧ください。

非圧縮ペイロードサイズの制約

最適なパフォーマンスを確保し、基盤となる LLM スキャナの処理トークン制限に対応するため、Agent Registry では、スキャンが有効な場合に、圧縮されていないサイズに厳格な制限を適用します。

非圧縮スキルの合計サイズ: 抽出されたアーカイブの最大サイズは 10 MB です。
ファイルあたりの非圧縮サイズ: スキルパッケージ内の個々のファイルで最大 1 MB。

スキルでスキャンが有効になっていて、これらの上限を超えると、スキルリビジョンの作成が INVALID_ARGUMENT エラーで失敗するか、リビジョンのスキャンステータスが UNSUPPORTED_FORMAT に解決されます。

スキャンが明示的に無効になっている場合、Agent Registry はこれらのスキャン固有のサイズ制限をバイパスしますが、一般的なシステム制限は引き続き適用されます。システムの上限の詳細については、割り当てとシステムの上限をご覧ください。

スキルのスキャンポリシーを構成する

デフォルトでは、スキルは有効（ブロック）（ENABLED_BLOCKING）スキャンポリシーを使用します。このポリシーは、アップロードされたスキルリビジョンを自動的にスキャンして、不正なデータ漏洩、認証情報の漏洩、プロンプトインジェクションなどのセキュリティリスクを検出します。検出された問題は、ガバナンスプロジェクト projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID で読み取り専用の Finding リソースとして公開されます。

[有効（ブロック）] を選択すると、Agent Registry はセキュリティ検出結果を含むリビジョンのダウンロードをブロックし、検出結果を含むリビジョンやスキャンが保留中のリビジョンをスキルのデフォルトリビジョンとして昇格できないようにします。

非ブロッキング監査モード（ENABLED_NONBLOCKING）のスキャンポリシーを構成したり、スキャンを無効（DISABLED）にしたりすることもできます。サポートされているスキャンポリシーの詳細については、スキャンポリシーをご覧ください。

スキルスキャンの設定を行う、または更新する

既存のスキルでスキャンを有効にするか、更新すると、構成変更後に作成されたスキルリビジョンにのみ適用されます。すでに作成されているリビジョンに対して、スキャンが遡及的にトリガーされることはありません。スキャンが無効になっているときにアップロードされたスキルコンテンツをスキャンするには、新しいスキルリビジョンを作成する必要があります。

スキルを作成または更新するときにスキャン設定を構成する手順は次のとおりです。

コンソール

Google Cloud コンソールで、[Agent Registry] ページに移動します。

[Agent Registry] に移動
[スキル] タブを選択します。
[スキルを追加] をクリックするか、既存のスキルを選択して [編集] をクリックします。
[セキュリティスキャン] セクションで、目的のスキャンポリシーを選択します。
[保存] または [作成] をクリックします。

gcloud

スキャンを有効にしてスキルを作成する（ブロック）: --scanning-policy フラグを enabled-blocking に設定して gcloud agent-registry skills create コマンドを実行します。たとえば、Cloud Storage バケットの ZIP アーカイブを使用してスキルを登録する場合:
```
gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-blocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
```
スキャンを有効にしてスキルを作成する（非ブロッキング）: --scanning-policy フラグを enabled-nonblocking に設定して gcloud agent-registry skills create コマンドを実行します。たとえば、Cloud Storage バケットの ZIP アーカイブを使用してスキルを登録する場合:
```
gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-nonblocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
```
既存のスキルのスキャンポリシーを更新する: --scanning-policy フラグを選択したポリシー（enabled-nonblocking など）に設定して、gcloud agent-registry skills update コマンドを実行します。
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```
スキルのスキャンを無効にする: --scanning-policy フラグを disabled に設定して gcloud agent-registry skills update コマンドを実行します。
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled
```
既存のスキルのスキャン構成を記述する: --format フラグを value(scanningConfig.policy) に設定して gcloud agent-registry skills describe コマンドを実行します。
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

次のように置き換えます。

SKILL_ID: スキルの ID。手動で登録された既存のスキルを更新または記述する場合は、private- 接頭辞（private-my-skill など）を含めます。
PROJECT_ID: プロジェクト ID。
LOCATION: レジストリのロケーション。
BUCKET_NAME: ZIP バンドルを含む Cloud Storage バケット名。バケットからインポートする前に、Agent Registry サービスエージェントにバケットに対する storage.objects.get 権限があることを確認します。詳細については、スキルを登録するをご覧ください。
SKILL_PACKAGE: スキルペイロードを含むスキルパッケージの名前。

REST

REST API を使用してスキャンを構成するには、リクエスト本文に scanningConfig オブジェクトを含めます。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "scanningConfig": {
          "policy": "ENABLED_BLOCKING"
        }
      }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=scanningConfig"

次のように置き換えます。

PROJECT_ID: プロジェクト ID。
LOCATION: レジストリのロケーション。
SKILL_ID: スキルの ID。手動で登録されたスキルの場合は、private- 接頭辞（private-my-skill など）を含めます。

組織ポリシーサービスを使用してスキャンを適用する

スキャンポリシーを評価する Skill リソースにカスタムの組織ポリシーサービス制約を定義することで、組織全体のスキャンポリシーを適用できます。必要に応じて、Resource Manager タグの除外を設定することもできます。

Agent Registry での組織のポリシーの適用、機能、制限事項については、組織のポリシーの適用をご覧ください。

カスタム制約を定義する

次の仕様で skills-scan-constraint.yaml という名前の YAML ファイルを作成します。

name: organizations/ORGANIZATION_ID/customConstraints/custom.skillsScanningEnforcement
resourceTypes:
- agentregistry.googleapis.com/Skill
methodTypes:
- CREATE
- UPDATE
condition: resource.scanningConfig.policy == "DISABLED"
actionType: DENY
displayName: Prevent Disabling Skills Scanning
description: Prevents creating or updating skills with scanning disabled.

ORGANIZATION_ID は、組織 ID に置き換えます。

すべてのスキルでブロックモードを必須にし、DISABLED と ENABLED_NONBLOCKING の両方のスキャンポリシーを防止するには、condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" と actionType: ALLOW を設定します。

カスタム制約を設定する

gcloud org-policies set-custom-constraint コマンドを使用して、組織にカスタム制約をアップロードして登録します。

gcloud org-policies set-custom-constraint skills-scan-constraint.yaml

条件付き除外を含むポリシーを適用する

すべての標準プロジェクトに制約を適用する skills-scan-policy.yaml という名前のポリシー定義ファイルを作成します。たとえば、exempt-scanning-enforcement: true でタグ付けしたテストプロジェクトは除外します。

name: organizations/ORGANIZATION_ID/policies/custom.skillsScanningEnforcement
spec:
  rules:
  # Enforce scanning on all standard projects
  - enforce: true
    condition:
      expression: "!resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Enforce Scanning"
      description: "Enforce scanning on all non-exempt projects"
  # Bypass enforcement for tagged projects
  - enforce: false
    condition:
      expression: "resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Exempt Testing Projects"
      description: "Allow scanning to be disabled for testing projects"

ORGANIZATION_ID は、組織 ID に置き換えます。

gcloud org-policies set-policy コマンドを使用して、ポリシーを組織に適用します。

gcloud org-policies set-policy skills-scan-policy.yaml

ポリシーを確認する

gcloud org-policies describe コマンドを使用して、ポリシーがプロジェクトで有効になっていることを確認します。

gcloud org-policies describe custom.skillsScanningEnforcement \
    --project=PROJECT_ID \
    --effective

PROJECT_ID は、実際のプロジェクト ID に置き換えます。

スキャン結果とリビジョンステータスを確認する

スキルリビジョンを公開すると、スキャナがバックグラウンドで非同期に実行されます。リビジョンのメタデータを検査してスキャンの結果を確認するには、gcloud agent-registry skills revisions describe コマンドを実行します。

gcloud agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

次のように置き換えます。

REVISION_ID: スキルリビジョンの ID。
SKILL_ID: スキルコンテナの ID。手動で登録されたスキルの場合は、private-my-skill などの private- 接頭辞を含めます。
PROJECT_ID: プロジェクト ID。
LOCATION: レジストリのロケーション。

出力には、次の例のような scanResult ブロックが含まれます。

name: projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1
createTime: '2026-08-10T09:15:00.000000Z'
state: ACTIVE
scanResult:
  scanState: SUCCEEDED
  scanTime: '2026-08-10T09:16:22.000000Z'
  findings:
  - projects/my-project/locations/us-central1/findings/b9a8c7d6-e5f4-4321-89ab-cdef01234567

scanResult.scanState に指定できる値は次のとおりです。

SUCCEEDED: スキャンの実行が完了しました。セキュリティの問題が検出されると、そのリソース名が scanResult.findings 配列にリストされます。問題が検出されない場合、scanResult.findings は空になります。
RUNNING: スキャンが実行中です。
DISABLED: スキルリビジョンの作成時にスキルのスキャンポリシーが DISABLED に設定されているため、スキャンはバイパスされます。
UNSUPPORTED_FORMAT: アップロードされたアーカイブをスキャナで分析できません。たとえば、圧縮されていないサイズがスキャンの上限を超えているか、アーカイブ形式がサポートされていません。詳しくは、scanResult.errorMessage をご覧ください。
FAILED: 内部エラーのため、スキャンを完了できません。詳細については、scanResult.errorMessage をご覧ください。

リビジョンのスキャンステータスには、リビジョンの作成時に有効だったスキャン構成が反映されます。スキルでスキャンを有効にするか更新すると、変更後に作成されたリビジョンにのみ適用され、既存のリビジョンのスキャンは遡及的にトリガーされません。スキャンが無効になっているときにアップロードされたスキルコンテンツをスキャンするには、新しいスキルリビジョンを作成する必要があります。

セキュリティの検出結果をトリアージする

スキャンでセキュリティの問題が検出されると、プロジェクトとロケーションをスコープとする Finding リソースとして、詳細なテレメトリーが Agent Registry に公開されます。検出結果を表示するには、Agent Registry API 管理者（roles/agentregistry.admin）ロールが必要です。

スキルリビジョンのすべての検出結果を一覧表示する: gcloud agent-registry findings list コマンドを実行します。

gcloud agent-registry findings list \
    --project=PROJECT_ID \
    --location=LOCATION \
    --filter="resource=\"projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID\""

次のように置き換えます。

PROJECT_ID: プロジェクト ID。
LOCATION: レジストリのロケーション。
SKILL_ID: スキルコンテナの ID（private-my-skill など）。
REVISION_ID: スキルリビジョンの ID。

出力は次のようになります。

NAME                                                                                  SEVERITY           FINDING_CLASS  CREATE_TIME
projects/my-project/locations/us-central1/findings/FINDING_ID  SEVERITY_CRITICAL  VULNERABILITY  2026-08-10T09:16:22.104Z

検出結果の詳細を記述する: gcloud agent-registry findings describe コマンドを実行します。
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
次のように置き換えます。
- FINDING_ID: Finding リソースの ID。
- PROJECT_ID: プロジェクト ID。
- LOCATION: レジストリのロケーション。
検出結果の出力例:
```
{
  "name": "projects/my-project/locations/us-central1/findings/FINDING_ID",
  "uid": "FINDING_ID",
  "createTime": "2026-08-10T09:16:22.104Z",
  "updateTime": "2026-08-10T09:16:22.104Z",
  "resource": "projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1",
  "severity": "SEVERITY_CRITICAL",
  "findingClass": "VULNERABILITY",
  "files": [
    {
      "path": "resources/helper.py",
      "lineNumber": "12"
    }
  ],
  "detail": "Involves unauthorized outbound network requests transmitting sensitive local files or environment variables. Detected inside resources/helper.py at line 12."
}
```
各 Finding リソースには、次の主なフィールドが含まれています。
- resource: 検出結果に関連付けられたスキルリビジョンの完全なリソース名。
- severity: 重大度レベル。指定できる値は次のとおりです。
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass: 検出結果のタイプ。
  - VULNERABILITY: ソフトウェアまたは命令の脆弱性。
  - SECRET: プレーンテキストの認証情報、鍵、トークンが公開されている。
- files: スキルアーカイブ内の影響を受けるファイルのリスト。相対的な path と lineNumber が含まれます。値 0 は、検出結果がファイル全体に適用されることを示します。
- detail: 検出されたセキュリティ問題の詳細な説明。

検出結果を修正してスキルを更新する

スキルのセキュリティ検出結果を解決する手順は次のとおりです。

検出結果の detail フィールドを確認し、files 配列内の問題のあるファイル path と lineNumber を調べます。自動スキャンでは、LLM を使用してセマンティックコードと命令を検査するため、ファイルを変更する前に、報告された行番号と検出結果を確認してください。
ローカル開発環境のソースファイルを更新して、検出結果を解決します。たとえば、不正なネットワーク呼び出しの削除、公開された認証情報の削除、プロンプトインジェクションパターンの排除などです。
更新したファイルを新しい ZIP アーカイブにパッケージ化します。
新しいスキルリビジョンを作成する。
新しいリビジョンの scanResult.scanState が SUCCEEDED に解決され、検出結果が一覧表示されないことを確認します。
スキルのデフォルトのリビジョンを更新して、検証済みのリビジョンを指すようにします。

次のステップ

スキルアーキテクチャについて学習する。
スキルを登録する方法を確認する。
スキルリビジョンを管理する方法を確認する。
割り当てとシステムの上限を確認する。

スキルをスキャンしてセキュリティ上の問題がないか確認する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

非圧縮ペイロード サイズの制約

スキルのスキャン ポリシーを構成する

スキル スキャンの設定を行う、または更新する

コンソール

gcloud

REST

組織ポリシー サービスを使用してスキャンを適用する

カスタム制約を定義する

カスタム制約を設定する

条件付き除外を含むポリシーを適用する

ポリシーを確認する

スキャン結果とリビジョン ステータスを確認する

セキュリティの検出結果をトリアージする

検出結果を修正してスキルを更新する

次のステップ

スキルをスキャンしてセキュリティ上の問題がないか確認する

非圧縮ペイロードサイズの制約

スキルのスキャンポリシーを構成する

スキルスキャンの設定を行う、または更新する

組織ポリシーサービスを使用してスキャンを適用する

スキャン結果とリビジョンステータスを確認する