Scansiona le skill per rilevare eventuali problemi di sicurezza

Il registro degli agenti ti consente di configurare la scansione di sicurezza automatizzata per le skill autonome, applicare le policy di scansione in tutta l'organizzazione utilizzando il servizio policy dell'organizzazione e valutare i risultati di sicurezza in modo da impedire che le skill compromesse raggiungano i tuoi agenti.

Quando carichi una revisione di una skill, Agent Registry esegue la scansione del file di istruzioni SKILL.md, degli script facoltativi e degli asset di supporto per rilevare rischi per la sicurezza come l'esfiltrazione di dati non autorizzata, le credenziali esposte e la prompt injection.

La scansione di sicurezza delle skill utilizza modelli linguistici di grandi dimensioni (LLM) per valutare le istruzioni, la logica del codice e l'intent semantico. Poiché l'analisi LLM è probabilistica, le scansioni potrebbero produrre falsi positivi o falsi negativi e i risultati potrebbero variare tra le esecuzioni. Inoltre, i dettagli sui risultati potrebbero essere approssimativi e soggetti ad allucinazioni. Gli sviluppatori devono esaminare e verificare i risultati della scansione prima di applicare le modifiche di correzione.

Prima di iniziare

  1. Configura Agent Registry.

  2. Per una configurazione con un singolo progetto, recupera l'ID progetto del progetto di governance in cui è abilitato Agent Registry. Se hai configurato un confine di gestione per più progetti, utilizza l'ID del progetto di gestione per il rilevamento e la registrazione a livello di confine oppure specifica l'ID di un progetto membro per le operazioni su un singolo progetto.

  3. Registra una skill autonoma in Agent Registry.

  4. Per utilizzare i comandi di Google Cloud CLI in questo documento, configura l'ambiente gcloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare l'analisi e valutare i risultati in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto di governance in cui è abilitato Agent Registry:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Altri ruoli di Agent Registry potrebbero includere anche le autorizzazioni necessarie per configurare la scansione e visualizzare le skill. Per saperne di più, consulta Ruoli e autorizzazioni di Agent Registry.

Vincoli delle dimensioni del payload non compresso

Per garantire prestazioni ottimali e rispettare i limiti dei token di elaborazione per gli scanner LLM sottostanti, Agent Registry applica limiti rigorosi alle dimensioni non compresse quando l'analisi è attiva:

  • Dimensioni totali della skill non compressa: massimo 10 MB per l'archivio estratto.
  • Dimensioni non compresse per file: massimo 1 MB per ogni singolo file all'interno del pacchetto di skill.

Se una skill ha la scansione abilitata e supera questi limiti, la creazione di una revisione della skill non va a buon fine con un errore INVALID_ARGUMENT o lo stato della scansione della revisione viene risolto in UNSUPPORTED_FORMAT.

Se la scansione è esplicitamente disabilitata, Agent Registry ignora questi limiti di dimensione specifici per la scansione, ma si applicano comunque i limiti generali del sistema. Per saperne di più sui limiti di sistema, consulta Quote e limiti di sistema.

Configura una policy di scansione per una skill

Per impostazione predefinita, le skill utilizzano la policy di scansione Abilitata (blocco) (ENABLED_BLOCKING), che scansiona automaticamente le revisioni delle skill caricate per rilevare rischi per la sicurezza come l'esfiltrazione di dati non autorizzata, le credenziali esposte e il prompt injection. I problemi rilevati vengono esposti come risorse Finding di sola lettura nel tuo progetto di governance: projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Con Abilitato (blocco), il registro degli agenti blocca il download delle revisioni con risultati di sicurezza e impedisce la promozione delle revisioni con risultati o scansioni in attesa come revisione predefinita dello skill.

Puoi anche configurare le policy di scansione per la modalità di controllo non bloccante (ENABLED_NONBLOCKING) o disattivare la scansione (DISABLED). Per saperne di più sulle policy di scansione supportate, consulta Policy di scansione.

Imposta o aggiorna le impostazioni di scansione delle skill

L'attivazione o l'aggiornamento della scansione su una skill esistente si applica solo alle revisioni della skill create dopo la modifica della configurazione. La scansione non viene attivata retroattivamente per le revisioni già create. Per analizzare i contenuti delle skill caricati quando l'analisi era disattivata, devi creare una nuova revisione della skill.

Per configurare le impostazioni di scansione durante la creazione o l'aggiornamento di una skill, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Agent Registry:

    Vai ad Agent Registry

  2. Seleziona la scheda Competenze.

  3. Fai clic su Aggiungi competenza o seleziona una competenza esistente e fai clic su Modifica.

  4. Nella sezione Scansione di sicurezza, seleziona la policy di scansione che preferisci.

  5. Fai clic su Salva o Crea.

gcloud

  • Crea una skill con la scansione abilitata (blocco): esegui il comando gcloud agent-registry skills create con il flag --scanning-policy impostato su enabled-blocking. Ad esempio, se registri una skill utilizzando un file ZIP da un bucket Cloud Storage:

    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"

  • Crea una skill con la scansione abilitata (non bloccante): esegui il comando gcloud agent-registry skills create con il flag --scanning-policy impostato su enabled-nonblocking. Ad esempio, se registri una skill utilizzando un file ZIP da un bucket Cloud Storage:

    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"

  • Aggiorna la policy di scansione su una skill esistente: esegui il comando gcloud agent-registry skills update con il flag --scanning-policy impostato sulla policy selezionata, ad esempio enabled-nonblocking:

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

  • Disattiva l'analisi su una skill: esegui il comando gcloud agent-registry skills update con il flag --scanning-policy impostato su disabled:

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

  • Descrivi la configurazione di scansione su una skill esistente: esegui il comando gcloud agent-registry skills describe con il flag --format impostato su value(scanningConfig.policy):

    gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"

Sostituisci quanto segue:

  • SKILL_ID: l'ID della skill. Quando aggiorni o descrivi una skill esistente registrata manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • BUCKET_NAME: il nome del bucket Cloud Storage che contiene il bundle ZIP. Prima di importare da un bucket, assicurati che l'agente di servizio Agent Registry disponga dell'autorizzazione storage.objects.get sul bucket. Per saperne di più, consulta Registra una skill.
  • SKILL_PACKAGE: il nome del pacchetto di competenze contenente il payload delle competenze.

REST

Per configurare la scansione utilizzando l'API REST, includi l'oggetto scanningConfig nel corpo della richiesta:

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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID della skill. Per le skill registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.

Forza l'analisi utilizzando il servizio policy dell'organizzazione

Puoi applicare policy di analisi a livello di organizzazione definendo un vincolo personalizzato del servizio policy dell'organizzazione sulla risorsa Skill che valuta la policy di analisi, con esenzioni facoltative dei tag di Resource Manager.

Per informazioni sull'applicazione delle policy dell'organizzazione in Agent Registry, sulle funzionalità e sulle limitazioni, consulta Applicazione delle policy dell'organizzazione.

Definisci il vincolo personalizzato

Crea un file YAML denominato skills-scan-constraint.yaml con la seguente specifica:

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.

Sostituisci ORGANIZATION_ID con l'ID organizzazione numerico.

Per richiedere la modalità di blocco per tutte le competenze e impedire l'applicazione delle policy di scansione DISABLED e ENABLED_NONBLOCKING, puoi in alternativa impostare condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" e actionType: ALLOW.

Imposta il vincolo personalizzato

Carica e registra il vincolo personalizzato nella tua organizzazione con il comando gcloud org-policies set-custom-constraint:

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

Applica la policy con esenzioni condizionali

Crea un file di definizione delle policy denominato skills-scan-policy.yaml che applica il vincolo a tutti i progetti standard, escludendo, ad esempio, i progetti di test che hai taggato con 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"

Sostituisci ORGANIZATION_ID con l'ID organizzazione numerico.

Applica la policy alla tua organizzazione con il comando gcloud org-policies set-policy:

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

Verifica policy

Verifica che la policy sia attiva su un progetto con il comando gcloud org-policies describe:

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

Sostituisci PROJECT_ID con l'ID progetto.

Esamina i risultati della scansione e lo stato della revisione

Quando pubblichi una revisione della skill, lo scanner viene eseguito in modo asincrono in background. Per ispezionare i metadati della revisione e verificare il risultato dell'analisi, esegui il comando gcloud agent-registry skills revisions describe:

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

Sostituisci quanto segue:

  • REVISION_ID: l'ID della revisione della skill.
  • SKILL_ID: l'ID del container di skill. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.

L'output contiene il blocco scanResult simile al seguente esempio:

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

I valori possibili per scanResult.scanState sono:

  • SUCCEEDED: l'esecuzione della scansione è stata completata. Se vengono rilevati problemi di sicurezza, i nomi delle risorse vengono elencati nell'array scanResult.findings. Se non vengono rilevati problemi, scanResult.findings è vuoto.
  • RUNNING: l'analisi è in fase di esecuzione.
  • DISABLED: la scansione viene ignorata perché la policy di scansione della skill è impostata su DISABLED al momento della creazione della revisione della skill.
  • UNSUPPORTED_FORMAT: l'archivio caricato non può essere analizzato dallo scanner, ad esempio perché le sue dimensioni non compresse hanno superato i limiti di scansione o il formato dell'archivio non è supportato. I dettagli sono forniti in scanResult.errorMessage.
  • FAILED: l'analisi non può essere completata a causa di un errore interno. I dettagli sono forniti in scanResult.errorMessage.

Lo stato dell'analisi di una revisione riflette la configurazione dell'analisi attiva al momento della creazione della revisione. L'attivazione o l'aggiornamento dell'analisi su una skill si applica solo alle revisioni create dopo la modifica e non attiva retroattivamente un'analisi per le revisioni esistenti. Per analizzare i contenuti delle skill caricati quando l'analisi era disattivata, devi creare una nuova revisione della skill.

Filtra i risultati sulla sicurezza

Quando una scansione rileva problemi di sicurezza, la telemetria dettagliata viene pubblicata in Agent Registry come risorse Finding con ambito limitato al progetto e alla località. La visualizzazione dei risultati richiede il ruolo Amministratore API Agent Registry (roles/agentregistry.admin).

  • Elenca tutti i risultati per una revisione della skill: esegui il comando 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\""

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto
    • LOCATION: la località del registry.
    • SKILL_ID: l'ID del container di competenze, ad esempio private-my-skill.
    • REVISION_ID: l'ID della revisione della skill.

    L'output è simile al seguente:

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

  • Descrivi i dettagli dei risultati: esegui il comando gcloud agent-registry findings describe:

    gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json

    Sostituisci quanto segue:

    • FINDING_ID: l'ID della risorsa Finding.
    • PROJECT_ID: l'ID progetto
    • LOCATION: la località del registry.

    Output di esempio dei risultati:

    {
  "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."
}

    Ogni risorsa Finding include i seguenti campi chiave:

    • resource: il nome completo della risorsa della revisione della skill associata al risultato.
    • severity: il livello di gravità. I valori consentiti sono:
      • SEVERITY_CRITICAL
      • SEVERITY_HIGH
      • SEVERITY_MEDIUM
      • SEVERITY_LOW
      • SEVERITY_UNSPECIFIED
    • findingClass: il tipo di risultato:
      • VULNERABILITY: un punto debole del software o delle istruzioni.
      • SECRET: credenziali, chiavi o token in testo non crittografato esposti.
    • files: l'elenco dei file interessati nell'archivio delle skill, inclusi i relativi path e lineNumber. Un valore pari a 0 indica che il risultato si applica all'intero file.
    • detail: una spiegazione dettagliata del problema di sicurezza rilevato.

Correggi i risultati e aggiorna le competenze

Per risolvere i risultati relativi alla sicurezza di una skill, segui questi passaggi:

  1. Esamina il campo detail del risultato e controlla il file incriminato path e lineNumber nell'array files. Poiché la scansione automatica utilizza LLM per ispezionare il codice semantico e le istruzioni, verifica i numeri di riga e i risultati segnalati prima di modificare i file.
  2. Aggiorna i file di origine nell'ambiente di sviluppo locale per risolvere il risultato. Ad esempio, rimuovi le chiamate di rete non autorizzate, rimuovi le credenziali esposte o elimina i pattern di prompt injection.
  3. Crea un pacchetto dei file aggiornati in un nuovo file ZIP.
  4. Crea una nuova revisione della skill.
  5. Verifica che il valore scanResult.scanState della nuova revisione venga risolto in SUCCEEDED senza risultati elencati.
  6. Aggiorna la revisione predefinita della skill in modo che punti alla revisione verificata.

Passaggi successivi