Directrices para las contribuciones de la comunidad a las integraciones de respuestas

Disponible en:

En este documento se describen las directrices para enviar integraciones de respuesta a Google SecOps a través de contribuciones de la comunidad. Todas las integraciones enviadas se someten a un proceso de verificación por parte del equipo oficial de Google SecOps, que se centra en los requisitos destacados en este documento.

Metadatos de integración de respuestas

Nombre

El nombre debe corresponderse con el nombre del producto con el que se va a integrar la integración y no debe contener caracteres especiales.

El Nombre visible debe escribirse con espacios. Por ejemplo, Vertex AI y no VertexAI.

Integration Identifier

El identificador de integración es un identificador único de la integración. Una vez que se haya creado la integración, no se podrá cambiar este valor. El identificador debe tener el mismo valor que Name, pero con los espacios en blanco eliminados.

El identificador está disponible en la mayoría de los lugares de la plataforma.

Descripción

La descripción debe ofrecer una visión general del producto con el que se crea la integración y no debe superar los 500 caracteres. Debe incluir la siguiente información:

This integration is owned by the "{vendor name}". Support Contact: {email}.

No incluyas URLs en la descripción.

Logotipos

Cada integración debe tener un icono SVG. Este icono debe adaptarse a los temas de la plataforma. Los iconos solo deben heredar el tema de la plataforma.

Debe validar el logotipo en las siguientes páginas:

A continuación se muestra un ejemplo de logotipo SVG diseñado para cumplir nuestra guía de estilo:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>

Asegúrate de codificar el archivo SVG antes de añadirlo al archivo de definición de la integración, como se indica en otras integraciones del mercado.

Como parte de la integración, puedes añadir un enlace que dirija a los usuarios a la documentación. Esta documentación debe alojarse en tu sitio.

Los usuarios pueden acceder al enlace de la documentación desde la sección Parámetros del cuadro de diálogo Configurar instancia.

Parámetros de configuración

Todas las integraciones deben contener parámetros de configuración (raíz de la API y parámetros de autenticación), a menos que la API subyacente no requiera autenticación y la raíz de la API se pueda codificar de forma rígida. En todas las integraciones en las que se necesite autenticación, debe haber un parámetro Verify SSL.

Todos los parámetros deben tener una descripción. La descripción debe ayudar a los usuarios a configurar la integración desde la plataforma. No incluyas URLs en la descripción de los parámetros.

Acción de ping

La acción Ping es una acción especial que usa la plataforma para validar la conectividad de la API. Esta acción es obligatoria aunque tu integración de no tenga ninguna otra acción. Cada vez que el usuario pulse el botón Probar en la configuración de la integración, se debe mostrar un estado preciso de la conectividad.

Notas de la versión

La estructura general de las notas de la versión debe seguir el siguiente formato:

  • {integration item} - {update}
    • Por ejemplo: Get Case Details - Added ability to fetch information about affected IOCs

En función de la situación, hay notas de la versión únicas para escenarios específicos:

  • Si se trata de una integración nueva, haz lo siguiente: New Integration Added - {integration name}
  • Si se añade una acción: New Action Added - {action name}
  • Si se añade un conector nuevo: New Connector Added - {connector name}
  • Si se añade un nuevo trabajo: New Job Added - {job name}
  • Si se añade un widget predefinido a una acción: {action name} - Added Predefined Widget.
  • Si se actualiza un widget predefinido: {action name} - Updated Predefined Widget.
  • Para los cambios que afecten a todos los elementos de integración, haz lo siguiente: Integration - {Update}
  • Para los cambios que afecten a todas las acciones: Integration's Actions - {Update}
  • Para los cambios que afecten a todos los conectores, haz lo siguiente: Integration's Connectors - {Update}
  • Para los cambios que afecten a todos los trabajos: Integration's Jobs - {Update}

Si la versión contenía un cambio regresivo, en la nota de la versión debes especificar REGRESSIVE!. Por ejemplo, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Las notas de la versión están disponibles en el panel lateral Detalles de la integración, que se muestra al hacer clic en el botón Detalles de la integración.

Gestión de versiones

Después de cada actualización de la integración, se debe actualizar la versión de la integración con un +1. Las versiones deben representarse como un número entero. No se permiten versiones secundarias, como 11.1.3 u 11.1.

Etiquetas

También puede añadir etiquetas a su integración. No cree nuevos tipos de etiquetas, sino que utilice las que ya están en la plataforma. Si no ves ninguna etiqueta que se adapte a tus necesidades, ponte en contacto con el equipo de verificación.

Notas generales

  • Prueba todo el contenido de la integración antes de enviarlo.
  • Revisa todo el contenido de la integración para detectar posibles vulnerabilidades y dependencias vulnerables.
  • Usa siempre la versión compatible más reciente de Python durante el desarrollo (Python 3.11).

Acciones

Nombre

El Nombre de la acción debe apuntar a la actividad que se está llevando a cabo. Por ejemplo, Get Case Details (Obtener detalles del caso), List Entity Events (Listar eventos de la entidad) o Execute Search (Ejecutar búsqueda).

Si la acción se ha diseñado para funcionar principalmente con entidades, es preferible incluir Entity en el nombre. Por ejemplo, Enrich Entities.

Los nombres de las acciones deben tener entre 2 y 3 palabras.

Descripción

En la descripción de la acción se debe indicar al usuario cuál será el resultado de la ejecución de la acción.

Si la acción funciona con entidades, debes añadir información sobre los tipos de entidades admitidos. Por ejemplo:

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Si la acción funciona en modo Async, debes incluir la siguiente nota en la descripción:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Intenta que la descripción no supere los 500 caracteres.

Parámetros de acción

Los parámetros de configuración de las acciones deben tener un nombre intuitivo. No uses caracteres especiales y procura que el nombre del parámetro de acción tenga entre dos y cuatro palabras.

La descripción del parámetro debe explicar al usuario qué impacto tiene ese parámetro en la ejecución de la acción. Si el parámetro admite una cantidad predeterminada de valores, en la descripción, incluya la siguiente sección: Possible Values: {value 1}, {value 2}

Salida de la acción (resultado de la secuencia de comandos)

El resultado de la secuencia de comandos debe representar un resultado sencillo de la acción. En la mayoría de los casos, solo debe apuntar a una variable llamada is_success, que puede tomar los valores true o false.

Por lo general, si la acción ha finalizado y ha realizado una operación, is_success debe ser true.

Salida de la acción (resultado en JSON)

El resultado JSON es el resultado más importante de la acción. Todos los datos disponibles en el resultado JSON se podrán consultar durante la ejecución del libro de jugadas. Verifica que se esté enviando un objeto JSON válido a la salida.

Los resultados JSON tienen un límite de tamaño de 15 MB.

Cuando crees un resultado JSON, asegúrate de que no haya claves que sean únicas durante la ejecución. Por ejemplo, el siguiente objeto JSON representa una estructura deficiente, ya que no se podría usar en los cuadernos de estrategias:


{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}

En su lugar, utiliza este formato:


[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]

Si usas entidades en la acción y devuelves resultados por entidad, lo más recomendable es estructurar el resultado JSON de la siguiente manera:


[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]

Ten siempre en cuenta cómo se puede usar el resultado de la acción en la automatización.

Asegúrate de que haya un ejemplo JSON para tu acción.

La plataforma usa el ejemplo de JSON en el creador de expresiones durante el proceso de creación del cuaderno de estrategias. Si el ejemplo de JSON es preciso, la experiencia de creación de la guía será mucho mejor. Elimina toda la información personal identificable de los ejemplos de JSON.

Salidas de acciones (enriquecimiento de entidades)

Si las acciones se ejecutan en entidades, durante la ejecución de la acción puedes añadir metadatos adicionales a las entidades. La estructura de esos metadatos debe seguir este formato: {integration identifier}_{key}. Por ejemplo: WebRisk_is_malicious.

Puede encontrar los metadatos añadidos en la página de detalles de las entidades.

Salidas de acciones (mensaje de salida)

El mensaje de salida debe explicar al usuario cómo se ha ejecutado la acción de forma más descriptiva. Debe indicar al usuario el resultado de la ejecución de la acción.

Si algunas entidades se han enriquecido correctamente, pero otras no, lo más recomendable es proporcionar información sobre el estado de cada entidad en el mensaje.

Si crees que se ha producido un error crítico durante la ejecución de la acción, asegúrate de que haya un mensaje detallado para esta situación y rechaza la acción. Si la acción falla, la guía correspondiente detendrá la ejecución hasta que se resuelva el error o se omita manualmente.

Estos son algunos ejemplos de mensajes de salida:

  • Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
  • Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
  • None of the provided entities were found in VirusTotal.
  • Successfully executed query "{query}" in Google SecOps.

Si la acción debe fallar y detener la ejecución del cuaderno de estrategias, se recomienda que el mensaje de salida tenga la siguiente estructura:

"Error executing action "{action name}". Reason: {error}'

No incluyas todo el traceback de los errores. En su lugar, intenta indicar al usuario el problema real en lenguaje natural.

Conectores

Nombre

El Nombre del conector debe dirigir al usuario a los datos que se van a ingerir. En general, la estructura del nombre debe ser la siguiente:

  • {integration display name} - {data that is being ingested} Connector
    • Por ejemplo: Crowdstrike - Pull Alerts Connector

Descripción

En la descripción del conector se debe indicar al usuario qué datos se van a ingerir. Por ejemplo, Pull alerts from Crowdstrike. Además, debe proporcionar información sobre la compatibilidad con listas dinámicas. Por ejemplo, Dynamic List works with the display_name parameter.

En este caso, la descripción final sería la siguiente:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Intenta que la descripción no supere los 500 caracteres.

Parámetros de conectores

Los parámetros de configuración del conector deben tener un nombre intuitivo. No uses caracteres especiales y procura que el nombre del parámetro de acción tenga entre dos y cuatro palabras.

En la descripción del parámetro se debe explicar al usuario qué impacto tiene en la ejecución del conector.

Si el parámetro admite una cantidad predeterminada de valores, incluya la siguiente sección en la descripción: Possible Values: {value 1}, {value 2}. debe tener los siguientes parámetros:

  • Alertas máximas que se deben obtener: indica cuántos {object} se deben procesar durante una iteración del conector.
  • Máximo {horas/días} hacia atrás: determina la hora de inicio de la primera iteración del conector. Por ejemplo, si Horas máximas hacia atrás se define en 1, el conector empezará a extraer datos de una hora antes.
  • Verificar SSL: verifica la conectividad con la API o la instancia.

Asignación de ontologías

Por cada conector que se cree, se recomienda proporcionar una asignación de ontología para verificar que los clientes mutuos disfruten de la mejor experiencia.

La asignación de ontologías se usa para crear automáticamente entidades (IOCs y recursos). Además, se definen los metadatos críticos de los campos del sistema, como Hora de inicio y Hora de finalización.

Lista dinámica

La lista dinámica es una función opcional que te permite crear un filtro avanzado para la ingestión. Te ofrece la flexibilidad de crear cualquier lógica personalizada y, al mismo tiempo, disfrutar de una experiencia de usuario única. El caso práctico más habitual es definir una lista de permitidos o una lista de bloqueo para la ingestión.

Si vas a crear una lógica personalizada para Dynamic List, asegúrate de que se proporcione en la descripción del conector. Además, se recomienda usar el parámetro Use Dynamic List as a blocklist (Usar lista dinámica como lista de bloqueo) para que también se admita la lógica inversa.

Empleo

Nombre

El nombre del trabajo debe explicar al usuario qué hace. En general, la estructura del nombre debe ser la siguiente:

  • {integration display name} - {process} Job
    • Por ejemplo: ServiceNow - Sync Incidents Job

Descripción

En la descripción del trabajo se debe destacar qué hace el trabajo durante las iteraciones. Por ejemplo, This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Intenta que la descripción no supere los 500 caracteres.

Parámetros de trabajo

Los parámetros de configuración de los trabajos deben tener un nombre intuitivo. Evita usar caracteres especiales e intenta limitar el nombre del parámetro de acción a entre dos y cuatro palabras.

En la descripción del parámetro se debe explicar al usuario qué impacto tiene en la ejecución del trabajo.

Si el parámetro admite una cantidad predeterminada de valores, incluye la siguiente sección en la descripción:

Possible Values: {value 1}, {value 2}.

Además de los parámetros de autenticación, todos los trabajos deben tener los siguientes parámetros:

  • Máximo {Horas/Días} hacia atrás: determina la hora de inicio de la primera iteración del trabajo.
  • Verificar SSL: verifica la conectividad con la API o la instancia.

¿Necesitas más ayuda? Recibe respuestas de los miembros de la comunidad y de los profesionales de Google SecOps.