Como usar módulos personalizados com o Security Health Analytics

Nesta página, explicamos como criar, visualizar, atualizar e excluir módulos personalizados do Security Health Analytics usando o console do Google Cloud ou a Google Cloud CLI.

Para mais informações introdutórias, consulte Visão geral dos módulos personalizados para o Security Health Analytics.

Antes de começar

Antes de trabalhar com módulos personalizados, você precisa dos seguintes pré-requisitos:

Você precisa do nível Premium do Security Command Center. Para mais informações sobre os níveis do Security Command Center, consulte Visão geral da ativação do Security Command Center.
O Security Health Analytics precisa estar ativado. Para informações sobre como ativar o Security Health Analytics, consulte Ativar ou desativar um serviço integrado.
Sua conta de usuário precisa receber um ou mais papéis do Identity and Access Management (IAM) que contenham as permissões necessárias. Para mais informações, consulte Permissões necessárias do IAM.
Se você pretende gravar seus próprios módulos personalizados e fazer upload deles para o Security Command Center usando comandos gcloud, é necessário usar a Google Cloud CLI. Para mais informações sobre como instalar a CLI gcloud, consulte Instalar a CLI gcloud.
Se a API Security Command Center ainda não estiver ativada, você precisará fazer isso antes de usar módulos personalizados para o Security Health Analytics. É possível ativar a API Security Command Center na página da Biblioteca de APIs no Console do Google Cloud.
Para entender os limites de uso do Security Health Analytics, consulte Cotas de módulos personalizados.

Permissões do IAM obrigatórias

Para trabalhar com módulos personalizados, você precisa das seguintes permissões do Identity and Access Management (IAM):

Permissão	Papel
securitycenter.securityhealthanalyticscustommodules.create securitycenter.securityhealthanalyticscustommodules.update securitycenter.securityhealthanalyticscustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.get securitycenter.securityhealthanalyticscustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.test	roles/securitycenter.securityHealthAnalyticsCustomModulesTester roles/securitycenter.adminViewer roles/securitycenter.adminEditor roles/securitycenter.admin

Para mais informações sobre permissões e papéis do IAM e como concedê-los, consulte Conceder um papel do IAM usando o console do Google Cloud.

Criar um módulo personalizado

Nesta seção, explicamos como criar módulos personalizados usando o console do Google Cloud ou a CLI gcloud.

Para testar o módulo personalizado como uma etapa do processo de criação, você precisa preparar as definições de recursos de teste em um arquivo YAML. Para ver instruções, consulte Criar recursos de teste em um arquivo YAML.

Para criar um módulo personalizado, selecione o método que você quer usar nas guias a seguir:

Console do Google Cloud

Para criar um módulo personalizado no console do Google Cloud, siga estas etapas:

Acesse a página Configurações do Security Command Center no console do Google Cloud.

Acesse configurações
Se solicitado, selecione a organização, a pasta ou o projeto em que você precisa criar o módulo personalizado.
No card Análise de integridade de segurança, clique em Gerenciar configurações.
Clique na guia Módulos.
Clique em Criar módulo. A página Criar módulo para o Security Health Analytics é aberta.
No painel Configurar módulo, defina o nome de exibição, os recursos a serem verificados e a lógica de detecção:
1. No campo Module name, especifique um nome para o módulo. O nome precisa ter entre 1 e 128 caracteres, começar com letra minúscula e conter apenas caracteres alfanuméricos ou sublinhados. Esse nome se torna a categoria de descobertas das descobertas que esse detector produz. Não será possível mudar o nome depois da criação do módulo.
2. Em Adicionar tipo de recurso, especifique de um a cinco tipos de recursos a verificar. Não é possível especificar um tipo de recurso mais de uma vez.
  
  Para acessar uma lista de tipos de recursos compatíveis, consulte Tipos de recursos compatíveis.
3. No Editor de expressão, escreva expressões CEL para executar verificações booleanas em uma ou mais propriedades do recurso especificado na última etapa. Para acionar uma descoberta, a expressão precisa ser resolvida como TRUE. Por exemplo, a expressão a seguir aciona uma descoberta se um recurso CryptoKey tiver um período de rotação definido e esse período for maior que 2.592.000 segundos (30 dias):
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  Para ver mais informações, consulte os seguintes tópicos:
4. Clique em Próxima. O painel Definir detalhes da descoberta é aberto.
No painel Definir os detalhes da descoberta, descreva o problema que o módulo personalizado detecta, incluindo a gravidade, qual é o problema, como corrigir o problema e os dados que você quer receber para incluir nas descobertas como propriedades de origem personalizadas:
1. No campo Gravidade, especifique a gravidade do problema. Você pode especificar Low, Medium, High ou Critical. O padrão é Medium.
  
  Para informações sobre os níveis de gravidade, consulte Classificações de gravidade para descobertas.
2. No campo Descrição da descoberta, explique o problema que o módulo personalizado detecta. Essa explicação aparece em cada instância de descoberta para ajudar as equipes de segurança a entender e resolver o problema detectado.
3. No campo Como encontrar as próximas etapas, explique as etapas que sua equipe de segurança pode seguir para corrigir ou resolver o problema detectado.
  
  As etapas são exibidas com cada instância de descoberta. Inclua etapas específicas que a equipe de segurança pode seguir para resolver o problema o mais rápido possível.
4. Opcional: no campo Propriedades de descoberta personalizadas, especifique até 10 pares de valores de nome para definir propriedades de origem personalizadas que serão retornadas com cada instância de descoberta. As informações são retornadas como propriedades de origem no JSON de descoberta e exibidas na guia Propriedades de origem, nos detalhes da descoberta no console do Google Cloud. Especifique os valores de texto ou propriedade como pares de chave-valor:
  - No campo Nome da propriedade, especifique um nome para a propriedade de origem personalizada. O nome precisa estar em conformidade com as seguintes regras:
    - O nome precisa começar com uma letra minúscula.
    - O nome precisa conter apenas caracteres alfanuméricos ou sublinhados.
    - O nome precisa ter entre 1 e 128 caracteres.
    - Cada nome precisa ser exclusivo entre as outras propriedades de origem.
  - No campo Valor da propriedade, especifique um dos seguintes valores em 1.024 caracteres ou menos:
    - Uma string de texto entre aspas. As aspas são incluídas no limite de 1.024 caracteres. Por exemplo: "This string provides additional useful information."
    - Qualquer propriedade do recurso que está sendo verificado. Por exemplo, se você estiver verificando o recurso CryptoKey, poderá especificar resource.rotationPeriod. O valor da propriedade rotationPeriod é retornado.
5. Clique em Próxima. O painel Ativar módulo é aberto.
Opcional: use o menu suspenso do painel Ativar módulo para especificar se o módulo personalizado será ativado ou desativado após a criação. Por padrão, os módulos personalizados são ativados após a criação. Se você especificar Desativar, poderá ativar o módulo mais tarde na guia Módulos da página de configurações do Security Health Analytics.
Clique em Próxima. O painel Módulo de teste é aberto.
Opcional: antes de criar seu módulo personalizado, recomendamos que você o teste.

Para testar um módulo personalizado, siga estas etapas:
1. Crie um arquivo YAML contendo as definições dos recursos de teste para os recursos que o módulo personalizado verificar.
  
  Para informações sobre como criar um arquivo de dados de teste, consulte Criar recursos de teste em um arquivo YAML.
2. Em Fazer upload do arquivo YAML, clique em Procurar para fazer upload do arquivo YAML que contém as definições de recurso de teste. O teste começa automaticamente quando o arquivo é enviado.
3. Em Visualização dos resultados do teste, confira os resultados.
  - Se houver sintaxe ou outros erros no arquivo YAML, uma mensagem de erro flutuante será exibida perto da parte inferior da página do navegador.
  - Se o teste for bem-sucedido, ele vai retornar as seguintes informações:
    - Nome de exibição do módulo personalizado.
    - O nome arbitrário especificado na propriedade resource no arquivo de dados de teste.
    - A organização, a pasta ou o projeto em que o módulo personalizado foi ou será criado.
Os resultados do teste não são armazenados ou gravados no Security Command Center.

Para mais informações, consulte Como testar módulos personalizados.
Clique em Criar. Você retornará à página Módulos e verá o módulo que criou com o status Ativado.

Novos módulos personalizados não estão disponíveis para uso pelo Security Health Analytics nas verificações. Para mais informações, consulte Latência de detecção.

CLI da gcloud

Para criar um módulo personalizado usando comandos gcloud, primeiro você precisa codificar a definição do módulo personalizado em um arquivo YAML que inclua expressões CEL para a lógica de detecção e propriedades de saída.

Depois que a definição for concluída, faça upload da definição no Security Command Center usando os comandos da CLI gcloud.

Codifique uma definição de módulo personalizado em um arquivo YAML de acordo com as instruções em Codificar um módulo personalizado para a Análise de integridade da segurança.
Salve o arquivo YAML em um local acessível à instância da CLI gcloud.
Faça upload da definição personalizada para o Security Command Center:
```
gcloud scc custom-modules sha create \
    PARENT_FLAG=PARENT_ID \
    --display-name="MODULE_DISPLAY_NAME" \
    --enablement-state="ENABLEMENT_STATE" \
    --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Substitua:
- PARENT_FLAG: o nível em que você está criando o módulo personalizado, --organization, --folder ou --project.
- PARENT_ID: o ID da organização, pasta ou projeto em que você está criando o módulo personalizado.
- ENABLEMENT_STATE: enabled ou disabled.
- MODULE_DISPLAY_NAME: o nome da categoria de descoberta que você quer exibir quando o módulo personalizado retornar uma descoberta. O nome precisa ter entre 1 e 128 caracteres, começar com letra minúscula e conter apenas caracteres alfanuméricos ou sublinhados.
- MODULE_FILE_NAME: o caminho e nome do arquivo YAML que contém a definição do módulo personalizado.

Detecção de latência

Depois de criar ou atualizar a definição de um módulo personalizado, pode haver um atraso de várias horas até que o módulo personalizado novo ou atualizado esteja disponível para uso em verificações.

A criação ou modificação de um módulo personalizado não aciona uma verificação. Depois que um módulo personalizado estiver disponível para uso, o Security Health Analytics não vai começar a usá-lo até que a primeira verificação em lote ou uma alteração na configuração do recurso de destino acione uma verificação em tempo real.

Para mais informações sobre os tipos de verificação do Security Health Analytics, consulte Tipos de verificação do Security Health Analytics.

Atualizar um módulo personalizado

Você pode atualizar a maioria das propriedades dos módulos personalizados do Security Health Analytics.

As seguintes propriedades de um módulo personalizado não podem ser alteradas:

O nome de exibição.
O ID do módulo personalizado.
O nome completo do recurso do módulo personalizado.

Quando você atualiza um módulo personalizado, as descobertas que o módulo personalizado emitiu anteriormente não são atualizadas ao mesmo tempo. Se as alterações no módulo resultarem em mudanças nas descobertas emitidas, as descobertas refletirão as mudanças somente após o próximo lote do Security Health Analytics ou verificação em tempo real.

Para modificar um módulo personalizado, use o console do Google Cloud ou a CLI gcloud. Clique em uma das guias a seguir para ver instruções.

Console do Google Cloud

Para atualizar um módulo personalizado no Console do Google Cloud, siga estas etapas:

Acesse a página Configurações do Security Command Center no console do Google Cloud.

Acesse configurações
No seletor de projeto, selecione a organização, a pasta ou o projeto em que o módulo personalizado foi criado originalmente. Não é possível editar um módulo personalizado em outro lugar.
No card Análise de integridade de segurança, clique em Gerenciar configurações.
Selecione a guia Modules. Todos os módulos de detecção do Security Health Analytics são exibidos.
Use o campo de filtro na parte superior da lista de módulos ou role a tela para encontrar o módulo personalizado que você precisa modificar.
No lado direito da linha do módulo personalizado, clique no ícone do menu de ações .
No menu "Ação", clique no ícone Editar (). A página Visualizar módulo é aberta e exibe a guia Configurar módulo.
Edite os campos do módulo personalizado de cada guia na página Ver módulo, conforme necessário.
Opcional: recomendamos que você teste as atualizações antes de salvar.

Para testar um módulo personalizado, siga estas etapas:
1. Crie um arquivo YAML contendo as definições dos recursos de teste para os recursos que o módulo personalizado verificar.
  
  Para informações sobre como criar um arquivo de dados de teste, consulte Criar recursos de teste em um arquivo YAML.
2. Em Fazer upload do arquivo YAML, clique em Procurar para fazer upload do arquivo YAML que contém as definições de recurso de teste. O teste começa automaticamente quando o arquivo é enviado.
3. Em Visualização dos resultados do teste, confira os resultados.
  - Se houver sintaxe ou outros erros no arquivo YAML, uma mensagem de erro flutuante será exibida perto da parte inferior da página do navegador.
  - Se o teste for bem-sucedido, ele vai retornar as seguintes informações:
    - Nome de exibição do módulo personalizado.
    - O nome arbitrário especificado na propriedade resource no arquivo de dados de teste.
    - A organização, a pasta ou o projeto em que o módulo personalizado foi ou será criado.
Os resultados do teste não são armazenados ou gravados no Security Command Center.

Para mais informações, consulte Como testar módulos personalizados.
Na parte inferior da página, clique em Salvar. Suas mudanças são aplicadas ao módulo personalizado.

CLI da gcloud

Para atualizar um módulo personalizado usando a CLI gcloud, primeiro edite a definição YAML do módulo personalizado e, em seguida, use comandos gcloud para atualizar o módulo personalizado no Security Health Analytics.

Editar a definição do módulo personalizado. Para ver informações sobre como codificar uma definição de módulo personalizado, consulte Programar um módulo personalizado para o Security Health Analytics.
Salve o arquivo YAML editado em um local acessível à CLI gcloud.
Atualize o módulo personalizado no Security Health Analytics executando o seguinte comando:
```
gcloud scc custom-modules sha update MODULE_ID \
   PARENT_FLAG=PARENT_ID \
   --enablement-state="ENABLED" \
   --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Substitua:
- MODULE_ID: o ID do projeto ou o nome completo do recurso do módulo personalizado.
- PARENT_FLAG: o nível em que o módulo personalizado foi criado, --organization, --folder ou --project.
- PARENT_ID: o ID da organização, pasta ou projeto em que o módulo personalizado foi criado.
- MODULE_FILE_NAME: o caminho e nome do arquivo YAML que contém a definição do módulo personalizado.

Ver um módulo personalizado

Selecione uma guia para saber como ver uma definição de módulo personalizado.

Console do Google Cloud

Para visualizar módulos personalizados no console do Google Cloud, siga estas etapas:

Acesse a página Análise de integridade de segurança nas configurações do Security Command Center.

Acesse configurações
Clique na guia Módulos. O painel Modules será aberto.
Se necessário, use o campo de filtro na parte superior da lista de módulos para encontrar o módulo personalizado que você precisa modificar.
Para ver os detalhes da definição do módulo personalizado, clique no ícone do menu de ação , no lado direito da linha do módulo personalizado.
No menu "Ação", clique no ícone Editar, . A página Visualizar módulo é aberta e mostra a guia Configurar módulo.
Clique nas guias da página Ver módulo para ver todos os campos da definição personalizada do módulo.

CLI da gcloud

Para visualizar os detalhes de um módulo personalizado, insira o seguinte comando:

gcloud scc custom-modules sha get MODULE_ID \
      PARENT_FLAG=PARENT_ID

Substitua:

MODULE_ID: o ID do projeto ou o nome completo do recurso do módulo personalizado.
PARENT_FLAG: o nível em que o módulo personalizado foi criado, --organization, --folder ou --project.
PARENT_ID: o ID da organização, pasta ou projeto em que o módulo personalizado foi criado.

Listar módulos personalizados

Selecione uma guia para saber como exibir uma lista de módulos personalizados.

Console do Google Cloud

Acesse a página Análise de integridade de segurança nas configurações do Security Command Center.

Acesse configurações
Clique na guia Módulos. O painel Modules será aberto.
Clique no campo de filtro na parte superior da lista de módulos para exibir a lista de tipos de filtro.
Selecione Type e digite Custom. As listas de módulos são atualizadas para exibir apenas módulos personalizados.

CLI da gcloud

Para ver uma lista de módulos personalizados, insira o seguinte comando:

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

Substitua:

PARENT_FLAG: o nível em que o módulo personalizado foi criado, --organization, --folder ou --project.
PARENT_ID: o ID da organização, pasta ou projeto em que o módulo personalizado foi criado.

Excluir um módulo personalizado

É possível excluir um módulo personalizado da organização, pasta ou projeto em que ele foi criado ou de uma organização ou pasta pai. Não é possível excluir um módulo personalizado de uma pasta ou projeto que o herda.

Para saber como excluir um módulo personalizado, selecione uma das guias a seguir.

Console do Google Cloud

Acesse a página Configurações do Security Command Center no console do Google Cloud.

Acesse configurações
Se solicitado, selecione a organização, a pasta ou o projeto.
No card Análise de integridade de segurança, clique em Gerenciar configurações.
Selecione a guia Modules. Todos os módulos de detecção do Security Health Analytics são exibidos.
Use o campo de filtro na parte superior da lista de módulos ou role a tela para encontrar o módulo personalizado que você precisa modificar.
No lado direito da linha do módulo personalizado, clique no ícone do menu de ações .
No menu "Ação", clique em Excluir. A caixa de diálogo Delete custom module vai ser aberta.
Na caixa de diálogo, clique em Excluir.

CLI da gcloud

Para excluir um módulo personalizado, insira o seguinte comando:

gcloud scc custom-modules sha delete MODULE_ID \
    PARENT_FLAG=PARENT_ID

Substitua:

MODULE_ID: o ID do projeto ou o nome completo do recurso do módulo personalizado.
PARENT_FLAG: o nível em que o módulo personalizado foi criado, --organization, --folder ou --project.
PARENT_ID: o ID da organização, pasta ou projeto em que o módulo personalizado foi criado.

As descobertas de módulos personalizados excluídos são marcadas como inativas pela Análise de integridade da segurança na próxima verificação em lote.

Como revisar descobertas

As descobertas geradas por módulos personalizados podem ser visualizadas no console do Google Cloud ou na API Security Command Center.

Console do Google Cloud

É possível ver as descobertas geradas pelos seus módulos personalizados com as outras descobertas do Security Command Center no console do Google Cloud.

Para ver as descobertas, siga estas etapas:

Acesse a página Descobertas no console do Google Cloud.

Acesse Descobertas
Se solicitado, selecione a organização.
No painel Filtros rápidos, role para baixo até a seção Nome de exibição da origem e clique em Security Health Analytics Custom. O painel Resultados da consulta de descobertas é atualizado para mostrar apenas as descobertas dos módulos personalizados do Security Health Analytics.

Se você não encontrar a opção Security Health Analytics Custom, isso significa que nenhum módulo personalizado retornou descobertas.
Para visualizar detalhes de uma descoberta específica, na coluna Categoria do painel Resultados da consulta de descobertas, clique no nome da categoria da descoberta. O painel de detalhes da descoberta se expande para exibir um resumo dos detalhes da descoberta.
Se alguma propriedade de origem personalizada tiver sido definida para o módulo personalizado, você poderá visualizá-la clicando na guia Source properties.
Para conferir a definição JSON completa da descoberta, clique na guia JSON.

CLI da gcloud

Para ver as descobertas, faça o seguinte:

Abra uma janela de terminal.

Para ver o ID de origem do Security Health Analytics, execute o seguinte comando:

gcloud scc sources describe organizations/ORGANIZATION_ID \
--source-display-name='Security Health Analytics Custom'

A saída será semelhante a esta: No exemplo, SOURCE_ID é um ID atribuído pelo servidor para fontes de segurança.

description: ...
displayName: Security Health Analytics Custom
name: organizations/ORGANIZATION_ID/sources/SOURCE_ID

Para listar todas as descobertas geradas pelos módulos personalizados, execute o comando a seguir.
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```

Para listar as descobertas de um módulo personalizado específico, execute o seguinte comando:

gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""

A seguir

É possível gerenciar as descobertas geradas por módulos personalizados, como todas as descobertas no Security Command Center. Para ver instruções, consulte as seguintes informações: