Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

掃描技能是否有安全性問題

您可以透過代理程式登錄檔，為獨立技能設定自動安全性掃描、使用組織政策服務在整個組織強制執行掃描政策，以及分類安全性發現項目，防止遭入侵的技能影響代理程式。

上傳技能修訂版本時，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 角色：

設定技能掃描：代理程式註冊資料庫使用者 (roles/agentregistry.user)
查看技能和技能修訂版本：Agent Registry API 檢視者 (roles/agentregistry.viewer)
查看及列出安全性發現項目：Agent Registry API 管理員 (roles/agentregistry.admin)
在組織或資料夾層級強制執行掃描政策：組織政策管理員 (roles/orgpolicy.policyAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

其他代理程式登錄檔角色可能也包含設定掃描和查看技能所需的權限。詳情請參閱「Agent Registry 角色和權限」。

未壓縮酬載大小限制

為確保最佳效能，並配合基礎 LLM 掃描器的處理詞元限制，Agent Registry 會在掃描期間強制執行嚴格的未壓縮大小限制：

未壓縮技能總大小：解壓縮後的封存檔大小上限為 10 MB。
每個檔案的未壓縮大小：技能套件中任何個別檔案的大小上限為 1 MB。

如果技能已啟用掃描功能，且超過這些限制，建立技能修訂版本時會失敗，並顯示 INVALID_ARGUMENT 錯誤，或修訂版本的掃描狀態會解析為 UNSUPPORTED_FORMAT。

如果明確停用掃描功能，代理程式註冊資料庫會略過這些掃描專屬的大小限制，但一般系統限制仍適用。如要進一步瞭解系統限制，請參閱「配額和系統限制」。

設定技能的掃描政策

根據預設，技能會使用「啟用 (封鎖)」(ENABLED_BLOCKING) 掃描政策，自動掃描上傳的技能修訂版本，找出未經授權的資料竊取、憑證外洩和提示詞注入等安全風險。偵測到的問題會以唯讀 Finding 資源的形式，顯示在管理專案中：projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID。

如果設為「Enabled (Blocking)」，Agent Registry 會封鎖下載有安全性發現項目的修訂版本，並禁止將有發現項目或待掃描的修訂版本，升級為技能的預設修訂版本。

您也可以設定非封鎖稽核模式 (ENABLED_NONBLOCKING) 的掃描政策，或停用掃描 (DISABLED)。如要進一步瞭解支援的掃描政策，請參閱「掃描政策」。

設定或更新技能掃描設定

如果啟用或更新現有技能的掃描功能，則「僅」適用於變更設定後建立的技能修訂版本。系統不會對已建立的修訂版本追溯觸發掃描。如要掃描在停用掃描功能時上傳的技能內容，請建立新的技能修訂版本。

如要在建立或更新技能時調整掃描設定，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Agent Registry」頁面：

前往 Agent Registry
選取「技能」分頁標籤。
按一下「Add skill」(新增技能)，或選取現有技能，然後按一下「Edit」(編輯)。
在「Security scanning」(安全性掃描) 部分，選取所需的掃描政策。
按一下「儲存」或「建立」。

gcloud

建立啟用掃描功能的技能 (封鎖)：執行 gcloud agent-registry skills create 指令，並將 --scanning-policy 旗標設為 enabled-blocking。舉例來說，如果您使用 Cloud Storage bucket 中的 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"

建立啟用掃描功能的技能 (非封鎖)：執行 gcloud agent-registry skills create 指令，並將 --scanning-policy 旗標設為 enabled-nonblocking。舉例來說，如果您使用 Cloud Storage bucket 中的 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"

更新現有技能的掃描政策：執行 gcloud agent-registry skills update 指令，並將 --scanning-policy 旗標設為所選政策，例如 enabled-nonblocking：

gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking

停用技能掃描功能：執行 gcloud agent-registry skills update 指令，並將 --scanning-policy 旗標設為 disabled：

gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled

說明現有技能的掃描設定：執行 gcloud agent-registry skills describe 指令，並將 --format 旗標設為 value(scanningConfig.policy)：

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 bucket 名稱。從 bucket 匯入前，請確認 Agent Registry 服務代理具備 bucket 的 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- 前置字元，例如 private-my-skill。
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。

修訂版本的掃描狀態反映了建立修訂版本時有效的掃描設定。啟用或更新技能掃描功能，只會套用至變更後建立的修訂版本，不會溯及既往，觸發掃描現有修訂版本。如要掃描在停用掃描功能時上傳的技能內容，請建立新的技能修訂版本。

分類安全性發現項目

掃描作業偵測到安全性問題時，系統會將詳細的遙測資料發布至 Agent Registry，做為專案和位置範圍內的 Finding 資源。必須具備 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

使用組織政策服務強制執行掃描

定義自訂限制

設定自訂限制

套用政策並設定條件式豁免

驗證政策

查看掃描結果和修訂版本狀態

分類安全性發現項目

修正發現項目並更新技能

後續步驟

掃描技能是否有安全性問題