Esta página foi traduzida pela API Cloud Translation.

Usar módulos personalizados com o Security Health Analytics

Esta página explica como criar, ver, atualizar e eliminar módulos personalizados para o Security Health Analytics através da Google Cloud consola ou da CLI Google Cloud.

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

Antes de começar

Antes de poder trabalhar com módulos personalizados, tem de cumprir os seguintes pré-requisitos:

A análise de segurança tem de estar ativada. Para obter informações sobre como ativar o Security Health Analytics, consulte o artigo Ative ou desative um serviço integrado.
A sua conta de utilizador tem de ter uma ou mais funções de gestão de identidades e acessos (IAM) que contenham as autorizações necessárias. Para mais informações, consulte o artigo Autorizações de IAM necessárias.
Se pretender escrever os seus próprios módulos personalizados e carregá-los para o Security Command Center através de comandos gcloud, precisa da Google Cloud CLI. Para ver informações sobre a instalação da CLI gcloud, consulte o artigo Instale a CLI gcloud.
Se a API Security Command Center ainda não estiver ativada, tem de a ativar antes de poder usar módulos personalizados para o Security Health Analytics. Pode ativar a API Security Command Center na página da biblioteca de APIs na Google Cloud consola.
Para compreender os limites de utilização do Security Health Analytics, consulte as Quotas de módulos personalizados.

Autorizações de IAM necessárias

Para trabalhar com módulos personalizados, precisa das seguintes autorizações de gestão de identidade e de acesso (IAM):

Autorização	Função
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 as autorizações e as funções do IAM e como as conceder, consulte Conceda uma função do IAM através da Google Cloud consola.

Crie um módulo personalizado

Esta secção explica como criar módulos personalizados através da Google Cloud consola, da CLI gcloud ou do Terraform.

Para testar o seu módulo personalizado como um passo no processo de criação, tem de preparar definições de recursos de teste num ficheiro YAML. Para obter instruções, consulte o artigo Crie recursos de teste num ficheiro YAML.

Para criar um módulo personalizado, selecione o método que quer usar nos seguintes separadores:

Google Cloud consola

Para criar um módulo personalizado na Google Cloud consola, conclua os seguintes passos:

Aceda à página Definições do Security Command Center na Google Cloud consola.

Aceda às Definições
Se lhe for pedido, selecione a organização, a pasta ou o projeto no qual tem de criar o módulo personalizado.
No cartão Análise de estado de segurança, clique em Gerir definições.
Clique no separador Módulos.
Clique em Criar módulo. É apresentada a página Criar módulo para o Security Health Analytics.
No painel Configurar módulo, defina o nome a apresentar, os recursos a analisar e a lógica de deteção:
1. No campo Nome do módulo, especifique um nome para o módulo. O nome tem de ter entre 1 e 128 carateres, começar com uma letra minúscula e conter apenas carateres alfanuméricos ou sublinhados. Este nome torna-se a categoria de deteção das deteções que este detetor produz. Não é possível alterar o nome após a criação do módulo.
2. Em Adicionar tipo de recurso, especifique um a cinco tipos de recursos a analisar. Não pode especificar um tipo de recurso mais do que uma vez.
  
  Para ver uma lista dos tipos de recursos suportados, consulte o artigo Tipos de recursos suportados.
3. No editor de expressões, escreva expressões CEL para executar verificações booleanas numa ou mais propriedades do recurso que especificou no último passo. Para acionar uma descoberta, a expressão tem de ser resolvida como TRUE. Por exemplo, a seguinte expressão aciona uma descoberta se um recurso CryptoKey tiver um período de rotação definido e o período de rotação for superior a 2 592 000 segundos (30 dias):
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  Para mais informações, consulte o seguinte:
4. Clicar em Seguinte. É apresentado o painel Definir detalhes da deteção.
No painel Definir detalhes da descoberta, descreva o problema que o módulo personalizado deteta, incluindo a respetiva gravidade, o que é o problema, como o corrigir e quaisquer dados que queira incluir nas descobertas como propriedades de origem personalizadas:
1. No campo Gravidade, especifique a gravidade do problema. Pode especificar Low, Medium, High ou Critical. Medium é a predefinição.
  
  Para obter informações sobre os níveis de gravidade, consulte o artigo Classificações de gravidade para resultados.
2. No campo Descrição da deteção, explique o problema que o módulo personalizado deteta. Esta explicação aparece em cada instância da descoberta para ajudar as equipas de segurança a compreender e resolver o problema detetado.
3. No campo Encontrar passos seguintes, explique os passos que a sua equipa de segurança pode seguir para corrigir ou resolver o problema detetado.
  
  Os passos são apresentados com cada instância da descoberta. Inclua passos específicos que a equipa de segurança pode seguir para resolver o problema o mais rapidamente possível.
4. Opcional: no campo Propriedades de deteção personalizadas, especifique até 10 pares de nome-valor para definir propriedades de origem personalizadas a devolver com cada instância de deteção. As informações são devolvidas como propriedades de origem no JSON da descoberta e são apresentadas no separador Propriedades de origem nos detalhes da descoberta na Google Cloud consola. Especifique os valores de texto ou de propriedades como pares chave-valor:
  - No campo Nome da propriedade, especifique um nome para a propriedade de origem personalizada. O nome tem de estar em conformidade com as seguintes regras:
    - O nome tem de começar com uma letra minúscula.
    - O nome só pode conter carateres alfanuméricos ou sublinhados.
    - O nome tem de ter entre 1 e 128 carateres.
    - Cada nome tem de ser exclusivo entre as outras propriedades de origem.
  - No campo Valor da propriedade, especifique um dos seguintes valores com 1024 carateres ou menos:
    - Uma string de texto entre aspas. As aspas estão incluídas no limite de 1024 carateres. Por exemplo, "This string provides additional useful information."
    - Qualquer propriedade do recurso que está a ser analisado. Por exemplo, se estiver a verificar o recurso CryptoKey, pode especificar resource.rotationPeriod. É devolvido o valor da propriedade rotationPeriod.
5. Clicar em Seguinte. É aberto o painel Ativar módulo.
Opcional: use o menu pendente do painel Ativar módulo para especificar se o módulo personalizado está ativado ou desativado após a criação. Por predefinição, os módulos personalizados são ativados após a criação. Se especificar Desativar, pode ativar o módulo mais tarde no separador Módulos na página de definições de estatísticas de estado de segurança.
Clicar em Seguinte. É aberto o painel Módulo de teste.
Opcional: antes de criar o módulo personalizado, recomendamos que o teste.

Para testar um módulo personalizado, siga estes passos:
1. Crie um ficheiro YAML que contenha definições de recursos de teste para os recursos que o seu módulo personalizado verifica.
  
  Para obter informações sobre como criar um ficheiro de dados de teste, consulte o artigo Crie recursos de teste num ficheiro YAML.
2. Em Carregue o ficheiro YAML, clique em Procurar para carregar o ficheiro YAML que contém as definições de recursos de teste. O teste começa automaticamente quando o ficheiro é carregado.
3. Em Pré-visualização dos resultados do teste, verifique os resultados.
  - Se existirem erros de sintaxe ou outros erros no ficheiro YAML, é apresentada uma mensagem de erro flutuante perto da parte inferior da página do navegador.
  - Se o teste for bem-sucedido, devolve as seguintes informações:
    - O nome a apresentar do módulo personalizado.
    - O nome arbitrário que especificou na propriedade resource no ficheiro de dados de teste.
    - A organização, a pasta ou o projeto no qual o módulo personalizado foi ou vai ser criado.
Os resultados dos testes não são armazenados nem escritos no Security Command Center.

Para mais informações, consulte o artigo Testar módulos personalizados.
Clique em Criar. Regressa à página Módulos e deve ver o módulo que criou com o estado Ativado.

Os novos módulos personalizados não estão imediatamente disponíveis para utilização pelo Security Health Analytics em análises. Para mais informações, consulte o artigo Latência de deteção.

CLI gcloud

Para criar um módulo personalizado através de comandos gcloud, primeiro tem de codificar a definição do módulo personalizado num ficheiro YAML que inclua expressões CEL para a lógica de deteção e as propriedades de saída.

Depois de concluir a definição, carregue-a para o Security Command Center através de comandos da CLI gcloud.

Codifique uma definição de módulo personalizado num ficheiro YAML de acordo com as instruções em Codifique um módulo personalizado para o Security Health Analytics.
Guarde o ficheiro YAML numa localização acessível à sua instância da CLI gcloud.
Carregue a 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 o seguinte:
- PARENT_FLAG: o nível no qual está a criar o módulo personalizado, --organization, --folder ou --project.
- PARENT_ID: o ID da organização, da pasta ou do projeto no qual está a criar o módulo personalizado.
- ENABLEMENT_STATE: enabled ou disabled.
- MODULE_DISPLAY_NAME: o nome da categoria de resultados que quer apresentar quando o módulo personalizado devolve um resultado. O nome tem de ter entre 1 e 128 carateres, começar com uma letra minúscula e conter apenas carateres alfanuméricos ou sublinhados.
- MODULE_FILE_NAME: o caminho e o nome do ficheiro YAML que contém a definição do módulo personalizado.

Terraform

Crie um módulo personalizado para uma organização:

resource "google_scc_management_organization_security_health_analytics_custom_module" "example" {
  organization = "123456789"
  display_name = "basic_custom_module"
  location = "global"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Crie um módulo personalizado para uma pasta:

resource "google_folder" "folder" {
  parent       = "organizations/123456789"
  display_name = "folder-name"
  deletion_protection = false
}

resource "google_scc_management_folder_security_health_analytics_custom_module" "example" {
  folder = google_folder.folder.folder_id
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Crie um módulo personalizado para um projeto:

resource "google_scc_management_project_security_health_analytics_custom_module" "example" {
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

Latência de deteção

Depois de criar ou atualizar a definição de um módulo personalizado, pode haver um atraso de até várias horas antes de o módulo personalizado novo ou atualizado estar disponível para utilização em análises.

A criação ou a modificação de um módulo personalizado não aciona uma análise. Depois de um módulo personalizado estar disponível para utilização, o Security Health Analytics não começa a usar os módulos personalizados até que a primeira análise em lote ou uma alteração à configuração do recurso de destino acione uma análise em tempo real.

Para mais informações sobre os tipos de análise do Security Health Analytics, consulte o artigo Tipos de análise do Security Health Analytics.

Atualize um módulo personalizado

Pode atualizar a maioria das propriedades dos módulos personalizados do Security Health Analytics.

Não é possível alterar as seguintes propriedades de um módulo personalizado:

O nome a apresentar.
O ID do módulo personalizado.
O nome do recurso completo do módulo personalizado.

Quando atualiza um módulo personalizado, as conclusões que o módulo personalizado gerou anteriormente não são atualizadas ao mesmo tempo. Se as alterações ao módulo resultarem em alterações às conclusões geradas, as conclusões refletem as alterações apenas após a próxima análise em tempo real ou em lote do Security Health Analytics.

Para modificar um módulo personalizado, pode usar a Google Cloud consola ou a CLI gcloud. Clique num dos seguintes separadores para ver instruções.

Google Cloud consola

Para atualizar um módulo personalizado existente na Google Cloud consola, siga estes passos:

Aceda à página Definições do Security Command Center na Google Cloud consola.

Aceda às Definições
No seletor de projetos, selecione a organização, a pasta ou o projeto no qual o módulo personalizado foi originalmente criado. Não pode editar um módulo personalizado noutro local.
No cartão Análise de estado de segurança, clique em Gerir definições.
Selecione o separador Módulos. São apresentados todos os módulos de deteção do Security Health Analytics.
Use o campo de filtro na parte superior da lista de módulos ou desloque a página para encontrar o módulo personalizado que precisa de modificar.
No lado direito da linha do módulo personalizado, clique no ícone do menu de ações, .
No menu Ações, clique no ícone Editar (). A página Ver módulo é aberta e apresenta o separador Configurar módulo.
Edite os campos do módulo personalizado de cada separador na página Ver módulo conforme necessário.
Opcional: antes de guardar as atualizações, recomendamos que as teste.

Para testar um módulo personalizado, siga estes passos:
1. Crie um ficheiro YAML que contenha definições de recursos de teste para os recursos que o seu módulo personalizado verifica.
  
  Para obter informações sobre como criar um ficheiro de dados de teste, consulte o artigo Crie recursos de teste num ficheiro YAML.
2. Em Carregue o ficheiro YAML, clique em Procurar para carregar o ficheiro YAML que contém as definições de recursos de teste. O teste começa automaticamente quando o ficheiro é carregado.
3. Em Pré-visualização dos resultados do teste, verifique os resultados.
  - Se existirem erros de sintaxe ou outros erros no ficheiro YAML, é apresentada uma mensagem de erro flutuante perto da parte inferior da página do navegador.
  - Se o teste for bem-sucedido, devolve as seguintes informações:
    - O nome a apresentar do módulo personalizado.
    - O nome arbitrário que especificou na propriedade resource no ficheiro de dados de teste.
    - A organização, a pasta ou o projeto no qual o módulo personalizado foi ou vai ser criado.
Os resultados dos testes não são armazenados nem escritos no Security Command Center.

Para mais informações, consulte Testar módulos personalizados.
Na parte inferior da página, clique em Guardar. As alterações são aplicadas ao módulo personalizado.

CLI gcloud

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

Edite a definição do módulo personalizado. Para ver informações sobre como programar uma definição de módulo personalizado, consulte o artigo Programar um módulo personalizado para o Security Health Analytics.
Guarde o ficheiro YAML editado numa localização acessível à CLI gcloud.
Atualize o módulo personalizado no Security Health Analytics emitindo 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 o seguinte:
- MODULE_ID: o ID ou o nome completo do recurso do módulo personalizado.
- PARENT_FLAG: o nível no qual o módulo personalizado foi criado, --organization, --folder ou --project.
- PARENT_ID: o ID da organização, da pasta ou do projeto no qual o módulo personalizado foi criado.
- MODULE_FILE_NAME: o caminho e o nome do ficheiro YAML que contém a definição do módulo personalizado.

Veja um módulo personalizado

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

Google Cloud consola

Para ver módulos personalizados na Google Cloud consola, siga estes passos:

Aceda à página Security Health Analytics nas definições do Security Command Center.

Aceda às Definições
Clique no separador Módulos. É aberto o painel Módulos.
Se necessário, use o campo de filtro na parte superior da lista de módulos para encontrar o módulo personalizado que precisa de modificar.
Para ver os detalhes da definição do módulo personalizado, clique no ícone do menu Ações, , no lado direito da linha do módulo personalizado.
No menu Ação, clique no ícone Editar. . A página Ver módulo é aberta e apresenta o separador Configurar módulo.
Clique nos separadores na página Ver módulo para ver todos os campos da definição do módulo personalizado.

CLI gcloud

Para ver os detalhes de um módulo personalizado, introduza o seguinte comando:

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

Substitua o seguinte:

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

Liste módulos personalizados

Selecione um separador para saber como apresentar uma lista de módulos personalizados.

Google Cloud consola

Aceda à página Security Health Analytics nas definições do Security Command Center.

Aceda às Definições
Clique no separador Módulos. É aberto o painel Módulos.
Clique no campo de filtro na parte superior da lista de módulos para apresentar a lista de tipos de filtros.
Selecione Tipo e introduza Custom. A lista de módulos é atualizada para mostrar apenas módulos personalizados.

CLI gcloud

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

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

Substitua o seguinte:

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

Elimine um módulo personalizado

Pode eliminar um módulo personalizado da organização, da pasta ou do projeto no qual foi criado, ou de uma organização ou pasta principal. Não pode eliminar um módulo personalizado de uma pasta ou um projeto que o herde.

Para saber como eliminar um módulo personalizado, selecione um dos seguintes separadores.

Google Cloud consola

Aceda à página Definições do Security Command Center na Google Cloud consola.

Aceda às Definições
Se lhe for pedido, selecione a sua organização, pasta ou projeto.
No cartão Análise de estado de segurança, clique em Gerir definições.
Selecione o separador Módulos. São apresentados todos os módulos de deteção do Security Health Analytics.
Use o campo de filtro na parte superior da lista de módulos ou desloque a página para encontrar o módulo personalizado que precisa de modificar.
No lado direito da linha do módulo personalizado, clique no ícone do menu de ações, .
No menu Ação, clique em Eliminar. É apresentada a caixa de diálogo Eliminar módulo personalizado.
Na caixa de diálogo, clique em Eliminar.

CLI gcloud

Para eliminar um módulo personalizado, introduza o seguinte comando:

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

Substitua o seguinte:

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

As conclusões dos módulos personalizados eliminados são marcadas como inativas pelo Security Health Analytics na análise em lote seguinte.

Rever conclusões

Pode ver as conclusões geradas por módulos personalizados na Google Cloud consola ou na API Security Command Center.

Consola

Na Google Cloud consola, aceda à página Resultados do Centro de comando de segurança.
Aceda a Conclusões
Selecione o seu Google Cloud projeto ou organização.
Na secção Filtros rápidos, na subsecção Nome a apresentar da origem, selecione Security Health Analytics Custom. Os resultados da consulta de conclusões são atualizados para mostrar apenas as conclusões desta origem.
Para ver os detalhes de uma descoberta específica, clique no nome da descoberta na coluna Categoria. O painel de detalhes da descoberta é aberto e apresenta o separador Resumo.
No separador Resumo, reveja os detalhes da descoberta, incluindo informações sobre o que foi detetado, o recurso afetado e, se disponíveis, os passos que pode seguir para corrigir a descoberta.
Opcional: para ver a definição JSON completa da descoberta, clique no separador JSON.

CLI gcloud

Para ver as conclusões, faça o seguinte:

Abra uma janela de terminal.

Para obter o ID da origem do Security Health Analytics, execute o seguinte comando:

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

O resultado da apresentação deve ser semelhante ao seguinte. No exemplo, SOURCE_ID é um ID atribuído pelo servidor para origens de segurança.

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

Para apresentar uma lista de todas as descobertas geradas pelos seus módulos personalizados, execute o seguinte comando:
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```
Para apresentar uma lista de resultados de um módulo personalizado específico, execute o seguinte comando:
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""
```

O que se segue?

Pode gerir as descobertas geradas por módulos personalizados, como todas as descobertas no Security Command Center. Para ver instruções, consulte as seguintes informações:

Usar módulos personalizados com o Security Health Analytics Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Autorizações de IAM necessárias

Crie um módulo personalizado

Google Cloud consola

CLI gcloud

Terraform

Latência de deteção

Atualize um módulo personalizado

Google Cloud consola

CLI gcloud

Veja um módulo personalizado

Google Cloud consola

CLI gcloud

Liste módulos personalizados

Google Cloud consola

CLI gcloud

Elimine um módulo personalizado

Google Cloud consola

CLI gcloud

Rever conclusões

Consola

CLI gcloud

O que se segue?

Usar módulos personalizados com o Security Health Analytics