Programar un módulo personalizado para Security Health Analytics

Solo para el nivel Premium: Esta función solo está disponible en el nivel Premium de Security Command Center.

En esta página, se explica cómo programar una definición de módulo personalizado con Common Expression Language (CEL) y YAML.

Usa Google Cloud CLI para subir las definiciones de tu módulo personalizado a las estadísticas del estado de seguridad.

En el archivo YAML, una definición de módulo personalizado consiste en un conjunto estructurado de propiedades que usas para definir los siguientes elementos de un módulo personalizado de estadísticas del estado de la seguridad:

• Los recursos que se analizarán.
• La lógica de detección que se usará.
• La información que debes proporcionar a los equipos de seguridad para que puedan comprender, clasificar y resolver con rapidez el problema detectado.

Las propiedades específicas obligatorias y opcionales que conforman una definición de YAML se tratan en Pasos de codificación.

Evita crear detectores redundantes

Para controlar el volumen de resultados, evita crear y ejecutar módulos que contengan funcionalidades redundantes.

Por ejemplo, si creas un módulo personalizado que verifica las claves de encriptación que no se rotan después de 30 días, considera inhabilitar el detector integrado de Security Health Analytics KMS_KEY_NOT_ROTATED, ya que su verificación, que usa un valor de 90 días, sería superflua.

Para obtener más información sobre cómo inhabilitar los detectores, consulta Habilita o inhabilita detectores.

Pasos de programación

Codificas la definición de un módulo personalizado para las estadísticas del estado de la seguridad como una serie de propiedades YAML, algunas de las cuales contienen expresiones CEL.

Para programar un módulo de definición personalizada, sigue estos pasos:

1. Crea un archivo de texto con la extensión de nombre de archivo yaml.

2. En el archivo de texto, crea una propiedad resource_selector y especifica de uno a cinco tipos de recursos para que el módulo personalizado analice. No se puede especificar un tipo de recurso más de una vez en una definición de módulo personalizado. Por ejemplo:

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

   Los tipos de recursos que especifiques deben ser compatibles con Security Command Center. Para obtener una lista de los tipos de recursos admitidos, consulta Tipos de recursos admitidos.

3. Crea una propiedad predicate y especifica una o más expresiones en CEL que verifiquen las propiedades de los tipos de recursos que se analizarán. Cualquier propiedad a la que hagas referencia en las expresiones en CEL debe existir en la definición de la API de Google Cloud de cada tipo de recurso que especifiques en resource_selector. Para activar un resultado, la expresión debe resolverse como TRUE. Por ejemplo, en la siguiente expresión, solo los valores rotationPeriod mayores que 2592000s activan un resultado.

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

   Para obtener ayuda con la escritura de expresiones en CEL, consulta los siguientes recursos:

   • Tipos de recursos admitidos. Haz clic en cada recurso para ver las propiedades que puedes usar en tus expresiones CEL.
   • Escribe expresiones en CEL.
   • Haz referencia a propiedades de recursos y políticas en módulos personalizados.

4. Crea una propiedad description que explique la vulnerabilidad o la configuración incorrecta que detecta el módulo personalizado. Esta explicación aparece en cada instancia de resultado para ayudar a los investigadores a comprender el problema detectado. El texto debe encerrarse entre comillas. Por ejemplo:

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

5. Crea una propiedad recommendation que explique cómo solucionar el problema detectado. Gcloud CLI requiere un carácter de escape antes de ciertos caracteres, como las comillas. En el siguiente ejemplo, se muestra el uso de la barra inversa para escapar cada conjunto de comillas:

   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."
   

   Si creas o actualizas un módulo personalizado con la consola de Google Cloud, no se requieren caracteres de escape.

6. Crea una propiedad severity y especifica la gravedad predeterminada para los resultados que crea este módulo. Los valores que se usan con más frecuencia para la propiedad severity son LOW, MEDIUM, HIGH y CRITICAL. Por ejemplo,

   severity: MEDIUM

7. De manera opcional, crea una propiedad custom_output y especifica información adicional que se mostrará con cada resultado. Especifica la información que se mostrará como uno o más pares nombre-valor. Puedes mostrar el valor de una propiedad del recurso analizado o una cadena literal. Las propiedades se deben especificar como resource.PROPERTY_NAME. Las cadenas literales deben estar entre comillas. En el siguiente ejemplo, se muestra una definición de custom_output que muestra un valor de propiedad, el valor de rotationPeriod en el recurso CryptoKey analizado y una cadena de texto, "Excessive rotation period for CryptoKey":

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

8. Guarda el archivo en una ubicación a la que pueda acceder tu gcloud CLI.

9. Sube la definición a Security Health Analytics con el siguiente 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
   

   Reemplaza los siguientes valores:

   • ORGANIZATION_ID por el ID de la organización superior del módulo personalizado o reemplaza la marca --organization por --folders o --project y especifica el ID de la carpeta o el proyecto superiores.
   • MODULE_DISPLAY_NAME con un nombre para mostrar como categoría de resultado cuando el módulo personalizado muestra resultados. El nombre debe tener entre 1 y 128 caracteres, comenzar con una letra minúscula y contener solo caracteres alfanuméricos o guiones bajos.
   • DEFINITION_FILE_NAME por la ruta de acceso y el nombre de archivo del archivo YAML que contiene la definición del módulo personalizado

   Si deseas obtener más información para trabajar con los módulos personalizados de Security Health Analytics, consulta Usa módulos personalizados para Security Health Analytics.

Analizar latencias de módulos personalizados nuevos

La creación de un módulo personalizado no activa un análisis nuevo.

Security Health Analytics no comienza a usar un módulo personalizado nuevo hasta que se cumple alguna de las siguientes condiciones:

• El primer análisis por lotes después de crear el módulo personalizado. Según el momento en el que crees un módulo personalizado en tu programa de análisis por lotes, es posible que debas esperar hasta 24 horas para que las estadísticas del estado de seguridad comiencen a usar el módulo personalizado.
• Un cambio en un recurso objetivo activa un análisis en tiempo real.

Ejemplo de definición de módulo personalizado

En el siguiente ejemplo, se muestra la definición completa de un módulo personalizado que activa un resultado si el valor de la propiedad rotationPeriod de un recurso cloudkms.googleapis.com/CryptoKey es superior a 2,592,000 segundos (30 días). En el ejemplo, se muestran dos valores opcionales en la sección custom_output: el valor de resource.rotationPeriod y una nota como string de texto.

En el ejemplo, observa los siguientes elementos:

• El tipo de recurso o recurso que se debe verificar se muestra en la sección resource_selector en resource_types.
• La verificación que el módulo realiza en los recursos, su lógica de detección, se define en la sección predicate precedida por expression.
• En la sección custom_output, se definen dos propiedades fuente personalizadas, duration y violation.
• La explicación del problema que se detectó se especifica en la propiedad description.
• La guía para solucionar el problema detectado se especifica en la propiedad recommendation. Debido a que las comillas aparecen en la guía, se requiere un carácter de escape de barra inversa antes de cada comilla.

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"

Haz referencia a propiedades de recursos y políticas en módulos personalizados

Sin importar el método que uses para crear un módulo personalizado (mediante la consola de Google Cloud o escribiendo la definición tú mismo), debes poder buscar las propiedades que puedes evaluar en el módulo personalizado. También debes saber cómo hacer referencia a esas propiedades en una definición de módulo personalizada.

Busca las propiedades de un recurso o una política

Las propiedades de un recurso de Google Cloud se definen en la definición de la API del recurso. Para encontrar esta definición, haz clic en el nombre del recurso en Tipos de recursos admitidos.

Puedes encontrar las propiedades de una política en la documentación de referencia de la API de IAM. Para ver las propiedades de una política, consulta Política.

Cómo hacer referencia a una propiedad de recurso en una definición de módulo personalizado

Cuando creas un módulo personalizado, todas las referencias directas a la propiedad de un recurso analizado deben comenzar con resource, seguidas de cualquier propiedad superior y, por último, la propiedad de destino. Las propiedades están separadas por un punto mediante una notación de puntos de estilo JSON.

Los siguientes son ejemplos de propiedades de recursos y cómo se pueden recuperar:

• resourceName: Almacena el nombre completo de un recurso en Cloud Asset Inventory, por ejemplo, //cloudresourcemanager.googleapis.com/projects/296605646631.
• resource.rotationPeriod: donde rotationPeriod es una propiedad de resource.
• resource.metadata.name: En el ejemplo anterior, name es una subpropiedad de metadata, que es una subpropiedad de resource.

Propiedades de las políticas de IAM de referencia

Puedes crear expresiones en CEL que evalúen la política de IAM de un recurso si haces referencia a las propiedades de la política de IAM del recurso. Las únicas propiedades disponibles son las vinculaciones y los roles dentro de las vinculaciones.

Cuando se hace referencia a las propiedades de la política de IAM, policy es la propiedad de nivel superior.

Los siguientes son ejemplos de propiedades de políticas de IAM y cómo se pueden recuperar:

• policy.bindings, donde bindings es una propiedad de policy.
• policy.version, donde version es una propiedad de policy.

Para obtener más ejemplos, consulta Expresiones en CEL de ejemplo.

Para obtener información sobre las propiedades de una política, consulta Política.

Escribe expresiones en CEL

Cuando creas un módulo personalizado, usas expresiones en CEL para evaluar las propiedades del recurso analizado. De manera opcional, también puedes usar expresiones CEL para definir pares name-value personalizados que muestren información adicional con tus resultados.

Ya sea que crees un módulo personalizado en la consola de Google Cloud o escribas la definición del módulo personalizado en un archivo YAML, las expresiones de CEL que definas son las mismas.

Expresiones en CEL para la lógica de detección

Codificas la lógica de detección de un módulo personalizado mediante expresiones de CEL con operadores CEL estándar para evaluar las propiedades de los recursos analizados.

Las expresiones pueden ser verificaciones simples de un solo valor o expresiones compuestas más complejas que verifican varios valores o condiciones. De cualquier manera, la expresión debe resolverse en un valor booleano true para activar un resultado.

Si creas un módulo personalizado en la consola de Google Cloud, escribe estas expresiones en el Editor de expresiones, en la página Configurar módulo.

Si codificas un módulo personalizado en un archivo YAML, agrega estas expresiones en la propiedad predicate.

Sin importar si usas la consola de Google Cloud o un archivo YAML, las expresiones en CEL que evalúan las propiedades de los recursos deben cumplir con las siguientes reglas:

• Las propiedades que especificas en una expresión CEL deben ser propiedades del recurso analizado, como se define en la definición de la API del tipo de recurso.

• Si un módulo personalizado evalúa varios tipos de recursos, las propiedades que especifiques en las expresiones en CEL deben ser comunes a cada tipo de recurso que evalúe el módulo personalizado.

  Por ejemplo, si defines un módulo personalizado llamado invalid_cryptokey que verifica dos tipos de recursos: cloudkms.googleapis.com/CryptoKey y cloudkms.googleapis.com/CryptoKeyVersion, podrías escribir la siguiente expresión, ya que los tipos de recursos CryptoKey y CryptoKeyVersion incluyen la propiedad name:

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

  Sin embargo, no puedes especificar la siguiente expresión en el módulo personalizado invalid_cryptokey porque las propiedades importTime y rotationPeriod que la expresión evalúa no se comparten en ambos tipos de recursos:

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

• Todas las enumeraciones en una expresión CEL se deben representar como strings. Por ejemplo, la siguiente es una expresión válida para el tipo de recurso cloudkms.googleapis.com/CryptoKeyVersion:

  resource.state = "PENDING_GENERATION"

• El resultado de las expresiones en CEL que defines en la propiedad predicate debe ser un booleano. Un resultado solo se activa si el resultado es true.

Para obtener más información sobre CEL, consulta lo siguiente:

• La especificación de CEL
• La definición del lenguaje CEL

Expresiones de CEL de ejemplo

En la siguiente tabla, se enumeran algunas expresiones en CEL que se pueden usar para evaluar las propiedades de los recursos. Puedes usarlos en la consola de Google Cloud y en las definiciones del módulo personalizado de YAML.

Tipo de recurso	Explicación	Expresión CEL
Cualquier recurso con una política de IAM	Verificación de la política de IAM para identificar a los miembros del dominio externo	!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))
cloudkms.googleapis.com/CryptoKey	Verificación del período de rotación de claves de Cloud KMS	has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')
Varios tipos de recursos con una sola política	Verifica si el nombre del recurso comienza con dev o devAccess según el 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	Regla de intercambio de tráfico de la nube privada virtual para que coincida con los intercambios de tráfico de la red	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	Solo permite el tráfico de entrada interno para la Cloud Function	has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')
compute.googleapis.com/Instance	El nombre del recurso coincide con el patrón	resource.name.matches('^gcp-vm-(linux|windows)-v\\d+$')
serviceusage.googleapis.com/Service	Solo permitir que se habiliten las APIs relacionadas con el almacenamiento	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	Solo se permiten las IP públicas incluidas en la lista de entidades permitidas	(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	Verifica si los ID del proyecto en un clúster de Dataproc contienen las subcadenas de prueba o desarrollo	has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development')

Expresiones en CEL para propiedades de resultados personalizadas

Opcionalmente, para mostrar información adicional con cada resultado que se puede usar en las consultas de resultados, puedes definir hasta diez propiedades personalizadas que se mostrarán con los resultados que generan tus módulos personalizados.

Las propiedades personalizadas aparecen en las propiedades fuente del resultado en su JSON y en la pestaña Propiedades fuente de los detalles del resultado en la consola de Google Cloud.

Las propiedades personalizadas se definen como pares name-value.

Si creas un módulo personalizado en la consola de Google Cloud, debes definir los pares name-value en la sección Propiedades personalizadas del resultado de la página Define los detalles del resultado.

Si codificas un módulo personalizado en un archivo YAML, enumera los pares name-value como properties en la propiedad custom_output.

Sin importar si usas la consola de Google Cloud o un archivo YAML, se aplican las siguientes reglas:

• Especifica name como una cadena de texto sin comillas.

• Especifica value como una de las siguientes opciones:

  • Para mostrar el valor de una propiedad, especifícala en el siguiente formato:

    RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN

  En el ejemplo:

  • RESOURCE_TYPE puede ser resource o policy.
  • PROPERTY: Una o más propiedades superiores de la propiedad que contiene el valor que se mostrará.

  • PROPERTY_TO_RETURN es la propiedad que contiene el valor que se mostrará.

  • Para mostrar una cadena de texto, encierra la cadena entre comillas.

En el siguiente ejemplo, se muestran dos pares name-value definidos correctamente en custom_output en un archivo YAML:

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

¿Qué sigue?

Para probar, enviar, ver y actualizar módulos personalizados, consulta las siguientes páginas:

• Para probar los módulos personalizados, consulta Cómo probar módulos personalizados para las estadísticas del estado de seguridad.
• Para subir, ver y actualizar módulos personalizados, consulta Crea y administra módulos personalizados para Security Health Analytics.