Codifique um módulo personalizado para o Security Health Analytics

Esta página explica como programar uma definição de módulo personalizado através do Idioma de expressão comum (IEC) e do YAML.

Use a CLI do Google Cloud para carregar as definições de módulos personalizados para o Security Health Analytics.

No ficheiro YAML, uma definição de módulo personalizado consiste num conjunto estruturado de propriedades que usa para definir os seguintes elementos de um módulo personalizado do Security Health Analytics:

  • Os recursos a analisar.
  • A lógica de deteção a usar.
  • As informações a fornecer às suas equipas de segurança para que possam compreender, classificar e resolver rapidamente o problema detetado.

As propriedades específicas obrigatórias e opcionais que compõem uma definição YAML são abordadas nos passos de programação.

Evite criar detetores redundantes

Para controlar o volume de localização, evite criar e executar módulos que contenham funcionalidades redundantes.

Por exemplo, se criar um módulo personalizado que verifique se as chaves de encriptação não são rodadas após 30 dias, considere desativar o detetor de análise de integridade de segurança incorporado KMS_KEY_NOT_ROTATED, porque a respetiva verificação, que usa um valor de 90 dias, seria supérflua.

Para mais informações sobre como desativar detetores, consulte o artigo Ative e desative detetores.

Passos de programação

Codifica a definição de um módulo personalizado para o Security Health Analytics como uma série de propriedades YAML, algumas das quais contêm expressões CEL.

Para programar um módulo de definição personalizado, siga estes passos:

  1. Crie um ficheiro de texto com a extensão do nome de ficheiro yaml.

  2. No ficheiro de texto, crie uma propriedade resource_selector e especifique um a cinco tipos de recursos para o módulo personalizado analisar. Não é possível especificar um tipo de recurso mais do que uma vez numa definição de módulo personalizado. Por exemplo:

    resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey

    Os tipos de recursos que especificar têm de ser suportados pelo Security Command Center. Para ver uma lista dos tipos de recursos suportados, consulte o artigo Tipos de recursos suportados.

  3. Crie uma propriedade predicate e especifique uma ou mais expressões CEL que verificam as propriedades dos tipos de recursos a serem analisados. Todas as propriedades a que faz referência nas expressões de IEC têm de existir na Google Cloud definição da API de cada tipo de recurso que especifica em resource_selector. Para acionar uma descoberta, a expressão tem de ser resolvida como TRUE. Por exemplo, na expressão seguinte, apenas os valores de rotationPeriod superiores a 2592000s acionam uma descoberta.

    predicate:
 expression: resource.rotationPeriod > duration("2592000s")

    Para receber ajuda na escrita de expressões CEL, consulte os seguintes recursos:

  4. Crie uma propriedade description que explique a vulnerabilidade ou a configuração incorreta que o módulo personalizado deteta. Esta explicação aparece em cada instância da descoberta para ajudar os investigadores a compreender o problema detetado. O texto tem de estar entre aspas. Por exemplo:

    description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."

  5. Crie uma propriedade recommendation que explique como corrigir o problema detetado. A CLI gcloud requer um caráter de escape antes de determinados carateres, como as aspas. O exemplo seguinte mostra a utilização da barra invertida para ignorar cada conjunto de aspas:

    recommendation: "To fix this issue go to
  https://console.cloud.google.com/security/kms. Click the key-ring that
  contains the key. Click the key. Click \"Edit rotation period\". Then
  set the rotation period to at most 30 days."

    Se criar ou atualizar um módulo personalizado através da Google Cloud consola, não são necessários carateres de escape.

  6. Crie uma propriedade severity e especifique a gravidade predefinida para as descobertas criadas por este módulo. Os valores usados frequentemente para a propriedade severity são LOW, MEDIUM, HIGH e CRITICAL. Por exemplo,

    severity: MEDIUM

  7. Opcionalmente, crie uma propriedade custom_output e especifique informações adicionais a devolver com cada resultado. Especifique as informações a devolver como um ou mais pares de nome-valor. Pode devolver o valor de uma propriedade do recurso analisado ou uma string literal. As propriedades têm de ser especificadas como resource.PROPERTY_NAME. As strings literais têm de estar entre aspas. O exemplo seguinte mostra uma definição que devolve um valor de propriedade, o valor de rotationPeriod no recurso CryptoKey analisado e uma string de texto, "Excessive rotation period for CryptoKey":custom_output

     custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "Excessive rotation period for CryptoKey"

  8. Guarde o ficheiro numa localização à qual a CLI gcloud possa aceder.

  9. Carregue a definição para o Security Health Analytics com o seguinte comando:

     gcloud scc custom-modules sha create \
     --organization=organizations/ORGANIZATION_ID \
     --display-name="MODULE_DISPLAY_NAME" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=DEFINITION_FILE_NAME.yaml

    Substitua os seguintes valores:

    • ORGANIZATION_ID com o ID da organização principal do módulo personalizado ou substitua a flag --organization por --folders ou --project e especifique o ID da pasta ou do projeto principal.
    • MODULE_DISPLAY_NAME com um nome a apresentar como a categoria de deteção quando o módulo personalizado devolve deteções. 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.
    • DEFINITION_FILE_NAME com o caminho e o nome do ficheiro do ficheiro YAML que contém a definição do módulo personalizado.

    Para mais informações sobre como trabalhar com módulos personalizados do Security Health Analytics, consulte o artigo Usar módulos personalizados para o Security Health Analytics.

Analise as latências de novos módulos personalizados

A criação de um módulo personalizado não aciona uma nova análise.

O Security Health Analytics não começa a usar um novo módulo personalizado até que se verifique uma das seguintes situações:

  • A primeira análise em lote depois de criar o módulo personalizado. Consoante a altura em que cria um módulo personalizado na sua programação de análise em lote, pode ter de aguardar até 24 horas antes de o Security Health Analytics começar a usar o módulo personalizado.
  • Uma alteração a um recurso de destino aciona uma análise em tempo real.

Exemplo de definição de módulo personalizado

O exemplo seguinte mostra uma definição de módulo personalizado concluída que aciona uma descoberta se o valor da propriedade rotationPeriod de um recurso cloudkms.googleapis.com/CryptoKey for superior a 2 592 000 segundos (30 dias). O exemplo devolve dois valores opcionais na secção custom_output: o valor de resource.rotationPeriod e uma nota como uma cadeia de texto.

No exemplo, repare nos seguintes elementos:

  • O tipo de recurso ou recurso a verificar está indicado na secção resource_selector abaixo de resource_types.
  • A verificação que o módulo realiza nos recursos, a respetiva lógica de deteção, é definida na secção predicate precedida de expression.
  • Duas propriedades de origem personalizadas, duration e violation, são definidas na secção custom_output.
  • A explicação do problema detetado é especificada na propriedade description.
  • As orientações para corrigir o problema detetado são especificadas na propriedade recommendation. Uma vez que as aspas aparecem nas orientações, é necessário um carater de escape de barra invertida antes de cada aspa.
severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
  resource_types:
  - cloudkms.googleapis.com/CryptoKey
predicate:
  expression: resource.rotationPeriod > duration("2592000s")
custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.rotationPeriod
    - name: violation
      value_expression:
        expression:
          "Excessive rotation period for CryptoKey"

Referenciar propriedades de recursos e políticas em módulos personalizados

Independentemente do método que usar para criar um módulo personalizado, quer seja através da Google Cloud consola ou escrevendo a definição, tem de conseguir procurar as propriedades que pode avaliar no módulo personalizado. Também tem de saber como fazer referência a essas propriedades numa definição de módulo personalizado.

Encontre as propriedades de um recurso ou uma política

As propriedades de um recurso Google Cloud são definidas na definição da API do recurso. Pode encontrar esta definição clicando no nome do recurso em Tipos de recursos suportados.

Pode encontrar as propriedades de uma política na documentação de referência da API IAM. Para ver as propriedades de uma política, consulte o artigo Política.

Faça referência a uma propriedade de recurso numa definição de módulo personalizado

Quando cria um módulo personalizado, todas as referências diretas à propriedade de um recurso analisado têm de começar com resource, seguido de quaisquer propriedades principais e, finalmente, a propriedade de destino. As propriedades estão separadas por um ponto, usando uma notação de pontos no estilo JSON.

Seguem-se exemplos de propriedades de recursos e como podem ser obtidas:

  • resourceName: armazena o nome completo de um recurso no Cloud Asset Inventory, por exemplo, //cloudresourcemanager.googleapis.com/projects/296605646631.
  • resource.rotationPeriod: onde rotationPeriod é uma propriedade de resource.
  • resource.metadata.name: onde name é uma subpropriedade de metadata, que é uma subpropriedade de resource.

Referencie propriedades da Política IAM

Pode criar expressões CEL que avaliam a política de IAM de um recurso referenciando as propriedades da política de IAM do recurso. As únicas propriedades disponíveis são associações e funções dentro das associações.

Quando faz referência a propriedades da política IAM, policy é a propriedade de nível superior.

Seguem-se exemplos de propriedades da política de IAM e como podem ser obtidas:

  • policy.bindings, onde bindings é uma propriedade de policy.
  • policy.version, onde version é uma propriedade de policy.

Para ver mais exemplos, consulte o artigo Exemplos de expressões CEL.

Para obter informações sobre as propriedades de uma política, consulte o artigo Política.

Escrever expressões IEC

Quando cria um módulo personalizado, usa expressões CEL para avaliar as propriedades do recurso analisado. Opcionalmente, também pode usar expressões CEL para definir pares name-value personalizados que devolvem informações adicionais com as suas descobertas.

Quer crie um módulo personalizado na Google Cloud consola ou escreva a definição do módulo personalizado num ficheiro YAML, as expressões CEL que definir são as mesmas.

Expressões IEC para lógica de deteção

Codifica a lógica de deteção de um módulo personalizado usando expressões CEL com operadores CEL padrão para avaliar as propriedades dos recursos analisados.

As suas expressões podem ser verificações simples de um único valor ou expressões compostas mais complexas que verificam vários valores ou condições. De qualquer forma, a expressão tem de ser resolvida como um valor booleano true para acionar uma descoberta.

Se estiver a criar um módulo personalizado na Google Cloud consola, escreve estas expressões no editor de expressões na página Configurar módulo.

Se estiver a programar um módulo personalizado num ficheiro YAML, adicione estas expressões na propriedade predicate.

Independentemente de estar a usar a Google Cloud consola ou um ficheiro YAML, as expressões CEL que avaliam as propriedades dos recursos têm de estar em conformidade com as seguintes regras:

  • As propriedades que especificar numa expressão CEL têm de ser propriedades do recurso analisado, conforme definido na definição da API do tipo de recurso.

  • Se um módulo personalizado avaliar vários tipos de recursos, as propriedades que especificar nas expressões CEL têm de ser comuns a cada tipo de recurso que o módulo personalizado avalia.

    Por exemplo, se definir um módulo personalizado denominado invalid_cryptokey que verifique dois tipos de recursos: cloudkms.googleapis.com/CryptoKey e cloudkms.googleapis.com/CryptoKeyVersion, pode escrever a seguinte expressão, porque os tipos de recursos CryptoKey e CryptoKeyVersion incluem a propriedade name:

    predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")

    No entanto, não pode especificar a seguinte expressão no módulo personalizado invalid_cryptokey porque as propriedades importTime e rotationPeriod que a expressão avalia não são partilhadas por ambos os tipos de recursos:

    predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")

  • Todas as enumerações numa expressão CEL têm de ser representadas como strings. Por exemplo, o seguinte é uma expressão válida para o tipo de recurso cloudkms.googleapis.com/CryptoKeyVersion:

    resource.state = "PENDING_GENERATION"

  • O resultado das expressões CEL que definir na propriedade predicate tem de ser um valor booleano. Uma descoberta só é acionada se o resultado for true.

Para mais informações sobre o CEL, consulte o seguinte:

Exemplos de expressões de IEC

A tabela seguinte apresenta algumas expressões de IEC que podem ser usadas para avaliar as propriedades dos recursos. Pode usar ambos na consolaGoogle Cloud e nas definições de módulos personalizados YAML.

Tipo de recurso Explicação Expressão IEC
Qualquer recurso com uma política de IAM Verificação da política IAM para identificar membros de um domínio externo !policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))
cloudkms.googleapis.com/CryptoKey Verificação do período de rotação de chaves do Cloud KMS has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')
Vários tipos de recursos com uma única política Verifique se o nome do recurso começa por dev ou devAccess com base no tipo de recurso (resource.type == 'compute.googleapis.com/Disk' && resource.name.startsWith('projects/PROJECT_ID/regions/ REGION/disks/devAccess')) || (resource.type == 'compute.googleapis.com/Instance ' && resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-'))
compute.googleapis.com/Network Regra de intercâmbio da nuvem privada virtual para corresponder a pares de rede resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') || resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$'))
cloudfunctions.googleapis.com/CloudFunction Permita apenas tráfego de entrada interno para a função do Cloud Run has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')
compute.googleapis.com/Instance O nome do recurso corresponde ao padrão resource.name.matches('^gcp-vm-(linux|windows)-v\\d+$')
serviceusage.googleapis.com/Service Permitir apenas a ativação de APIs relacionadas com o armazenamento resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') || resource.name.matches('bigquery-json.googleapis.com') || resource.name.matches('bigquery.googleapis.com') || resource.name.matches('sql-component.googleapis.com') || resource.name.matches('spanner.googleapis.com'))
sqladmin.googleapis.com/Instance Apenas são permitidos IPs públicos na lista de autorizações (resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' || ip.ipAddress.matches('IP_ADDRESS'))))
dataproc.googleapis.com/Cluster Verifique se os IDs dos projetos num cluster do Dataproc contêm as subcadeias de carateres testing ou development has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development')

Expressões CEL para propriedades de localização personalizadas

Opcionalmente, para devolver informações adicionais com cada resultado que podem ser usadas em consultas de localização, pode definir até dez propriedades personalizadas para devolver com os resultados gerados pelos seus módulos personalizados.

As propriedades personalizadas aparecem nas propriedades de origem da descoberta no seu JSON e no separador Propriedades de origem dos detalhes da descoberta naGoogle Cloud consola.

Define propriedades personalizadas como pares name-value.

Se estiver a criar um módulo personalizado na Google Cloud consola, define os pares name-value na secção Propriedades de deteção personalizadas na página Definir detalhes da deteção.

Se estiver a programar um módulo personalizado num ficheiro YAML, lista os pares name-value como properties na propriedade custom_output.

Independentemente de estar a usar a Google Cloud consola ou um ficheiro YAML, aplicam-se as seguintes regras:

  • Especifique name como uma string de texto sem aspas.

  • Especifique value como uma das seguintes opções:

    • Para devolver o valor de uma propriedade, especifique a propriedade no seguinte formato:

      RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN

    No exemplo:

    • RESOURCE_TYPE pode ser resource ou policy.
    • PROPERTY uma ou mais propriedades principais da propriedade que contém o valor a devolver.

    • PROPERTY_TO_RETURN é a propriedade que contém o valor a devolver.

    • Para devolver uma string de texto, inclua a string entre aspas.

O exemplo seguinte mostra dois pares name-value definidos corretamente em custom_output num ficheiro YAML:

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "Note content"

O que se segue?

Para testar, enviar, ver e atualizar módulos personalizados, consulte as seguintes páginas: