Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Analyser les skills pour détecter les problèmes de sécurité

Agent Registry vous permet de configurer l'analyse de sécurité automatisée pour les compétences autonomes, d'appliquer des règles d'analyse dans l'ensemble de votre organisation à l'aide du service de règles d'administration et de trier les résultats de sécurité afin d'empêcher les compétences compromises d'atteindre vos agents.

Lorsque vous importez une révision de compétence, Agent Registry analyse le fichier d'instructions SKILL.md, les scripts facultatifs et les éléments associés pour détecter les risques de sécurité tels que l'exfiltration de données non autorisée, les identifiants exposés et l'injection de prompt.

L'analyse de sécurité des compétences utilise des grands modèles de langage (LLM) pour évaluer les instructions, la logique du code et l'intention sémantique. L'analyse LLM étant probabiliste, les analyses peuvent produire des faux positifs ou des faux négatifs, et les résultats peuvent varier d'une exécution à l'autre. De plus, les détails sur les résultats peuvent être approximatifs et sujets à des hallucinations. Les développeurs doivent examiner et vérifier les résultats de l'analyse avant d'appliquer les modifications de correction.

Avant de commencer

Configurer le registre d'agents.
Pour une configuration à projet unique, obtenez l'ID de projet du projet de gouvernance où le registre d'agents est activé. Si vous avez configuré une limite de gestion pour plusieurs projets, utilisez l'ID de votre projet de gestion pour la découverte et l'enregistrement à l'échelle de la limite, ou spécifiez l'ID d'un projet membre pour les opérations sur un seul projet.
Enregistrez une compétence autonome dans Agent Registry.
Pour utiliser les commandes de la Google Cloud CLI dans ce document, configurez votre environnement gcloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer l'analyse et trier les résultats dans Agent Registry, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet de gouvernance où Agent Registry est activé :

Configurer l'analyse des compétences : Utilisateur du registre d'agents (roles/agentregistry.user)
Afficher les compétences et les révisions de compétences : Lecteur de l'API Agent Registry (roles/agentregistry.viewer)
Afficher et lister les résultats de sécurité : Administrateur de l'API Agent Registry (roles/agentregistry.admin)
Appliquer des règles d'analyse au niveau de l'organisation ou du dossier : Administrateur des règles d'administration (roles/orgpolicy.policyAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

D'autres rôles du registre d'agents peuvent également inclure les autorisations requises pour configurer l'analyse et afficher les compétences. Pour en savoir plus, consultez Rôles et autorisations Agent Registry.

Contraintes de taille de la charge utile non compressée

Pour garantir des performances optimales et respecter les limites de jetons de traitement des scanners LLM sous-jacents, Agent Registry applique des limites strictes de taille non compressée lorsque l'analyse est active :

Taille totale de la compétence non compressée : 10 Mo maximum pour l'archive extraite.
Taille non compressée par fichier : 1 Mo maximum pour chaque fichier du package de compétences.

Si l'analyse est activée pour une compétence et que celle-ci dépasse ces limites, la création d'une révision de compétence échoue avec une erreur INVALID_ARGUMENT ou l'état d'analyse de la révision est défini sur UNSUPPORTED_FORMAT.

Si l'analyse est explicitement désactivée, Agent Registry ignore ces limites de taille spécifiques à l'analyse, mais les limites générales du système s'appliquent toujours. Pour en savoir plus sur les limites du système, consultez Quotas et limites du système.

Configurer une règle d'analyse pour une compétence

Par défaut, les compétences utilisent la règle d'analyse Activée (blocage) (ENABLED_BLOCKING), qui analyse automatiquement les révisions de compétences importées pour détecter les risques de sécurité tels que l'exfiltration de données non autorisée, les identifiants exposés et l'injection de prompt. Les problèmes détectés sont exposés en tant que ressources Finding en lecture seule dans votre projet de gouvernance : projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Avec l'option Activé (blocage), le registre d'agents bloque le téléchargement des révisions présentant des résultats de sécurité et empêche la promotion des révisions présentant des résultats ou des analyses en attente en tant que révision par défaut de la compétence.

Vous pouvez également configurer des règles d'analyse pour le mode d'audit non bloquant (ENABLED_NONBLOCKING) ou désactiver l'analyse (DISABLED). Pour en savoir plus sur les règles d'analyse compatibles, consultez Règles d'analyse.

Définir ou modifier les paramètres d'analyse des compétences

L'activation ou la mise à jour de l'analyse sur une compétence existante ne s'applique qu'aux révisions de compétences créées après la modification de la configuration. L'analyse n'est pas déclenchée rétroactivement pour les révisions déjà créées. Pour analyser le contenu des compétences importé lorsque l'analyse était désactivée, vous devez créer une révision de compétence.

Pour configurer les paramètres d'analyse lors de la création ou de la mise à jour d'une compétence, procédez comme suit :

Console

Dans la console Google Cloud , accédez à la page Registre d'agents :

Accéder au registre d'agents
Sélectionnez l'onglet Compétences.
Cliquez sur Ajouter une compétence ou sélectionnez une compétence existante, puis cliquez sur Modifier.
Dans la section Analyse de sécurité, sélectionnez la règle d'analyse de votre choix.
Cliquez sur Enregistrer ou Créer.

gcloud

Créer une compétence avec l'analyse activée (blocage) : exécutez la commande gcloud agent-registry skills create avec l'option --scanning-policy définie sur enabled-blocking. Par exemple, si vous enregistrez une compétence à l'aide d'une archive ZIP d'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"
```
Créer une compétence avec l'analyse activée (non bloquante) : exécutez la commande gcloud agent-registry skills create avec l'option --scanning-policy définie sur enabled-nonblocking. Par exemple, si vous enregistrez une compétence à l'aide d'une archive ZIP d'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"
```
Mettre à jour la règle d'analyse sur une compétence existante : exécutez la commande gcloud agent-registry skills update avec l'option --scanning-policy définie sur la règle sélectionnée, par exemple enabled-nonblocking :
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```

Désactiver l'analyse sur une compétence : exécutez la commande gcloud agent-registry skills update avec l'option --scanning-policy définie sur disabled :

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

Décrire la configuration d'analyse sur une compétence existante : exécutez la commande gcloud agent-registry skills describe avec l'option --format définie sur value(scanningConfig.policy) :
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

Remplacez les éléments suivants :

SKILL_ID : ID de la compétence. Lorsque vous mettez à jour ou décrivez une compétence existante enregistrée manuellement, incluez le préfixe private-, par exemple private-my-skill.
PROJECT_ID : ID du projet.
LOCATION : emplacement du registre.
BUCKET_NAME : nom du bucket Cloud Storage contenant le bundle ZIP. Avant d'importer des données à partir d'un bucket, assurez-vous que l'agent de service Agent Registry dispose de l'autorisation storage.objects.get sur le bucket. Pour en savoir plus, consultez Enregistrer une compétence.
SKILL_PACKAGE : nom du package de compétences contenant la charge utile de la compétence.

REST

Pour configurer l'analyse à l'aide de l'API REST, incluez l'objet scanningConfig dans le corps de votre requête :

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"

Remplacez les éléments suivants :

PROJECT_ID : ID du projet.
LOCATION : emplacement du registre.
SKILL_ID : ID de la compétence. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.

Appliquer l'analyse à l'aide du service de règles d'administration

Vous pouvez appliquer des règles d'analyse à l'échelle de l'organisation en définissant une contrainte de service de règles d'administration personnalisée sur la ressource Skill qui évalue la règle d'analyse, avec des exemptions de tags Resource Manager facultatives.

Pour en savoir plus sur l'application des règles d'administration dans le registre d'agents, les fonctionnalités et les limites, consultez Application des règles d'administration.

Définir la contrainte personnalisée

Créez un fichier YAML nommé skills-scan-constraint.yaml avec la spécification suivante :

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.

Remplacez ORGANIZATION_ID par l'ID numérique de votre organisation.

Pour exiger le mode bloquant pour toutes les compétences et empêcher les règles d'analyse DISABLED et ENABLED_NONBLOCKING, vous pouvez également définir condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" et actionType: ALLOW.

Définir la contrainte personnalisée

Importez et enregistrez la contrainte personnalisée dans votre organisation à l'aide de la commande gcloud org-policies set-custom-constraint :

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

Appliquer la règle avec des exceptions conditionnelles

Créez un fichier de définition de règle nommé skills-scan-policy.yaml qui applique la contrainte à tous les projets standards, tout en exemptant, par exemple, les projets de test que vous avez tagués avec 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"

Remplacez ORGANIZATION_ID par l'ID numérique de votre organisation.

Appliquez la règle à votre organisation à l'aide de la commande gcloud org-policies set-policy :

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

Vérifier la règle

Vérifiez que la règle est active sur un projet à l'aide de la commande gcloud org-policies describe :

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

Remplacez PROJECT_ID par l'ID du projet.

Examiner les résultats de l'analyse et l'état de la révision

Lorsque vous publiez une révision de compétence, l'outil d'analyse s'exécute de manière asynchrone en arrière-plan. Pour inspecter les métadonnées de la révision et vérifier le résultat de l'analyse, exécutez la commande gcloud agent-registry skills revisions describe :

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

Remplacez les éléments suivants :

REVISION_ID : ID de la révision de la compétence.
SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
PROJECT_ID : ID du projet.
LOCATION : emplacement du registre.

Le résultat contient le bloc scanResult, qui ressemble à l'exemple suivant :

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

Les valeurs possibles pour scanResult.scanState sont les suivantes :

SUCCEEDED : l'analyse est terminée. Si des problèmes de sécurité sont détectés, leurs noms de ressources sont listés dans le tableau scanResult.findings. Si aucun problème n'est détecté, scanResult.findings est vide.
RUNNING : l'analyse est en cours d'exécution.
DISABLED : l'analyse est ignorée, car la règle d'analyse de la compétence est définie sur DISABLED au moment de la création de la révision de la compétence.
UNSUPPORTED_FORMAT : l'archive importée ne peut pas être analysée par l'outil d'analyse, par exemple parce que sa taille non compressée dépasse les limites d'analyse ou que son format d'archive n'est pas compatible. Pour en savoir plus, consultez scanResult.errorMessage.
FAILED : l'analyse ne peut pas se terminer en raison d'une erreur interne. Pour en savoir plus, consultez scanResult.errorMessage.

L'état d'analyse d'une révision reflète la configuration d'analyse active au moment de la création de la révision. L'activation ou la mise à jour de l'analyse sur une compétence ne s'applique qu'aux révisions créées après la modification et ne déclenche pas d'analyse rétroactive pour les révisions existantes. Pour analyser les contenus de compétences importés lorsque l'analyse était désactivée, vous devez créer une révision de compétence.

Trier les résultats de sécurité

Lorsqu'une analyse détecte des problèmes de sécurité, des données de télémétrie détaillées sont publiées dans Agent Registry en tant que ressources Finding limitées à votre projet et à votre emplacement. Pour afficher les résultats, vous devez disposer du rôle Administrateur de l'API Agent Registry (roles/agentregistry.admin).

Lister tous les résultats d'une révision de compétence : exécutez la commande 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\""

Remplacez les éléments suivants :

PROJECT_ID : ID du projet.
LOCATION : emplacement du registre.
SKILL_ID : ID du conteneur de compétences, par exemple private-my-skill.
REVISION_ID : ID de la révision de la compétence.

Le résultat ressemble à ce qui suit :

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

Décrire les détails d'un résultat : exécutez la commande gcloud agent-registry findings describe :
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
Remplacez les éléments suivants :
- FINDING_ID : ID de la ressource Finding.
- PROJECT_ID : ID du projet.
- LOCATION : emplacement du registre.
Exemple de sortie de résultat :
```
{
  "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."
}
```
Chaque ressource Finding inclut les champs clés suivants :
- resource : nom complet de la ressource de la révision de compétence associée au résultat.
- severity : niveau de gravité. Valeurs autorisées :
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass : type de résultat :
  - VULNERABILITY : une faiblesse logicielle ou d'instruction.
  - SECRET : identifiants, clés ou jetons en texte brut exposés.
- files : liste des fichiers concernés dans l'archive de la compétence, y compris les path et lineNumber relatifs. La valeur 0 indique que le résultat s'applique à l'ensemble du fichier.
- detail : explication détaillée du problème de sécurité détecté.

Corriger les résultats et mettre à jour les compétences

Pour résoudre les résultats de sécurité d'une compétence, procédez comme suit :

Examinez le champ detail du résultat, puis inspectez le fichier incriminé path et lineNumber dans le tableau files. Étant donné que l'analyse automatisée utilise des LLM pour inspecter le code sémantique et les instructions, vérifiez les numéros de ligne et les résultats signalés avant de modifier vos fichiers.
Mettez à jour vos fichiers sources dans votre environnement de développement local pour résoudre le problème. Par exemple, supprimez les appels réseau non autorisés, supprimez les identifiants exposés ou éliminez les modèles d'injection de prompt.
Regroupez les fichiers mis à jour dans une nouvelle archive ZIP.
Créer une révision de compétence
Vérifiez que le scanResult.scanState de la nouvelle révision renvoie SUCCEEDED sans qu'aucun résultat ne soit listé.
Mettez à jour la révision par défaut de la compétence pour qu'elle pointe vers la révision validée.

Étapes suivantes

Découvrez l'architecture des compétences.
Découvrez comment enregistrer des compétences.
Découvrez comment gérer les révisions de compétences.
Passez en revue les quotas et limites du système.

Analyser les skills pour détecter les problèmes de sécurité Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Rôles requis

Contraintes de taille de la charge utile non compressée

Configurer une règle d'analyse pour une compétence

Définir ou modifier les paramètres d'analyse des compétences

Console

gcloud

REST

Appliquer l'analyse à l'aide du service de règles d'administration

Définir la contrainte personnalisée

Définir la contrainte personnalisée

Appliquer la règle avec des exceptions conditionnelles

Vérifier la règle

Examiner les résultats de l'analyse et l'état de la révision

Trier les résultats de sécurité

Corriger les résultats et mettre à jour les compétences

Étapes suivantes

Analyser les skills pour détecter les problèmes de sécurité