Aportar integraciones de respuesta de la comunidad

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 revisión por parte del equipo oficial de Google SecOps, con un enfoque en los requisitos destacados en este documento.

Metadatos de integración de respuestas

Nombre

El Nombre debe corresponder al nombre del producto con el que se integrará la integración y no debe contener ningún carácter especial.

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 que se crea la integración, no se puede cambiar este valor. El identificador debe tener el mismo valor que Name, pero sin los 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 de alto nivel 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 tener 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 formato 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 SVG antes de agregarlo al archivo de definición de la integración, como se puede encontrar en otras integraciones en Content Hub.

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 a documentos 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 Auth), a menos que la API subyacente no requiera autenticación y la raíz de la API se pueda codificar de forma fija. Para 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 colocar 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, incluso si tu integración no tiene ninguna otra acción. Cada vez que el usuario presione el botón Probar dentro de la configuración de la integración, debería mostrarse un estado preciso de la conectividad.

Notas de la versión

La estructura general de la nota de la versión debe tener 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: 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, ocurre lo siguiente: {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: 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 contiene 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 de la integración.

Control de versiones

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

Etiquetas

De manera opcional, puedes agregar etiquetas a tu integración. Evita crear tipos de etiquetas nuevos; usa los que ya están en la plataforma. Si no ves una etiqueta que te convenga, consulta con el equipo de revisió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 más reciente compatible 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 entidad o Ejecutar búsqueda.

Si la acción está diseñada para funcionar principalmente con entidades, se prefiere colocar 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é tipo 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 asíncrono, 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 las acciones 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 de la secuencia de comandos 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 terminó de ejecutarse y realizó una operación, is_success debería ser true.

Resultado de la acción (resultado en JSON)

El resultado en JSON es el resultado más importante de la acción. Todos los datos disponibles en el resultado JSON serán accesibles durante la ejecución de la guía. 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 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 las guías:


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

En su lugar, dale 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",
       }
   }
]
    

Considera siempre 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 dentro del compilador de expresiones durante el proceso de creación de la guía. Una muestra de JSON precisa mejora significativamente la experiencia de creación de guías. Quita cualquier información de IIP 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 falla la acción. Cuando la acción falla, la guía correspondiente detendrá su ejecución hasta que el error se resuelva 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 falla y detiene 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 colocar todo el seguimiento de errores. En cambio, intenta dirigir al usuario al problema real en lenguaje natural.

Conectores

Nombre

El Nombre del conector debe dirigir al usuario a los datos que se transferirán. 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 qué ingerirá el 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:

  • Cantidad máxima de alertas que se recuperarán: Indica cuántos {object} se deben procesar durante 1 iteración del conector.
  • Máximo de {horas/días} hacia atrás: Dicta la hora de inicio en la primera iteración del conector. Por ejemplo, si el parámetro Max Hours Backwards se establece en 1, el conector comenzará a extraer datos de una hora antes.
  • Verificar SSL: Verifica la conectividad con la API o la instancia.

Asignación de ontología

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

La asignación de ontología se usa para crear entidades (IOC y recursos) de forma automática. 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. Tienes la flexibilidad de compilar cualquier lógica personalizada con ella, a la vez que tienes una UX única. El caso de uso más común es definir una lista de entidades permitidas o una lista de entidades bloqueadas para la transferencia.

Si estás creando una lógica personalizada para la lista dinámica, 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é hace este trabajo. 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 al usuario lo que 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 limitar la descripción a 500 caracteres.

Parámetros del trabajo

Los parámetros de configuración de trabajos 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 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:

  • Máximo de {horas/días} hacia atrás: Dicta la hora de inicio en la primera iteración del trabajo.
  • Verificar SSL: Verifica la conectividad con la API o la instancia.

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