Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Analiza las habilidades para detectar problemas de seguridad

El Registro de agentes te permite configurar análisis de seguridad automatizados para habilidades independientes, aplicar políticas de análisis en toda tu organización con el servicio de políticas de la organización y clasificar los hallazgos de seguridad para que puedas evitar que las habilidades vulneradas lleguen a tus agentes.

Cuando subes una revisión de habilidad, Agent Registry analiza el archivo de instrucciones SKILL.md, las secuencias de comandos opcionales y los recursos de apoyo en busca de riesgos de seguridad, como el robo de datos no autorizado, las credenciales expuestas y la inyección de instrucciones.

El análisis de seguridad de las habilidades usa modelos de lenguaje grandes (LLM) para evaluar las instrucciones, la lógica del código y la intención semántica. Debido a que el análisis de LLM es probabilístico, los análisis pueden producir falsos positivos o falsos negativos, y los resultados pueden variar entre las ejecuciones. Además, los detalles sobre los hallazgos pueden ser aproximados y estar sujetos a alucinaciones. Los desarrolladores deben revisar y verificar los hallazgos del análisis antes de aplicar los cambios de solución.

Antes de comenzar

Configura el Registro de agentes.
Para una configuración de un solo proyecto, obtén el ID del proyecto del proyecto de administración en el que está habilitado el Registro de agentes. Si configuraste un límite de administración para varios proyectos, usa el ID de tu proyecto de administración para el descubrimiento y el registro en todo el límite, o especifica un ID del proyecto miembro para las operaciones de un solo proyecto.
Registra una habilidad independiente en Agent Registry.
Para usar los comandos de Google Cloud CLI en este documento, configura tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para configurar el análisis y clasificar los hallazgos en el Registro de agentes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto de administración en el que está habilitado el Registro de agentes:

Configurar el análisis de habilidades: Usuario del registro de agentes (roles/agentregistry.user)
Visualizar habilidades y revisiones de habilidades: Visualizador de la API de Agent Registry (roles/agentregistry.viewer)
Visualiza y enumera los hallazgos de seguridad: Administrador de la API de Agent Registry (roles/agentregistry.admin)
Aplica políticas de análisis a nivel de la organización o de la carpeta: Administrador de políticas de la organización (roles/orgpolicy.policyAdmin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otros roles de Agent Registry también pueden incluir los permisos necesarios para configurar el análisis y ver las habilidades. Para obtener más información, consulta Roles y permisos de Agent Registry.

Restricciones de tamaño de carga útil sin comprimir

Para garantizar un rendimiento óptimo y adaptarse a los límites de tokens de procesamiento de los escáneres de LLM subyacentes, el Registro de agentes aplica límites estrictos de tamaño sin comprimir cuando el análisis está activo:

Tamaño total de la habilidad sin comprimir: un máximo de 10 MB para el archivo extraído.
Tamaño sin comprimir por archivo: Un máximo de 1 MB para cualquier archivo individual dentro del paquete de habilidades.

Si una habilidad tiene habilitado el análisis y supera estos límites, la creación de una revisión de habilidad falla con un error INVALID_ARGUMENT o el estado del análisis de la revisión se resuelve como UNSUPPORTED_FORMAT.

Si el análisis se inhabilita de forma explícita, el registro de agentes omite estos límites de tamaño específicos del análisis, pero se siguen aplicando los límites generales del sistema. Para obtener más información sobre los límites del sistema, consulta Cuotas y límites del sistema.

Configura una política de análisis para una habilidad

De forma predeterminada, las habilidades usan la política de análisis Habilitada (bloqueo) (ENABLED_BLOCKING), que analiza automáticamente las revisiones de habilidades subidas en busca de riesgos de seguridad, como robo de datos no autorizado, credenciales expuestas y ataques de inyección de instrucciones. Los problemas detectados se exponen como recursos Finding de solo lectura en tu proyecto de administración: projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Con Habilitado (bloqueo), el Registro de agentes bloquea la descarga de revisiones con hallazgos de seguridad y evita que se promocionen revisiones con hallazgos o análisis pendientes como la revisión predeterminada de la habilidad.

También puedes configurar políticas de análisis para el modo de auditoría sin bloqueo (ENABLED_NONBLOCKING) o inhabilitar el análisis (DISABLED). Para obtener más información sobre las políticas de análisis compatibles, consulta Políticas de análisis.

Establece o actualiza la configuración de análisis de habilidades

Habilitar o actualizar el análisis en una habilidad existente se aplica solo a las revisiones de habilidades creadas después del cambio de configuración. El análisis no se activa de forma retroactiva para las revisiones que ya se crearon. Para analizar el contenido de las habilidades que se subió cuando se inhabilitó el análisis, debes crear una nueva revisión de la habilidad.

Para establecer la configuración de análisis cuando creas o actualizas una habilidad, sigue estos pasos:

Console

En la consola de Google Cloud , ve a la página Registro de agentes:

Ir al registro de agentes
Selecciona la pestaña Habilidades.
Haz clic en Agregar habilidad o selecciona una habilidad existente y haz clic en Editar.
En la sección Análisis de seguridad, selecciona la política de análisis que desees.
Haz clic en Guardar o Crear.

gcloud

Crea una habilidad con el análisis habilitado (bloqueo): Ejecuta el comando gcloud agent-registry skills create con la marca --scanning-policy establecida en enabled-blocking. Por ejemplo, si registras una habilidad con un archivo ZIP de un bucket de Cloud Storage, haz lo siguiente:
```
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 habilidad con el análisis habilitado (sin bloqueo): Ejecuta el comando gcloud agent-registry skills create con la marca --scanning-policy establecida en enabled-nonblocking. Por ejemplo, si registras una habilidad con un archivo ZIP de un bucket de Cloud Storage, haz lo siguiente:
```
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"
```
Actualiza la política de análisis en una habilidad existente: Ejecuta el comando gcloud agent-registry skills update con la marca --scanning-policy establecida en la política seleccionada, por ejemplo, enabled-nonblocking:
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```

Inhabilita el análisis en una habilidad: Ejecuta el comando gcloud agent-registry skills update con la marca --scanning-policy establecida en disabled:

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

Describe la configuración de análisis en una habilidad existente: ejecuta el comando gcloud agent-registry skills describe con la marca --format establecida en value(scanningConfig.policy):
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

Reemplaza lo siguiente:

SKILL_ID: Es el ID de la habilidad. Cuando actualices o describas una habilidad existente registrada de forma manual, incluye el prefijo private-, como private-my-skill.
PROJECT_ID: Es el ID del proyecto.
LOCATION: Es la ubicación del registro.
BUCKET_NAME: Es el nombre del bucket de Cloud Storage que contiene el paquete ZIP. Antes de importar desde un bucket, asegúrate de que el agente de servicio de Agent Registry tenga el permiso storage.objects.get en el bucket. Para obtener más información, consulta Registra una habilidad.
SKILL_PACKAGE: Es el nombre del paquete de habilidades que contiene la carga útil de la habilidad.

REST

Para configurar el análisis con la API de REST, incluye el objeto scanningConfig en el cuerpo de la solicitud:

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"

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto.
LOCATION: Es la ubicación del registro.
SKILL_ID: Es el ID de la habilidad. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.

Aplicar el análisis con el servicio de políticas de la organización

Puedes aplicar políticas de análisis en toda la organización definiendo una restricción personalizada del servicio de políticas de la organización en el recurso Skill que evalúa la política de análisis, con exenciones opcionales de etiquetas de Resource Manager.

Para obtener información sobre la aplicación de políticas de la organización en el Registro de agentes, las capacidades y las limitaciones, consulta Aplicación de políticas de la organización.

Define la restricción personalizada

Crea un archivo YAML llamado skills-scan-constraint.yaml con la siguiente especificación:

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.

Reemplaza ORGANIZATION_ID por el ID numérico de tu organización.

Para exigir el modo de bloqueo en todas las habilidades y evitar las políticas de análisis DISABLED y ENABLED_NONBLOCKING, también puedes establecer condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" y actionType: ALLOW.

Establece la restricción personalizada

Sube y registra la restricción personalizada en tu organización con el comando gcloud org-policies set-custom-constraint:

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

Aplica la política con exenciones condicionales

Crea un archivo de definición de política llamado skills-scan-policy.yaml que aplique la restricción en todos los proyectos estándar y, por ejemplo, exima los proyectos de prueba que etiquetaste 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"

Reemplaza ORGANIZATION_ID por el ID numérico de tu organización.

Aplica la política a tu organización con el comando gcloud org-policies set-policy:

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

Verifica la política

Verifica que la política esté activa en un proyecto con el comando gcloud org-policies describe:

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

Reemplaza PROJECT_ID con el ID del proyecto.

Revisa los resultados del análisis y el estado de la revisión

Cuando publicas una revisión de habilidad, el escáner se ejecuta de forma asíncrona en segundo plano. Para inspeccionar los metadatos de la revisión y verificar el resultado del análisis, ejecuta el comando gcloud agent-registry skills revisions describe:

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

Reemplaza lo siguiente:

REVISION_ID: Es el ID de la revisión de la habilidad.
SKILL_ID: Es el ID del contenedor de habilidades. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
PROJECT_ID: Es el ID del proyecto.
LOCATION: Es la ubicación del registro.

El resultado contiene el bloque scanResult que se ve como en el siguiente ejemplo:

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

Los valores posibles de scanResult.scanState son los siguientes:

SUCCEEDED: Se completó la ejecución del análisis. Si se detectan problemas de seguridad, sus nombres de recursos se enumeran en el array scanResult.findings. Si no se detectan problemas, scanResult.findings estará vacío.
RUNNING: El análisis se está ejecutando de forma activa.
DISABLED: Se omite el análisis porque la política de análisis de la habilidad se establece en DISABLED en el momento en que se crea la revisión de la habilidad.
UNSUPPORTED_FORMAT: El escáner no puede analizar el archivo subido, por ejemplo, porque su tamaño sin comprimir superó los límites de análisis o su formato de archivo no es compatible. Los detalles se proporcionan en scanResult.errorMessage.
FAILED: El análisis no se puede completar debido a un error interno. Los detalles se proporcionan en scanResult.errorMessage.

El estado de análisis de una revisión refleja la configuración de análisis activa en el momento en que se creó la revisión. Habilitar o actualizar el análisis en una habilidad solo se aplica a las revisiones creadas después del cambio y no activa de forma retroactiva un análisis para las revisiones existentes. Para analizar el contenido de las habilidades que se subieron cuando se inhabilitó el análisis, debes crear una nueva revisión de la habilidad.

Clasifica los hallazgos de seguridad

Cuando un análisis detecta problemas de seguridad, se publica telemetría detallada en Agent Registry como recursos Finding con alcance para tu proyecto y ubicación. Para ver los hallazgos, se requiere el rol de administrador de la API de Agent Registry (roles/agentregistry.admin).

Enumera todos los hallazgos de una revisión de habilidad: ejecuta el 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\""

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto.
LOCATION: Es la ubicación del registro.
SKILL_ID: Es el ID del contenedor de habilidades, como private-my-skill.
REVISION_ID: Es el ID de la revisión de la habilidad.

El resultado es similar a lo siguiente:

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

Describe los detalles del hallazgo: ejecuta el comando gcloud agent-registry findings describe:
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
Reemplaza lo siguiente:
- FINDING_ID: Es el ID del recurso Finding.
- PROJECT_ID: Es el ID del proyecto.
- LOCATION: Es la ubicación del registro.
Resultado de muestra del hallazgo:
```
{
  "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."
}
```
Cada recurso Finding incluye los siguientes campos clave:
- resource: Es el nombre de recurso completo de la revisión de la habilidad asociada con el hallazgo.
- severity: Es el nivel de gravedad. Se permiten los siguientes valores:
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass: Es el tipo de hallazgo:
  - VULNERABILITY: una debilidad de software o de instrucciones.
  - SECRET: credenciales, claves o tokens de texto simple expuestos.
- files: Es la lista de archivos afectados en el archivo de la habilidad, incluidos los valores relativos de path y lineNumber. Un valor de 0 indica que el hallazgo se aplica a todo el archivo.
- detail: Es una explicación detallada del problema de seguridad detectado.

Corrige los hallazgos y actualiza las habilidades

Para resolver los hallazgos de seguridad en una habilidad, sigue estos pasos:

Revisa el campo detail del hallazgo y, luego, inspecciona el archivo ofensivo path y lineNumber en el array files. Debido a que el análisis automatizado usa LLM para inspeccionar el código y las instrucciones semánticas, verifica los números de línea y los hallazgos informados antes de modificar tus archivos.
Actualiza los archivos de origen en tu entorno de desarrollo local para resolver el hallazgo. Por ejemplo, quita las llamadas de red no autorizadas, quita las credenciales expuestas o elimina los patrones de inserción de instrucciones.
Empaqueta los archivos actualizados en un nuevo archivo ZIP.
Crea una nueva revisión de habilidad.
Verifica que el scanResult.scanState de la revisión nueva se resuelva en SUCCEEDED sin que se muestren hallazgos.
Actualiza la revisión predeterminada de la habilidad para que apunte a la revisión verificada.

¿Qué sigue?

Obtén más información sobre la arquitectura de habilidades.
Obtén más información para registrar habilidades.
Obtén más información para administrar las revisiones de habilidades.
Revisa las cuotas y los límites del sistema.

Analiza las habilidades para detectar problemas de seguridad Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Roles obligatorios

Restricciones de tamaño de carga útil sin comprimir

Configura una política de análisis para una habilidad

Establece o actualiza la configuración de análisis de habilidades

Console

gcloud

REST

Aplicar el análisis con el servicio de políticas de la organización

Define la restricción personalizada

Establece la restricción personalizada

Aplica la política con exenciones condicionales

Verifica la política

Revisa los resultados del análisis y el estado de la revisión

Clasifica los hallazgos de seguridad

Corrige los hallazgos y actualiza las habilidades

¿Qué sigue?

Analiza las habilidades para detectar problemas de seguridad