Lineamientos para la contribución de la comunidad a las integraciones de respuestas

Compatible con:

En este documento, se describen los lineamientos 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, con un enfoque en los requisitos destacados en este documento.

Metadatos de integración de la respuesta

Nombre

El Nombre debe corresponder al nombre del producto con el que se integrará la integración y no debe contener caracteres especiales.

El nombre visible debe escribirse con espacios en blanco; por ejemplo, Vertex AI y no VertexAI.

Identificador de integración

El identificador de integración es un identificador único de la integración. Una vez creada la integración, no se puede cambiar este valor. El identificador debe tener el mismo valor que Name, pero sin espacios en blanco.

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

Descripción

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

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

Evita incluir URLs en la descripción.

Logotipos

Cada integración debe proporcionarse con un ícono SVG. Este ícono debe adaptarse a los temas de la plataforma. Los íconos solo deben heredar el tema de la plataforma.

Debes validar el logotipo en las siguientes páginas:

A continuación, se muestra un ejemplo de un logotipo en SVG, diseñado para que coincida con 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 agregarlo al archivo de definición de integración, como se puede ver en otras integraciones del mercado.

Como parte de la integración, puedes agregar un vínculo que dirija a los usuarios a la documentación. Se espera que esta documentación se aloje en tu extremo.

Los usuarios pueden acceder al vínculo de la documentación desde la sección Parameters del diálogo Configure Instance.

Parámetros de configuración

Todas las integraciones deben contener parámetros de configuración (parámetros de raíz de la API y de Auth), 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 necesita 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. Evita incluir URLs en la descripción de los parámetros.

Acción de ping

La acción de ping es una acción especial que utiliza la plataforma para validar la conectividad de la API. Esta acción es obligatoria incluso si tu integración no tiene otras acciones. Cada vez que el usuario presione el botón Probar dentro de 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 la nota 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

Según la situación, hay notas de la versión únicas para situaciones específicas:

  • Si se trata de una integración nueva, haz lo siguiente: New Integration Added - {integration name}
  • Si se agrega una acción nueva: New Action Added - {action name}
  • Si se agrega un conector nuevo: New Connector Added - {connector name}
  • Si se agrega un trabajo nuevo: New Job Added - {job name}
  • Si se agrega 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 afectan a todos los elementos de integración: Integration - {Update}
  • Para los cambios que afectan a todas las acciones, haz lo siguiente: Integration's Actions - {Update}
  • Para los cambios que afectan a todos los conectores: Integration's Connectors - {Update}
  • Para los cambios que afectan 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 cuando haces clic en el botón Detalles en la integración.

Control de versiones

Cada actualización de la integración debe ir seguida de una actualización de +1 en la versión de la integración. Las versiones deben representarse como un número entero. No se permiten versiones secundarias, como 11.1.3 o 11.1.

Etiquetas

De manera opcional, puedes agregar etiquetas a tu integración. Evita crear nuevos tipos de etiquetas; usa las que ya están en la plataforma. Si no ves una etiqueta que se adapte a ti, consulta al 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.
  • Siempre usa 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á realizando; por ejemplo, Obtener detalles del caso, Enumerar eventos de la entidad o Ejecutar búsqueda.

Si la acción está diseñada para funcionar principalmente con entidades, es preferible incluir Entity en el nombre; por ejemplo, Enrich Entities.

Los nombres de las acciones deben expresarse en 2 o 3 palabras.

Descripción

La Descripción de la acción debe destacar para el usuario cuál será el resultado de la ejecución de la acción.

Si la acción funciona con entidades, debes agregar información sobre qué tipos de entidades se admiten. 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 proporcionar 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 limitar la descripción a 500 caracteres.

Parámetros de acción

Los parámetros de configuración de la acción deben tener un nombre intuitivo. Evita usar caracteres especiales y trata de limitar el nombre del parámetro de acción a entre 2 y 4 palabras.

La descripción del parámetro debe explicarle 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 admitidos, proporciona la siguiente sección dentro de la descripción: Possible Values: {value 1}, {value 2}

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

El resultado del script debe representar un resultado simple 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.

En general, si la acción finalizó la ejecución y realizó una operación, is_success debe ser true.

Salida de la acción (resultado en JSON)

El resultado en JSON es el resultado más importante de la acción. Se podrá acceder a todos los datos disponibles en el resultado JSON durante la ejecución del playbook. Verifica que se envíe un objeto JSON válido al resultado.

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

Cuando compiles un resultado en formato 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 dentro de los playbooks:


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

En su lugar, usa este formato:


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

Si usas entidades dentro de la acción y devuelves resultados por entidad, la práctica recomendada es estructurar el resultado JSON de la siguiente manera:


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

Siempre considera cómo se puede usar el resultado de la acción dentro de la automatización.

Asegúrate de que haya una muestra de JSON para tu acción.

La plataforma usa la muestra de JSON en el compilador de expresiones durante el proceso de compilación del playbook. Una muestra de JSON precisa mejora significativamente la experiencia de creación del manual. Quita toda la información de PII de las muestras de JSON.

Resultados de la acción (enriquecimiento de entidades)

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

Puedes encontrar los metadatos agregados en la página de detalles de las entidades.

Resultados de la acción (mensaje de salida)

El mensaje de salida debe explicar al usuario cómo se ejecutó la acción de una manera más descriptiva. Debe dirigir al usuario al resultado de la ejecución de la acción.

Si algunas entidades se enriquecieron correctamente, pero otras no, la práctica recomendada es proporcionar información de estado para cada entidad proporcionada en el mensaje.

Si crees que se produjo 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 de que la acción falle. Cuando falla la acción, la guía correspondiente detendrá la ejecución hasta que se resuelva el error o se omita de forma manual.

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 de la guía, se recomienda que el mensaje de salida tenga la siguiente estructura:

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

Evita incluir todo el registro de seguimiento de los errores. En cambio, intenta señalarle 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

La Descripción del conector debe destacar para el usuario lo que se transferirá al conector; por ejemplo, Pull alerts from Crowdstrike. Además, debes 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 se vería de la siguiente manera:

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

Intenta limitar la descripción a 500 caracteres.

Parámetros del conector

Los parámetros de configuración del conector deben tener un nombre intuitivo. Evita usar caracteres especiales y trata de limitar el nombre del parámetro de acción a entre 2 y 4 palabras.

La descripción del parámetro debe explicarle al usuario qué impacto tiene ese parámetro en la ejecución del conector.

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

  • Max Alerts To Fetch: Indica cuántos {object} se deben procesar durante 1 iteración del conector.
  • Max {Hours/Days} Backwards: Indica la hora de inicio en la primera iteración del conector. Por ejemplo, si Max Hours Backwards se establece en 1, el conector comenzará a extraer datos de una hora antes.
  • Verificar SSL: Verifica la conectividad a la API o a la instancia.

Asignación de ontología

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

La correlación de ontologías se usa para crear automáticamente entidades (IOC y recursos). Además, allí 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 transferencia de datos. Tienes la flexibilidad de crear cualquier lógica personalizada con él y, al mismo tiempo, tener una UX única. El caso de uso más común es definir una lista de entidades permitidas o una lista de bloqueo para la transferencia.

Si compilas alguna lógica personalizada para Dynamic List, asegúrate de que se proporcione en la descripción del conector. Además, se recomienda tener un parámetro Use Dynamic List as a blocklist para que también se admita la lógica inversa.

Trabajos

Nombre

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

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

Descripción

La Descripción del trabajo debe destacar para el usuario lo que el trabajo está haciendo durante las iteraciones; por ejemplo, This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Intenta limitar la descripción a 500 caracteres.

Parámetros del trabajo

Los parámetros de configuración del trabajo deben tener un nombre intuitivo. Evita usar caracteres especiales y trata de limitar el nombre del parámetro de acción a entre 2 y 4 palabras.

La descripción del parámetro debe explicarle al usuario qué impacto tiene en la ejecución del trabajo.

Si el parámetro admite una cantidad predeterminada de valores admitidos, proporciona la siguiente sección dentro de 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:

  • Max {Hours/Days} Backwards: Indica la hora de inicio en la primera iteración del trabajo.
  • Verificar SSL: Verifica la conectividad a la API o a la instancia.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.