Esta página se ha traducido con Cloud Translation API.

Codificar un módulo personalizado para Security Health Analytics

En esta página se explica cómo codificar una definición de módulo personalizado mediante el lenguaje de expresión común (CEL) y YAML.

Usa la CLI de Google Cloud para subir las definiciones de tus módulos personalizados a Security Health Analytics.

En el archivo YAML, una definición de módulo personalizado consta de un conjunto estructurado de propiedades que se usan para definir los siguientes elementos de un módulo personalizado de Security Health Analytics:

Los recursos que se van a analizar.
La lógica de detección que se va a usar.
La información que deben proporcionar a sus equipos de seguridad para que puedan entender, evaluar y resolver rápidamente el problema detectado.

Las propiedades obligatorias y opcionales específicas que componen una definición YAML se explican en la sección Pasos de codificación.

Evita crear detectores redundantes

Para controlar el volumen de las búsquedas, evita crear y ejecutar módulos que contengan funciones redundantes.

Por ejemplo, si crea un módulo personalizado que comprueba si las claves de cifrado no se han rotado después de 30 días, puede inhabilitar el detector KMS_KEY_NOT_ROTATED de Security Health Analytics, ya que su comprobación, que usa un valor de 90 días, sería superflua.

Para obtener más información sobre cómo inhabilitar detectores, consulta el artículo Habilitar e inhabilitar detectores.

Pasos de codificación

Codificas la definición de un módulo personalizado para Security Health Analytics como una serie de propiedades YAML, algunas de las cuales contienen expresiones CEL.

Para codificar un módulo de definición personalizado, sigue estos pasos:

Crea un archivo de texto con la extensión de nombre de archivo yaml.
En el archivo de texto, cree una propiedad resource_selector y especifique de uno a cinco tipos de recursos para que los analice el módulo personalizado. 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 ver una lista de los tipos de recursos admitidos, consulta Tipos de recursos admitidos.
Crea una propiedad predicate y especifica una o varias expresiones CEL que comprueben las propiedades de los tipos de recursos que se van a analizar. Las propiedades a las que hagas referencia en las expresiones de CEL deben existir en laGoogle Cloud definición de API 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 de rotationPeriod superiores a 2592000s activan una detección.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Para obtener ayuda a la hora de escribir expresiones CEL, consulta los siguientes recursos:
- Tipos de recursos admitidos Haga clic en cada recurso para ver las propiedades que puede usar en sus expresiones de CEL.
- Escribir expresiones CEL
- Hacer referencia a propiedades de recursos y políticas en módulos personalizados
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 los resultados para ayudar a los investigadores a entender el problema detectado. El texto debe ir 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."
```
Crea una propiedad recommendation que explique cómo solucionar el problema detectado. La CLI gcloud requiere un carácter de escape antes de determinados caracteres, como las comillas. En el siguiente ejemplo se muestra el uso de la barra invertida 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 mediante la consolaGoogle Cloud , no es necesario aplicar caracteres de escape.
Crea una propiedad severity y especifica la gravedad predeterminada de las detecciones que cree este módulo. Los valores que se suelen usar para la propiedad severity son LOW, MEDIUM, HIGH y CRITICAL. Por ejemplo,
```
severity: MEDIUM
```
También puede crear una propiedad custom_output y especificar información adicional que se devuelva con cada resultado. Especifica la información que quieres devolver como uno o varios pares de nombre y valor. Puede devolver el valor de una propiedad del recurso analizado o una cadena literal. Las propiedades deben especificarse como resource.PROPERTY_NAME. Las cadenas literales deben escribirse entre comillas. En el siguiente ejemplo se muestra una definición de custom_output que devuelve tanto un valor de propiedad (el valor de rotationPeriod en el recurso CryptoKey analizado) como 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"
```
Guarda el archivo en una ubicación a la que pueda acceder tu CLI de gcloud.
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
```
Sustituye los siguientes valores:
- ORGANIZATION_ID por el ID de la organización principal del módulo personalizado o sustituye la marca --organization por --folders o --project y especifica el ID de la carpeta o el proyecto principal.
- MODULE_DISPLAY_NAME con un nombre que se mostrará como categoría de resultado cuando el módulo personalizado devuelva resultados. El nombre debe tener entre 1 y 128 caracteres, empezar por una letra minúscula y contener solo caracteres alfanuméricos o guiones bajos.
- DEFINITION_FILE_NAME con la ruta y el nombre de archivo del archivo YAML que contiene la definición del módulo personalizado.
Para obtener más información sobre cómo trabajar con módulos personalizados de Security Health Analytics, consulta el artículo Usar módulos personalizados de Security Health Analytics.

Analizar las latencias de los nuevos módulos personalizados

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

Security Health Analytics no empieza a usar un nuevo módulo personalizado hasta que se cumpla una de las siguientes condiciones:

El primer análisis por lotes después de crear el módulo personalizado. En función de cuándo cree un módulo personalizado en su programación de análisis por lotes, es posible que tenga que esperar hasta 24 horas para que Security Health Analytics empiece a usarlo.
Cuando se modifica un recurso de destino, se activa un análisis en tiempo real.

Ejemplo de definición de módulo personalizado

En el siguiente ejemplo se muestra una definición de módulo personalizado completada que activa una detección 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 devuelven dos valores opcionales en la sección custom_output: el valor de resource.rotationPeriod y una nota como cadena de texto.

En el ejemplo, ten en cuenta los siguientes elementos:

El tipo de recurso o elemento que se debe comprobar se indica en la sección resource_selector de resource_types.
La comprobación que realiza el módulo 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 de origen personalizadas: duration y violation.
La explicación del problema detectado se especifica en la propiedad description.
Las directrices para solucionar el problema detectado se especifican en la propiedad recommendation. Como en las directrices aparecen comillas, es necesario usar el carácter de escape de barra invertida 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"

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

Independientemente del método que uses para crear un módulo personalizado (la consolaGoogle 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 personalizado.

Buscar las propiedades de un recurso o una política

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

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

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 empezar por resource, seguido de las propiedades superiores y, por último, la propiedad de destino. Las propiedades se separan con un punto, mediante la notación de puntos de estilo JSON.

A continuación se muestran ejemplos de propiedades de recursos y cómo se pueden obtener:

resourceName: almacena el nombre completo de un recurso en Inventario de Recursos de Cloud. Por ejemplo, //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: donde rotationPeriod es una propiedad de resource.
resource.metadata.name: name es una subpropiedad de metadata, que es una subpropiedad de resource.

Consultar propiedades de la política de gestión de identidades y accesos

Puedes crear expresiones CEL que evalúen la política de gestión de identidades y accesos de un recurso haciendo referencia a las propiedades de la política de gestión de identidades y accesos del recurso. Las únicas propiedades disponibles son los enlaces y los roles de los enlaces.

Cuando se hace referencia a las propiedades de la política de gestión de identidades y accesos, policy es la propiedad de nivel superior.

A continuación, se muestran ejemplos de propiedades de políticas de gestión de identidades y accesos y cómo se pueden obtener:

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

Para ver más ejemplos, consulta Ejemplos de expresiones CEL.

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

Escribir expresiones CEL

Cuando creas un módulo personalizado, usas expresiones CEL para evaluar las propiedades del recurso analizado. También puede usar expresiones CEL para definir pares name-value personalizados que devuelvan información adicional con sus resultados.

Tanto si creas un módulo personalizado en la Google Cloud consola como si escribes tú mismo la definición del módulo personalizado en un archivo YAML, las expresiones CEL que definas serán las mismas.

Expresiones CEL para la lógica de detección

Para codificar la lógica de detección de un módulo personalizado, debes usar expresiones CEL con operadores CEL estándar para evaluar las propiedades de los recursos analizados.

Las expresiones pueden ser comprobaciones sencillas de un solo valor o expresiones compuestas más complejas que comprueben varios valores o condiciones. De cualquier forma, la expresión debe resolverse como un valor booleano true para activar una detección.

Si vas a crear un módulo personalizado en la Google Cloud consola, escribe estas expresiones en el editor de expresiones de la página Configurar módulo.

Si vas a codificar un módulo personalizado en un archivo YAML, añade estas expresiones en la propiedad predicate.

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

Las propiedades que especifiques en una expresión CEL deben ser propiedades del recurso analizado, tal como se definen 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 de 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 comprueba dos tipos de recursos: cloudkms.googleapis.com/CryptoKey y cloudkms.googleapis.com/CryptoKeyVersion, puedes 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 evalúa la expresión no se comparten entre ambos tipos de recursos:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Todos los enums de una expresión CEL deben representarse como cadenas. 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 CEL que definas en la propiedad predicate debe ser un valor booleano. Una detección solo se activa si el resultado es true.

Para obtener más información sobre CEL, consulta los siguientes recursos:

Ejemplos de expresiones CEL

En la siguiente tabla se incluyen algunas expresiones CEL que se pueden usar para evaluar propiedades de recursos. Puedes usar ambos en la consolaGoogle Cloud y en las definiciones de módulos personalizados de YAML.

Tipo de recurso	Explicación	Expresión CEL
Cualquier recurso con una política de gestión de identidades y accesos	Comprobación de la política de gestión de identidades y accesos para identificar a los miembros que no pertenecen al dominio	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	Comprobación del periodo de rotación de claves de Cloud KMS	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
Varios tipos de recursos con una sola política	Comprueba si el nombre del recurso empieza por `dev` o `devAccess` en función del 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 peering de nube privada virtual para que coincidan las redes peer	`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`	Permitir solo el tráfico de entrada interno de la función de Cloud Run	`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`	Permitir que solo 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 IPs públicas incluidas en la lista de permitidos	`(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`	Comprobar si los IDs de proyecto de un clúster de Dataproc contienen las subcadenas testing o development	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Expresiones CEL para propiedades de resultados personalizadas

Si quieres devolver información adicional con cada resultado que se pueda usar en las consultas de búsqueda, puedes definir hasta diez propiedades personalizadas para que se devuelvan con los resultados que generen tus módulos personalizados.

Las propiedades personalizadas aparecen en las propiedades de origen de la detección en su JSON y en la pestaña Propiedades de origen de los detalles de la detección en la consola deGoogle Cloud .

Las propiedades personalizadas se definen como pares name-value.

Si creas un módulo personalizado en la Google Cloud consola, define los pares name-value en la sección Propiedades de resultados personalizadas de la página Definir detalles de los resultados.

Si estás codificando un módulo personalizado en un archivo YAML, debes enumerar los pares name-value como properties en la propiedad custom_output.

Independientemente de si usas la consola 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 devolver el valor de una propiedad, especifica la propiedad con el siguiente formato:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
En el ejemplo:
- RESOURCE_TYPE puede ser resource o policy.
- PROPERTY una o varias propiedades principales de la propiedad que contiene el valor que se va a devolver.
- PROPERTY_TO_RETURN es la propiedad que contiene el valor que se va a devolver.
- Para devolver una cadena de texto, ponla 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"

Siguientes pasos

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

Para probar módulos personalizados, consulta Probar módulos personalizados de Security Health Analytics.
Para subir, ver y actualizar módulos personalizados, consulta el artículo Crear y gestionar módulos personalizados para Security Health Analytics.