API deGoogle Cloud
En este documento, se proporciona orientación para ayudarte a configurar e integrar la API deGoogle Cloud con Google Security Operations SOAR.
Versión de integración: 4.0
Integra la Google Cloud API con la plataforma SOAR de Google SecOps
La integración requiere los siguientes parámetros:
| Parámetros | Descripción |
|---|---|
Test URL |
Opcional Es una URL de prueba para validar la autenticación en la API de Google Cloud . Este parámetro usa una solicitud GET. |
Service Account Json File Content |
Opcional Es el contenido del archivo JSON de la clave de la cuenta de servicio. Puedes configurar este parámetro, el parámetro Para configurar este parámetro, proporciona el contenido completo del archivo JSON de la clave de la cuenta de servicio que descargaste cuando creaste una cuenta de servicio. Para obtener más información sobre el uso de cuentas de servicio como método de autenticación, consulta Descripción general de las cuentas de servicio y Uso de la identidad de cuentas de servicio. En esta integración, la autenticación con el archivo JSON de la clave de la cuenta de servicio tiene prioridad sobre el correo electrónico de Workload Identity. |
Organization ID |
Opcional Es el ID de la organización que se usará en la integración. Para recuperar el valor de este parámetro durante la ejecución de la acción, establece el siguiente marcador de posición: |
Project ID |
Opcional ID del proyecto que se usará en la integración. Para recuperar el valor de este parámetro durante la ejecución de la acción, establece el siguiente marcador de posición:
|
Quota Project ID |
Opcional El ID del proyecto Google Cloud que usas para las APIs y la facturación. Google Cloud Este parámetro requiere que otorgues el rol La integración adjunta este valor del parámetro a todas las solicitudes de la API. Si no estableces un valor para este parámetro, la integración recupera el ID del proyecto de tu cuenta de servicio Google Cloud . |
Workload Identity Email |
Opcional Es la dirección de correo electrónico del cliente de tu cuenta de servicio. Puedes configurar este parámetro o el parámetro En esta integración, la autenticación con el archivo JSON de la clave de la cuenta de servicio tiene prioridad sobre el correo electrónico de Workload Identity. Para actuar en nombre de cuentas de servicio con Workload Identity,
otorga el rol de |
OAuth Scopes |
Opcional Lista separada por comas de los permisos de OAuth que se requieren para ejecutar las solicitudes a la API de Google Cloud . |
Verify SSL |
Obligatorio Si se selecciona, la integración verifica que el certificado SSL para conectarse al servicio de Google Cloud sea válido. Esta opción está seleccionada de forma predeterminada. |
Si quieres obtener instrucciones para configurar una integración en Google SecOps, consulta Configura integraciones.
Si es necesario, puedes hacer cambios más adelante. Después de configurar una instancia de integración, puedes usarla en las guías. Para obtener más información sobre cómo configurar y admitir varias instancias, consulta Compatibilidad con varias instancias.
Acciones
Para obtener más información sobre las acciones, consulta Cómo responder a las acciones pendientes de Tu escritorio y Cómo realizar una acción manual.
Ejecutar solicitud HTTP
Usa la acción Ejecutar solicitud HTTP para construir y ejecutar una solicitud de API HTTP personalizada en una URL de destino.
Esta acción no se ejecuta en las entidades de SecOps de Google.
Comportamiento de la acción
Esta acción admite comportamientos complejos, como la sondeo asíncrono, la construcción de cargas útiles dinámicas y la administración de archivos.
Sondeo asíncrono
Cuando se proporciona Expected Response Values, la acción opera en modo asíncrono. En este modo, la acción sondea repetidamente el extremo de destino para hacer un seguimiento del estado de una respuesta (por ejemplo, espera a que se complete una tarea de larga duración).
La acción evalúa el cuerpo de la respuesta en función de las condiciones JSON proporcionadas en el parámetro y continúa la ejecución hasta que se cumplen las condiciones o la acción alcanza su tiempo de espera.
Lógica de condición
La acción admite la siguiente lógica para hacer un seguimiento de los estados de respuesta:
Coincidencia de un solo campo: La acción espera a que un campo específico alcance un solo valor.
{ "state": "finished" }Varios valores (lógica OR): La acción detiene la ejecución si un campo coincide con algún valor de una lista proporcionada. Esto es útil para detenerse en los estados "correcto" y "error" para evitar sondeos innecesarios.
{ "state": ["finished", "error"] }Varios campos (lógica AND): La acción espera hasta que todos los campos especificados coincidan con sus respectivos valores de forma simultánea.
{ "state": "finished", "percentage": "100" }Lógica combinada: Puedes combinar varias condiciones dentro del objeto JSON.
{ "state": ["finished", "error"], "percentage": "10" }
Comportamiento del análisis de JSON
Cuando evalúa las condiciones, la acción sigue estas reglas:
Búsqueda global: La acción busca las claves especificadas en todo el objeto de respuesta JSON. Proporciona el nombre de la clave exactamente como aparece en el JSON, sin anteponer nombres de objetos principales ni usar prefijos (por ejemplo, usa
"state", no"data_state"ni"data-state").Varias claves idénticas: Si la respuesta contiene varias claves con el mismo nombre en diferentes niveles de la jerarquía JSON, solo se alcanza el resultado esperado cuando todos los nombres de clave coincidentes satisfacen el valor esperado idéntico.
Por ejemplo, para buscar el estado
finisheden la respuesta JSON y omitir otros estados, configura todas las clavesstateenExpected Response Valuescomofinished:{ "data": { "state": "finished" }, "state": "finished" }
Construcción del cuerpo de la carga útil
La acción construye el cuerpo de la solicitud en función del encabezado Content-Type proporcionado en Headers.
Esta es la entrada Body Payload que se usa para los siguientes ejemplos de construcción:
{
"Id": "123123",
"sorting": "asc"
}
application/x-www-form-urlencoded: La acción genera la carga útil comoId=123123&sorting=asc.application/json: La acción genera la siguiente carga útil de JSON:{ "Id": "123123", "sorting": "asc" }XML: Si el producto de terceros requiere XML, proporciona una entrada con formato XML directamente enBody Payload:<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="[http://schemas.xmlsoap.org/soap/envelope/](http://schemas.xmlsoap.org/soap/envelope/)"> <soap:Body> <NumberToWords xmlns="[http://www.dataaccess.com/webservicesserver/](http://www.dataaccess.com/webservicesserver/)"> <ubiNum>500</ubiNum> </NumberToWords> </soap:Body> </soap:Envelope>
Manejo de archivos
La acción admite los siguientes flujos de trabajo para administrar archivos:
Descarga de archivos:
Para devolver los datos del archivo como parte del resultado JSON en formato base64, selecciona
Base64 Output.Para guardar un archivo directamente en el muro de casos como un archivo ZIP, selecciona
Save To Case Wall.
Subir archivos: Para subir un archivo, conviértelo en una cadena codificada en base64 y agrégalo como parte del valor de
Body Payload.En el siguiente ejemplo, se muestra un archivo de imagen convertido en una cadena codificada en base64:
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: Para archivos sensibles (como software malicioso), selecciona
Password Protect Zip. Esto encripta automáticamente el archivo ZIP guardado que se creó conSave To Case Wallcon la contraseñainfected.
Configuración del bloque de la guía
En la siguiente configuración, se muestra cómo usar la acción Ejecutar solicitud HTTP dentro de un bloque de playbook. Usa este ejemplo para comprender cómo aplicar marcadores de posición y prefijos de entrada.
Cuando uses entradas de bloques como marcadores de posición, debes incluir el prefijo Input. (por ejemplo, [Input.comment]).
Método:
PUTRuta de URL:
https://{API_URL}/[Input.table_name]/[Input.sys_id]Encabezados:
{ "Content-type": "application/json; charset=utf-8", "Accept": "application/json", "User-Agent": "GoogleSecops" }Carga útil del cuerpo:
{ "work_notes": "[Input.comment]" }
Entradas de acción
La acción Ejecutar solicitud HTTP requiere los siguientes parámetros:
| Parámetro | Descripción |
|---|---|
Method |
Opcional Es un método para usar en la solicitud. El valor predeterminado es
|
URL Path |
Opcional Es una URL para ejecutar. El valor predeterminado es |
URL Params |
Opcional Son los parámetros de URL. La acción usa cualquier valor proporcionado junto con los valores que proporcionaste directamente en el parámetro Ruta de URL. Este parámetro requiere el formato de objeto JSON como entrada. El valor predeterminado es el siguiente: {
"URL Field Name": "URL_FIELD_VALUE"
} |
Headers |
Opcional Encabezados que se usarán en la solicitud HTTP. Este parámetro requiere el formato de objeto JSON como entrada. El valor predeterminado es el siguiente: {
"Content-Type": "application/json; charset=utf-8",
"Accept": "application/json",
"User-Agent" : "GoogleSecOps"
} |
Cookie |
Opcional Son los parámetros que se usarán en el encabezado Este parámetro anula las cookies proporcionadas en el parámetro Headers. Este parámetro requiere el formato de objeto JSON como entrada. El valor predeterminado es el siguiente: {
"Cookie_1": "COOKIE_1_VALUE"
} |
|
Opcional
Es un cuerpo para la solicitud HTTP. La acción crea diferentes cargas útiles según el valor del encabezado Este parámetro requiere el formato de objeto JSON como entrada, excepto cuando un producto de terceros requiere XML o el contenido de El valor predeterminado es el siguiente: {
"Body Field Name": "BODY_FIELD_VALUE"
} |
Expected Response Values |
Opcional. Objeto JSON que contiene los pares campo-valor que definen el estado requerido del cuerpo de la respuesta. |
Save To Case Wall |
Opcional Si se selecciona, la acción guarda el archivo y lo adjunta al muro del caso. El archivo se archiva con la extensión No está seleccionado de forma predeterminada. |
Password Protect Zip |
Opcional Si se selecciona, la acción agrega una contraseña al archivo Usa este parámetro cuando trabajes con archivos sospechosos. Esta opción está seleccionada de forma predeterminada. |
Follow Redirects |
Opcional Si se selecciona, la acción sigue los redireccionamientos. Esta opción está seleccionada de forma predeterminada. |
Fail on 4xx/5xx |
Opcional Si se selecciona esta opción, la acción falla si el código de estado de la respuesta es un error 4xx o 5xx. Esta opción está seleccionada de forma predeterminada. |
Base64 Output |
Opcional Si se selecciona, la acción convierte la respuesta al formato base64. Usa este parámetro cuando descargues archivos. El resultado JSON no puede superar los 15 MB. No está seleccionado de forma predeterminada. |
Fields To Return |
Obligatorio Son los campos que se devolverán. Los valores posibles son los siguientes:
|
Request Timeout |
Obligatorio Es un período para esperar a que el servidor envíe datos antes de que falle la acción. El valor predeterminado es 120 segundos. |
Resultados de la acción
La acción Ejecutar solicitud HTTP proporciona los siguientes resultados:
| Tipo de salida de la acción | Disponibilidad |
|---|---|
| Adjunto del muro de casos | No disponible |
| Vínculo al muro de casos | No disponible |
| Tabla del muro de casos | No disponible |
| Tabla de enriquecimiento | No disponible |
| Resultado de JSON | Disponible |
| Mensajes de salida | Disponible |
| Resultado de secuencia de comandos | Disponible |
Resultado de JSON
En el siguiente ejemplo, se describe el resultado JSON que se recibe cuando se usa la acción Ejecutar solicitud HTTP:
{
"response_data": {
"data": {
"relationships": {
"comment": [
{
"name": "item",
"description": "Object to which the comment belongs to."
},
{
"name": "author",
"description": "User who wrote the comment."
}
]
}
}
},
"redirects": [],
"response_code": 200,
"cookies": {},
"response_headers": {
"Content-Type": "application/json",
"X-Cloud-Trace-Context": "VALUE",
"Date": "Fri, 03 Nov 2023 16:14:13 GMT",
"Server": "Google Frontend",
"Content-Length": "36084"
},
"apparent_encoding": "ascii"
}
Mensajes de salida
La acción Ejecutar solicitud HTTP proporciona los siguientes mensajes de salida:
| Mensaje de salida | Descripción del mensaje |
|---|---|
|
La acción se completó correctamente. |
Failed to execute API request. Error:
ERROR_REASON |
No se pudo realizar la acción. Verifica la conexión al servidor, los parámetros de entrada o las credenciales. |
Resultado de secuencia de comandos
En la siguiente tabla, se describen los valores del resultado de la secuencia de comandos cuando se usa la acción Ejecutar solicitud HTTP:
| Nombre del resultado de la secuencia de comandos | Valor |
|---|---|
is_success |
True o False |
Ping
Usa la acción Ping para probar la conectividad a Google Cloud.
Esta acción no se ejecuta en las entidades de SecOps de Google.
Entradas de acción
Ninguno
Resultados de la acción
La acción Ping proporciona los siguientes resultados:
| Tipo de salida de la acción | Disponibilidad |
|---|---|
| Adjunto del muro de casos | No disponible |
| Vínculo al muro de casos | No disponible |
| Tabla del muro de casos | No disponible |
| Tabla de enriquecimiento | No disponible |
| Resultado de JSON | Disponible |
| Mensajes de salida | Disponible |
| Resultado de secuencia de comandos | Disponible |
Resultado de JSON
En el siguiente ejemplo, se describe el resultado JSON que se recibe cuando se usa la acción Ping:
{
"endpoint": "TEST_URL"
}
Mensajes de salida
La acción Ping proporciona los siguientes mensajes de salida:
| Mensaje de salida | Descripción del mensaje |
|---|---|
Successfully tested connectivity. |
La acción se completó correctamente. |
Failed to test connectivity. |
No se pudo realizar la acción. Verifica la conexión al servidor, los parámetros de entrada o las credenciales. |
Resultado de secuencia de comandos
En la siguiente tabla, se describen los valores del resultado de la secuencia de comandos cuando se usa la acción Ping:
| Nombre del resultado de la secuencia de comandos | Valor |
|---|---|
is_success |
True o False |
¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.