O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Verificar se há problemas de segurança nas habilidades

O Agent Registry permite configurar a verificação de segurança automatizada para habilidades independentes, aplicar políticas de verificação em toda a organização usando o Serviço de Políticas da Organização e fazer a triagem de descobertas de segurança para evitar que habilidades comprometidas cheguem aos agentes.

Quando você faz upload de uma revisão de habilidade, o Registro de Agentes verifica o arquivo de instruções SKILL.md, os scripts opcionais e os recursos de suporte em busca de riscos de segurança, como exfiltração de dados não autorizada, credenciais expostas e injeção de comandos.

A verificação de segurança de habilidades usa modelos de linguagem grandes (LLMs) para avaliar instruções, lógica de código e intenção semântica. Como a análise de LLM é probabilística, as verificações podem produzir falsos positivos ou falsos negativos, e os resultados podem variar entre as execuções. Além disso, os detalhes sobre as descobertas podem ser aproximados e sujeitos a alucinações. Os desenvolvedores precisam analisar e verificar as descobertas da verificação antes de aplicar as mudanças de correção.

Antes de começar

Configure o Agent Registry.
Para uma configuração de projeto único, use o ID do projeto da governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações de projeto único.
Registre uma habilidade independente no Agent Registry.
Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para configurar as descobertas de verificação e triagem no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto de governança em que o Agent Registry está ativado:

Configurar a verificação de habilidades: Usuário do registro de agentes (roles/agentregistry.user)
Ver habilidades e revisões de habilidades: Leitor da API Agent Registry (roles/agentregistry.viewer)
Visualizar e listar descobertas de segurança: Administrador da API Agent Registry (roles/agentregistry.admin)
Aplicar políticas de verificação no nível da organização ou da pasta: Administrador de políticas da organização (roles/orgpolicy.policyAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Outros papéis do Agent Registry também podem incluir as permissões necessárias para configurar a verificação e visualizar habilidades. Para mais informações, consulte Papéis e permissões do Agent Registry.

Restrições de tamanho de payload descompactado

Para garantir o desempenho ideal e acomodar os limites de tokens de processamento para scanners de LLM, o Registro de Agentes aplica limites rígidos de tamanho não compactado quando a verificação está ativa:

Tamanho total da habilidade descompactada: máximo de 10 MB para o arquivo extraído.
Tamanho descompactado por arquivo: máximo de 1 MB para qualquer arquivo individual no pacote de habilidades.

Se uma habilidade tiver a verificação ativada e exceder esses limites, a criação de uma revisão de habilidade vai falhar com um erro INVALID_ARGUMENT ou o status de verificação da revisão será resolvido como UNSUPPORTED_FORMAT.

Se a verificação estiver explicitamente desativada, o Agent Registry vai ignorar esses limites de tamanho específicos da verificação, mas os limites gerais do sistema ainda serão aplicados. Para mais informações sobre limites do sistema, consulte Cotas e limites do sistema.

Configurar uma política de verificação para uma habilidade

Por padrão, as habilidades usam a política de verificação Ativada (bloqueio) (ENABLED_BLOCKING), que verifica automaticamente as revisões de habilidades enviadas em busca de riscos de segurança, como exfiltração de dados não autorizada, credenciais expostas e injeção de comandos. Os problemas detectados são expostos como recursos Finding somente leitura no seu projeto de governança: projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Com a opção Ativado (bloqueio), o Agent Registry bloqueia o download de revisões com descobertas de segurança e impede a promoção de revisões com descobertas ou verificações pendentes como a revisão padrão da habilidade.

Também é possível configurar políticas de verificação para o modo de auditoria sem bloqueio (ENABLED_NONBLOCKING) ou desativar a verificação (DISABLED). Para mais informações sobre as políticas de verificação compatíveis, consulte Políticas de verificação.

Definir ou atualizar as configurações de verificação de habilidades

Ativar ou atualizar a verificação em uma habilidade atual se aplica somente às revisões de habilidade criadas após a mudança de configuração. A verificação não é acionada retroativamente para revisões que já foram criadas. Para verificar o conteúdo de habilidades enviado quando a verificação estava desativada, é preciso criar uma nova revisão de habilidade.

Para definir as configurações de verificação ao criar ou atualizar uma habilidade, siga estas etapas:

Console

No console do Google Cloud , acesse a página Registro de agentes:

Acessar o Agent Registry
Selecione a guia Habilidades.
Clique em Adicionar habilidade ou selecione uma habilidade e clique em Editar.
Na seção Verificação de segurança, selecione a política de verificação que você quer.
Clique em Salvar ou Criar.

gcloud

Criar uma habilidade com a verificação ativada (bloqueio): execute o comando gcloud agent-registry skills create com a flag --scanning-policy definida como enabled-blocking. Por exemplo, se você registrar uma habilidade usando um arquivo ZIP de um bucket do 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"
```
Criar uma habilidade com a verificação ativada (sem bloqueio): execute o comando gcloud agent-registry skills create com a flag --scanning-policy definida como enabled-nonblocking. Por exemplo, se você registrar uma habilidade usando um arquivo ZIP de um bucket do 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"
```
Atualizar a política de verificação em uma habilidade: execute o comando gcloud agent-registry skills update com a flag --scanning-policy definida como a política selecionada, por exemplo, enabled-nonblocking:
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```

Desativar a verificação em uma habilidade: execute o comando gcloud agent-registry skills update com a flag --scanning-policy definida como disabled:

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

Descrever a configuração de verificação em uma habilidade atual: execute o comando gcloud agent-registry skills describe com a flag --format definida como value(scanningConfig.policy):
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

Substitua:

SKILL_ID: o ID da habilidade. Ao atualizar ou descrever uma habilidade registrada manualmente, inclua o prefixo private-, como private-my-skill.
PROJECT_ID: o ID do projeto;
LOCATION: o local do registro.
BUCKET_NAME: o nome do bucket do Cloud Storage que contém o pacote ZIP. Antes de importar de um bucket, verifique se o agente de serviço do Agent Registry tem a permissão storage.objects.get no bucket. Para mais informações, consulte Registrar uma habilidade.
SKILL_PACKAGE: o nome do pacote de habilidades que contém o payload de habilidades.

REST

Para configurar a verificação usando a API REST, inclua o objeto scanningConfig no corpo da solicitação:

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"

Substitua:

PROJECT_ID: o ID do projeto;
LOCATION: o local do registro.
SKILL_ID: o ID da habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.

Aplicar a verificação usando o Serviço de Política da Organização

É possível aplicar políticas de verificação em toda a organização definindo uma restrição personalizada do Serviço de Políticas da Organização no recurso Skill que avalia a política de verificação, com isenções opcionais de tags do Resource Manager.

Para informações sobre a aplicação da política da organização no Agent Registry, recursos e limitações, consulte Aplicação da política da organização.

Definir a restrição personalizada

Crie um arquivo YAML chamado skills-scan-constraint.yaml com a seguinte especificação:

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.

Substitua ORGANIZATION_ID pelo ID numérico da organização.

Para exigir o modo de bloqueio em todas as habilidades e impedir as políticas de verificação DISABLED e ENABLED_NONBLOCKING, defina condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" e actionType: ALLOW.

Defina a restrição personalizada.

Faça upload e registre a restrição personalizada na sua organização com o comando gcloud org-policies set-custom-constraint:

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

Aplicar a política com isenções condicionais

Crie um arquivo de definição de política chamado skills-scan-policy.yaml que aplique a restrição em todos os projetos padrão e, por exemplo, isente os projetos de teste que você marcou com 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"

Substitua ORGANIZATION_ID pelo ID numérico da organização.

Aplique a política à sua organização com o comando gcloud org-policies set-policy:

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

Verificar política

Verifique se a política está ativa em um projeto com o comando gcloud org-policies describe:

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

Substitua PROJECT_ID pelo ID do projeto.

Analisar os resultados da verificação e o status da revisão

Quando você publica uma revisão de habilidade, o scanner é executado de forma assíncrona em segundo plano. Para inspecionar os metadados da revisão e verificar o resultado da verificação, execute o comando gcloud agent-registry skills revisions describe:

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

Substitua:

REVISION_ID: o ID da revisão da habilidade.
SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
PROJECT_ID: o ID do projeto;
LOCATION: o local do registro.

A saída contém o bloco scanResult, que é semelhante ao seguinte exemplo:

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

Os valores possíveis para scanResult.scanState são:

SUCCEEDED: a verificação foi concluída. Se problemas de segurança forem detectados, os nomes dos recursos serão listados na matriz scanResult.findings. Se nenhum problema for detectado, scanResult.findings ficará vazio.
RUNNING: a verificação está em execução.
DISABLED: a verificação é ignorada porque a política de verificação da habilidade está definida como DISABLED no momento em que a revisão da habilidade é criada.
UNSUPPORTED_FORMAT: o arquivo enviado não pode ser analisado pelo verificador, por exemplo, porque o tamanho descompactado excedeu os limites de verificação ou o formato do arquivo não é compatível. Confira mais detalhes em scanResult.errorMessage.
FAILED: não é possível concluir a verificação devido a um erro interno. Os detalhes estão em scanResult.errorMessage.

O status de verificação de uma revisão reflete a configuração de verificação ativa no momento em que a revisão foi criada. Ativar ou atualizar a verificação em uma habilidade se aplica apenas às revisões criadas após a mudança e não aciona retroativamente uma verificação para as revisões atuais. Para verificar o conteúdo de habilidades enviado por upload quando a verificação estava desativada, é preciso criar uma nova revisão de habilidade.

Fazer a triagem de descobertas de segurança

Quando uma verificação detecta problemas de segurança, uma telemetria detalhada é publicada no Agent Registry como recursos Finding com escopo definido para seu projeto e local. Para visualizar as descobertas, é necessário ter o papel de administrador da API Agent Registry (roles/agentregistry.admin).

Listar todas as descobertas de uma revisão de habilidade: execute o 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\""

Substitua:

PROJECT_ID: o ID do projeto;
LOCATION: o local do registro.
SKILL_ID: o ID do contêiner de habilidade, como private-my-skill.
REVISION_ID: o ID da revisão da habilidade.

O resultado será o seguinte:

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

Descrever detalhes da descoberta: execute o comando gcloud agent-registry findings describe:
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
Substitua:
- FINDING_ID: o ID do recurso Finding.
- PROJECT_ID: o ID do projeto;
- LOCATION: o local do registro.
Exemplo de saída de descoberta:
```
{
  "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 inclui os seguintes campos principais:
- resource: o nome do recurso completo da revisão de habilidade associada à descoberta.
- severity: o nível de gravidade. Os valores permitidos são:
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass: o tipo de descoberta:
  - VULNERABILITY: uma falha de software ou instrução.
  - SECRET: credenciais, chaves ou tokens de texto simples expostos.
- files: a lista de arquivos afetados no arquivo de skill, incluindo os path e lineNumber relativos. Um valor de 0 indica que a descoberta se aplica ao arquivo inteiro.
- detail: uma explicação detalhada do problema de segurança detectado.

Corrigir descobertas e atualizar habilidades

Para resolver as descobertas de segurança em uma habilidade, siga estas etapas:

Revise o campo detail da descoberta e inspecione o arquivo ofensivo path e lineNumber na matriz files. Como a verificação automática usa LLMs para inspecionar código e instruções semânticas, verifique os números de linha e as descobertas relatadas antes de modificar os arquivos.
Atualize os arquivos de origem no ambiente de desenvolvimento local para resolver a descoberta. Por exemplo, remova chamadas de rede não autorizadas, remova credenciais expostas ou elimine padrões de injeção de comandos.
Empacote os arquivos atualizados em um novo arquivo ZIP.
Criar uma revisão de habilidade.
Verifique se o scanResult.scanState da nova revisão é resolvido como SUCCEEDED sem descobertas listadas.
Atualize a revisão padrão da habilidade para apontar para a revisão verificada.

A seguir

Aprenda mais sobre a arquitetura de habilidades.
Saiba como registrar habilidades.
Saiba como gerenciar revisões de habilidades.
Analise as cotas e os limites do sistema.

Verificar se há problemas de segurança nas habilidades Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Restrições de tamanho de payload descompactado

Configurar uma política de verificação para uma habilidade

Definir ou atualizar as configurações de verificação de habilidades

Console

gcloud

REST

Aplicar a verificação usando o Serviço de Política da Organização

Definir a restrição personalizada

Defina a restrição personalizada.

Aplicar a política com isenções condicionais

Verificar política

Analisar os resultados da verificação e o status da revisão

Fazer a triagem de descobertas de segurança

Corrigir descobertas e atualizar habilidades

A seguir

Verificar se há problemas de segurança nas habilidades