En esta página, se explica cómo programar una definición de módulo personalizado usando el comando Common Expression Language (CEL) y YAML.
Usar Google Cloud CLI para subir las definiciones de módulos personalizados a Security Health Analytics.
En el archivo YAML, una definición de módulo personalizado consiste en un conjunto estructurado de propiedades que se usan para definir los siguientes elementos de una Módulo personalizado de Security Health Analytics:
- Los recursos que se deben analizar.
- La lógica de detección que se usará.
- La información que debes brindar a tus equipos de seguridad para que puedan comprender, clasificar y resolver el problema detectado.
Las propiedades específicas obligatorias y opcionales que conforman una definición YAML se describen en Pasos para la programación.
Evita crear detectores redundantes
Para controlar el volumen de hallazgos, evita crear y ejecutar módulos que contengan funcionalidad redundante.
Por ejemplo, si creas un módulo personalizado que comprueba si hay claves de encriptación que
no se roten después de 30 días, considera inhabilitar el
El detector de Security Health Analytics KMS_KEY_NOT_ROTATED
, porque
su comprobació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 los detectores.
Pasos de la 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 en CEL.
Para programar un módulo de definición personalizada, sigue estos pasos:
Crea un archivo de texto con la extensión de nombre de archivo
yaml
.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. R el tipo de recurso no se puede especificar más de una vez en un módulo personalizado definición. 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.
Crea una propiedad
predicate
y especifica una o más expresiones en CEL que verifican las propiedades de los tipos de recursos que se analizarán. Cualquier propiedad los datos a los que haces referencia en las expresiones en CEL deben existir en el La API de Google Cloud: Definición de cada tipo de recurso que especificas enresource_selector
. Para activar un hallazgo, la expresión debe resolverse comoTRUE
. Por ejemplo, en la siguiente expresión, solo los valoresrotationPeriod
mayores que2592000s
se activan un hallazgo.predicate: expression: resource.rotationPeriod > duration("2592000s")
Si deseas obtener ayuda para escribir expresiones en CEL, consulta los siguientes recursos:
- Tipos de recursos admitidos. Haz clic en cada recurso para ver las propiedades que puedes usar en tu en CEL.
- Escribe expresiones en CEL.
- Haz referencia a propiedades de recursos y políticas en módulos personalizados.
Crea una propiedad
description
que explique la vulnerabilidad o que detecta el módulo personalizado. Esta explicación aparece en cada instancia de un hallazgo para ayudar a los investigadores a comprender el problema detectado. El texto debe estar 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
en la que se explique cómo corregir el problema el problema detectado. gcloud CLI requiere un carácter de escape antes de ciertos caracteres, como comillas. Lo siguiente En este ejemplo, se muestra el uso de la barra inversa para escapar cada conjunto de comillas marcas: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 Consola de Google Cloud, no se requieren caracteres de escape.
Crea una propiedad
severity
y especifica la gravedad predeterminada del hallazgos que creó este módulo. Valores de uso común para La propiedadseverity
sonLOW
,MEDIUM
,HIGH
yCRITICAL
. Por ejemplo:severity: MEDIUM
De forma opcional, crea una propiedad
custom_output
y especifica información adicional que se devolverá con cada hallazgo. Especifica la información. como uno o más pares nombre-valor. Puedes mostrar el valor de una propiedad del recurso analizado. o una cadena literal. Las propiedades deben especificarse comoresource.PROPERTY_NAME
Las cadenas literales deben tener encerrado entre comillas. En el siguiente ejemplo, se muestra uncustom_output
definición que muestra un valor de propiedad, el valor derotationPeriod
en el recursoCryptoKey
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"
Guarda el archivo en una ubicación a la que pueda acceder tu gcloud CLI.
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 del elemento superior organización del módulo personalizado o reemplaza--organization
con--folders
o--project
y especifica el ID de la carpeta o el proyecto superior.MODULE_DISPLAY_NAME
por un nombre para mostrar como la categoría de hallazgo cuando el módulo personalizado devuelve resultados. Debe tener entre 1 y 128 caracteres y 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 de el archivo YAML que contiene la definición del módulo personalizado.
Para obtener más información sobre cómo trabajar con las estadísticas del estado de seguridad personalizadas módulos, consulta Usa módulos personalizados para Security Health Analytics.
Analiza latencias para nuevos módulos personalizados
La creación de un módulo personalizado no activa un análisis nuevo.
Security Health Analytics no comenzará a usar un nuevo módulo personalizado hasta que de las siguientes opciones:
- El primer análisis por lotes después de crear el módulo personalizado. Según Cuando creas un módulo personalizado en el programa de análisis por lotes, es posible que debes esperar hasta 24 horas para que Security Health Analytics comience a usar el módulo personalizado.
- Un cambio en un recurso de destino 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 completa que
activa un hallazgo si el valor de la propiedad rotationPeriod
de un
El recurso cloudkms.googleapis.com/CryptoKey
es mayor que 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 una cadena de texto.
En el ejemplo, ten en cuenta los siguientes elementos:
- El tipo de recurso que se debe verificar se muestra en el archivo
resource_selector
. enresource_types
. - La verificación que realiza el módulo en los recursos, su lógica de detección
se define en la sección
predicate
, precedida porexpression
. - Se definen dos propiedades fuente personalizadas,
duration
yviolation
en la seccióncustom_output
. - La explicación del problema que se detectó se especifica en el
description
. - La guía para solucionar el problema detectado es
especificadas en la propiedad
recommendation
. Porque aparecen las comillas en la guía, se requiere un carácter de escape de barra inversa antes de cada comillas.
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
Independientemente del método que uses para crear un módulo personalizado, con el la consola de Google Cloud o escribiendo la definición tú mismo, necesitas 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.
Busca las propiedades de un recurso o una política
Las propiedades de un recurso de Google Cloud se definen en la API definición del recurso. Para encontrar esta definición, haz clic en el el nombre del recurso en Tipos de recursos admitidos.
Puedes encontrar las propiedades de una política en la página de IAM, documentación de referencia de la API. Para conocer 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 debe comenzar con resource
, seguido de cualquier recurso superior
y, por último, la propiedad de destino. Las propiedades están separadas
por un punto, con 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, para Por ejemplo,//cloudresourcemanager.googleapis.com/projects/296605646631
.resource.rotationPeriod
: donderotationPeriod
es una propiedad deresource
.resource.metadata.name
: En el ejemplo anterior,name
es una subpropiedad demetadata
. que es una subpropiedad deresource
.
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 haciendo 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.
Estos son algunos ejemplos de las propiedades de las políticas de IAM y cómo que se pueden recuperar:
policy.bindings
, dondebindings
es una propiedad depolicy
.policy.version
, dondeversion
es una propiedad depolicy
.
Para obtener más ejemplos, consulta Expresiones en CEL de ejemplo.
Para obtener información acerca de 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 en CEL para definir pares name
-value
personalizados que muestran resultados
información con tus hallazgos.
Si creas un módulo personalizado en la consola de Google Cloud o escribir por tu cuenta la definición del módulo personalizado en un archivo YAML, las expresiones en CEL que defines son las mismas.
Expresiones CEL para la lógica de detección
Codificas la lógica de detección de un módulo personalizado con CEL con operadores CEL estándar para evaluar las propiedades de los recursos analizados.
Tus expresiones pueden ser verificaciones simples de un solo valor o más complejas.
y compuestas 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, escribes estas expresiones En el editor de expresiones de la página Configure module.
Si estás programando 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 las expresiones en CEL que evalúan las propiedades de los recursos, deben cumplir con el las siguientes reglas:
- Las propiedades que especifiques en una expresión en CEL deben ser propiedades del recurso analizado, como se define en la definición de la API del recurso el tipo de letra.
Si un módulo personalizado evalúa varios tipos de recursos, las propiedades que que especifiques en las expresiones en CEL deben ser comunes a cada tipo de recurso que evalúa 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
ycloudkms.googleapis.com/CryptoKeyVersion
, puedes escribir lo siguiente debido a que los recursosCryptoKey
yCryptoKeyVersion
incluyen la propiedadname
: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 los objetosimportTime
y Las propiedades derotationPeriod
que evalúa la expresión no se comparten por 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 de la siguiente manera: 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 en CEL que defines en la propiedad
predicate
debe ser un valor booleano. Un resultado se activa solo si el resultado estrue
.
Para obtener más información sobre CEL, consulta los siguientes vínculos:
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 usar ambas en el la consola de Google Cloud y en las definiciones de módulos personalizadas en 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 ajenos al dominio | !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 nube privada virtual que debe coincidir con los intercambios de tráfico de 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 permitir el tráfico de entrada interno para 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 |
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 IDs de los proyectos de un clúster de Dataproc contienen para probar o desarrollar subcadenas | has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development') |
Expresiones en CEL para propiedades de resultados personalizadas
De manera opcional, para obtener información adicional con cada hallazgo que se pueda para buscar consultas, puedes definir hasta diez propiedades personalizadas para devolver los resultados que generan tus módulos personalizados.
Las propiedades personalizadas aparecen en las propiedades fuente del hallazgo en la JSON y en la pestaña Propiedades fuente de los detalles del hallazgo 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,
defines los pares name
-value
en Propiedades de resultados personalizadas
en la página Define los detalles del hallazgo.
Si estás programando un módulo personalizado en un archivo YAML, debes enumerar los elementos name
-value
se vincula como properties
en la propiedad custom_output
.
Sin importar si usas la consola de Google Cloud o un archivo 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 la siguiente tabla formato:
RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
En el ejemplo:
RESOURCE_TYPE
puede serresource
opolicy
PROPERTY
una o más propiedades superiores de la que contiene el valor que se mostrará.PROPERTY_TO_RETURN
es la propiedad que contiene el valor que se debe mostrar.Para que se muestre una cadena de texto, enciérrala 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 Prueba módulos personalizados para Security Health Analytics.
- Para subir, ver y actualizar módulos personalizados, consulta Crea y administra módulos personalizados para Security Health Analytics.