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 na análise de integridade da segurança, 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. Você pode ativar a API Security Command Center 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 | Role |
---|---|
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.
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:
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.
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.
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 recursoCryptoKey
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:
Clique em Next. 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:
No campo Gravidade, especifique a gravidade do problema. Você pode especificar
Low
,Medium
,High
ouCritical
. O padrão éMedium
.Para informações sobre os níveis de gravidade, consulte Classificações de gravidade para descobertas.
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.
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.
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á especificarresource.rotationPeriod
. O valor da propriedaderotationPeriod
é retornado.
- Uma string de texto entre aspas. As aspas são incluídas no limite de 1.024 caracteres. Por exemplo:
- No campo Nome da propriedade, especifique um nome para a propriedade de origem personalizada. O nome precisa estar em conformidade com as seguintes regras:
Clique em Next. 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 Next. 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:
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.
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.
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
oudisabled
.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.
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 (edit). 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:
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.
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.
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 mais informações sobre como programar uma definição de módulo personalizada, consulte Como programar um módulo personalizado para a Análise de integridade da segurança.
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.
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, edit. 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.
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.
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.
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:
- Trabalhar com as descobertas no console do Google Cloud
- Como usar marcações de segurança
- Como configurar as notificações de localização
- Como exportar dados do Security Command Center