TIPCommon.base

El módulo TIPCommon.base sirve como referencia técnica fundamental para el desarrollo de la integración dentro de Google SecOps, ya que proporciona lógica central para acciones, trabajos en segundo plano y normalización de datos multiplataforma.

Análisis de datos de acción

En esta sección, se incluyen funciones de utilidad necesarias para analizar los datos de casos de las respuestas sin procesar de la API y convertirlos en objetos estructurados para usarlos en tareas de automatización.

TIPCommon.base.action.action_parser.parse_case_attachment

TIPCommon.base.action.action_parser.parse_case_attachment(attachment: MutableMapping[str, Any]) → CaseAttachment

Esta utilidad convierte los datos adjuntos sin procesar de JSON de una respuesta de API en un objeto CaseAttachment estructurado.

Parámetros

Parámetros
attachment	Son los datos JSON sin procesar del adjunto, tal como se recuperaron de la respuesta de la API.

TIPCommon.base.action.action_parser.parse_case_comment

TIPCommon.base.action.action_parser.parse_case_comment(comment: MutableMapping[str, Any]) → CaseComment

Esta función analiza los datos sin procesar de los comentarios en formato JSON en un objeto CaseComment para facilitar el acceso a los metadatos de los comentarios.

Parámetros

Parámetros
comment	Son los datos JSON sin procesar del comentario, tal como se recuperaron de la respuesta de la API.

class TIPCommon.base.action.base_action.Action

clase TIPCommon.base.action.base_action.Action(name: str)

Bases: ABC, Generic[ApiClient]

La clase base Action proporciona una infraestructura unificada para el desarrollo de la automatización, incluida la administración de propiedades y los flujos de ejecución generales.

Advertencia: Esta clase requiere Python 3. No se admiten los entornos heredados de Python 2.

Parámetros

Parámetros
name	Es el identificador de la secuencia de comandos de la acción.

Atributos

Los siguientes atributos administran el estado interno de la acción y proporcionan acceso a los recursos del SDK y a los clientes de integración.

Atributos
_soar_action	SiemplifyAction Es el objeto del SDK de SiemplifyAction.
_api_client	Apiable Es el cliente de API de la integración.
_name	str Es el nombre de la secuencia de comandos que usa esta acción.
_action_start_time	int Es la hora de inicio de la acción en formato Unix.
_logger	SiemplifyLogger Es el objeto de registro que se usa para registrar acciones.
_params	Container Es el contenedor de parámetros de esta acción.
global_context	dict Es un diccionario para almacenar el contexto, si es necesario.
_entity_types	list[EntityTypesEnum] Son los tipos de entidades que admite la acción.
_entities_to_update	list[Entity] Son las entidades que se actualizarán cuando finalice la acción.
json_results	JSON Son los resultados en formato JSON de la acción.
_attachments	list[Attachment] Son los archivos adjuntos del resultado del caso que se agregarán.
_contents	list[Content] Es el contenido del resultado del caso que se agregará.
_data_tables	list[DataTable] Son las tablas de datos de resultados de casos que se agregarán.
_html_reports	list[HTMLReport] Informes HTML de los resultados del caso que se agregarán.
_links	list[Link] Son los vínculos de los resultados del caso que se agregarán.
_markdowns	list[Markdown] Son las reducciones de precios de los casos que se agregarán.
_entity_insights	list[EntityInsight] Son las estadísticas de la entidad del caso que se agregarán.
_case_insights	list[CaseInsight] Son las estadísticas del caso que se agregarán.
_execution_state	ExecutionState Es el indicador del estado de ejecución final de la acción.
_result_value	bool Es el valor del resultado final de la acción.
_output_message	str Es el mensaje de salida de la acción cuando se completa correctamente.
_error_output_message	str Es el mensaje de salida de la acción cuando falla.

Métodos

Son métodos estándar que se usan para administrar el ciclo de vida y el formato de salida de una secuencia de comandos de acción.

- run()	Ejecuta la acción.
- _get_adjusted_json_results()	Ajusta el resultado JSON a una estructura en particular.

Métodos abstractos

Los desarrolladores deben anular estos métodos para definir la lógica única de una acción personalizada.

Métodos abstractos
_validate_params()	Valida los parámetros de esta acción.
_init_api_clients()	Inicializa los clientes de la API de la acción.
_perform_action()	Realiza la lógica principal de la acción.

Métodos adicionales

Estos métodos opcionales se activan durante fases específicas del ciclo de vida de ejecución de la acción para controlar alertas o limpiar recursos.

• _get_entity_types()
• _finalize_action_on_success()
• _finalize_action_on_failure()
• _on_entity_failure()
• _handle_timeout()
• _extract_action_parameters()
• _finalize()

Métodos de wrapper del SDK

Estos métodos proporcionan un acceso conveniente al SDK subyacente, lo que permite que las acciones interactúen con casos, alertas y configuraciones de la plataforma.

• _add_attachment_to_current_case()
• _get_current_case_attachments()
• _add_comment_to_case()
• _get_current_case_comments()
• _assign_case_to_user()
• _add_tag_to_case()
• _attach_playbook_to_current_alert()
• _get_similar_cases_to_current_case()
• _get_alerts_ticket_ids_from_cases_closed_since_timestamp()
• _change_current_case_stage()
• _change_current_case_priority()
• _close_current_case()
• _close_alert()
• _escalate_case()
• _mark_case_as_important()
• _raise_incident()
• _add_entity_to_case()
• _update_alerts_additional_data()
• _get_current_integration_configuration()
• _any_alert_entities_in_custom_list()
• _add_alert_entities_to_custom_list()
• _remove_alert_entities_from_custom_list()

Ejemplo de implementación

En el siguiente ejemplo, se muestra cómo implementar una acción personalizada heredando de la clase base Action.

from TIPCommon.base.actions.action_base import Action
from TIPCommon.validation import ParameterValidator

SOME_ACTION_SCRIPT_NAME = 'Some Integration - Some Action'

class SomeAction(Action):

 def _validate_params(self) -> None:
 validator = ParameterValidator(self.soar_action)
 ... # validation logic

 def _perform_action(self, entity: Entity) -> None:
 try:
 self.logger.info('Querying Api client')
 data = self.api_client.do_something(
 param=self.params.query,
 entity=entity.original_identifier
 )

 ... # Some logic to process the data

 except SomeCustomException as err:
 self.error_output_message = (
 "Action wasn't able to successfully do its thing."

 )
 raise err from err


def main() -> None:
 SomeAction(SEARCH_GRAPHS_SCRIPT_NAME).run()


if __name__ == '__main__':
 main()

Propiedades

Las siguientes propiedades proporcionan acceso de solo lectura o administrado a los metadatos, los resultados y los objetos del SDK de la acción.

action_start_time

property action_start_time: int

Devuelve un objeto int que representa la hora de inicio de la acción en formato Unix.

api_client

property api_client: ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None

Devuelve un objeto Apiable que representa el cliente de API configurado para la integración.

archivos adjuntos

property attachments: list[Attachment]

Devuelve una lista de objetos Attachment que representan los archivos adjuntos del resultado del caso asociados con esta acción. Todos los archivos adjuntos de esta lista se envían al resultado del caso de forma predeterminada.

case_insights

property case_insights: list[CaseInsight]

Devuelve una lista de objetos CaseInsight que representan hallazgos de alto nivel asociados con esta acción. De forma predeterminada, todas las estadísticas del caso de esta lista se envían al resultado del caso.

 

property contents: list[Content]

Devuelve una lista de objetos Content que representan los resultados de texto para el caso. Todo el contenido de esta lista se envía al resultado del caso de forma predeterminada.

data_tables

property data_tables: list[DataTable]

Devuelve una lista de objetos DataTable que representan estadísticas de datos tabulares para el caso. De forma predeterminada, todas las tablas de datos de esta lista se envían al resultado del caso.

entities_to_update

property entities_to_update: list[DomainEntityInfo]

Devuelve una lista de objetos Entity que se actualizarán en la plataforma una vez que finalice la acción.

entity_insights

property entity_insights: list[EntityInsight]

Devuelve una lista de objetos EntityInsight que representan hallazgos vinculados a entidades específicas. De forma predeterminada, todas las estadísticas de la entidad en esta lista se envían al resultado del caso.

entity_types

property entity_types: list[EntityTypesEnum]

Devuelve una lista de objetos EntityTypesEnum que representan los tipos de entidades que la acción está diseñada para procesar. Si una acción se ejecuta en entidades, solo procesa los tipos que aparecen en esta lista.

error_output_message

property error_output_message: str

Obtiene o establece el mensaje que se muestra en la plataforma en caso de que falle la ejecución. El valor predeterminado es Action ACTION_NAME failed.

execution_state

property execution_state: ExecutionState

Devuelve un objeto ExecutionState que representa el indicador de estado de procesamiento final. Estos son los estados posibles:

• ExecutionState.COMPLETED = 0
• ExecutionState.IN_PROGRESS = 1
• ExecutionState.FAILED = 2
• ExecutionState.TIMED_OUT = 3

global_context

global_context: dict

Es un diccionario que se usa para almacenar y recuperar información de contexto durante la ejecución de la acción.

html_reports

property html_reports: list[HTMLReport]

Devuelve una lista de objetos HTMLReport que representan informes visuales para el resultado del caso. De forma predeterminada, todos los informes HTML de esta lista se envían al resultado del caso.

is_first_run

property is_first_run: bool

Devuelve true si esta es la ejecución inicial de la acción o false en caso contrario.

json_results

property json_results: Dict[str, Any] | List[Dict[str, Any]]

Devuelve el resultado en formato JSON para mostrarlo en el muro del caso y usarlo en la lógica del playbook posterior.

vínculos

property links: list[Link]

Devuelve una lista de objetos Link que representan URLs de referencia externas para el resultado del caso. De forma predeterminada, todos los vínculos de esta lista se envían al resultado del caso.

logger

property logger: NewLineLogger

Devuelve la instancia de NewLineLogger que se usa para el registro específico de la secuencia de comandos.

markdowns

property markdowns: list[Markdown]

Devuelve una lista de objetos Markdown que representan estadísticas de texto con formato. De forma predeterminada, todos los elementos de Markdown de esta lista se envían al resultado del caso.

nombre

property name: str

Devuelve el nombre de cadena de la secuencia de comandos de la acción.

output_message

property output_message: str

Obtiene o establece el mensaje que se muestra en la plataforma y que resume la ejecución correcta de una acción.

params

property params: Container

Devuelve un objeto Container que describe los parámetros de entrada de la acción, con cada parámetro expuesto como un atributo snake_case.

result_value

property result_value: bool

Obtiene o establece el indicador de éxito que se devuelve a la plataforma.

• True: La acción se completó correctamente.
• False: No se pudo realizar la acción.

run

run(**kwargs)

Es el método estándar para activar la lógica de ejecución de la acción.

soar_action

property soar_action: SiemplifyAction

Devuelve el objeto SiemplifyAction del SDK subyacente que se usa para la interacción directa con la plataforma.

class TIPCommon.base.action.base_enrich_action.EnrichAction

clase TIPCommon.base.action.base_enrich_action.EnrichAction(name: str)

Bases: Action

EnrichAction es una clase base especializada diseñada para acciones que actualizan propiedades de entidades con datos externos.

Parámetros

Se requiere el siguiente parámetro para inicializar la acción de enriquecimiento y registrarla en la plataforma.

Parámetros
name	Es el identificador único del script de la acción de enriquecimiento.

Atributos

Los siguientes atributos administran los datos que se usan durante las iteraciones de entidades y definen el contenido incluido en los resultados de salida de la acción.

Atributos
enrichment_data	dict Son los datos de enriquecimiento de la entidad actual en cada una de las iteraciones de la entidad. Al final de cada iteración, el atributo additional_properties de la entidad se actualiza con self.enrichment_data, lo que significa que este valor se establece cada vez con el valor nuevo.
entity_results	Any Son los resultados de la entidad incluidos en el resultado JSON de este objeto.
global_context	dict Es un diccionario que se usa para almacenar y compartir datos de contexto en diferentes fases de la ejecución de la acción de enriquecimiento.

Métodos abstractos

Los siguientes métodos abstractos se deben implementar en las subclases para definir los tipos de entidades específicos y la lógica de enriquecimiento de la acción.

Métodos abstractos
_get_entity_types()	Obtiene el tipo de entidades en las que se ejecuta la acción.
_perform_enrich_action()	Realiza la lógica de enriquecimiento principal en una entidad.

Métodos privados

Estos métodos internos controlan la organización de la lógica de enriquecimiento y no se deben modificar.

Métodos privados
_perform_action()	Este método combina los otros métodos abstractos con más lógica de enriquecimiento lista para usar y la pasa a la clase principal para usarla en el método start(). Advertencia: No anules este método.

Módulo Data Models

Este módulo proporciona definiciones estructuradas para objetos, enumeraciones y constantes de integración cruzada.

class TIPCommon.base.action.data_models.ActionParamType

clase TIPCommon.base.action.data_models.ActionParamType(value)

Bases: Enum

ActionParamType define los tipos de datos de la IU admitidos para los parámetros de la secuencia de comandos de acción.

Constantes

Constante	Valor
BOOLEAN	1
CASE_PRIORITIES	7
CLOSE_CASE_REASONS	5
CLOSE_ROOT_CAUSE	6
CODE	20
CONTENT	11
DDL	15
EMAIL_CONTENT	10
ENTITY_TYPE	13
MULTI_VALUES	14
NULL	-1
PASSWORD	12
PLAYBOOK_NAME	2
STAGE	4
STRING	0
USER	3

class TIPCommon.base.action.data_models.Attachment

clase TIPCommon.base.action.data_models.Attachment(filename: str, file_contents: bytes, title: str = 'Script Result Attachment', additional_data: dict | None = None)

Bases: object

Este modelo representa un archivo adjunto de resultado de secuencia de comandos para subir al muro del caso.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Parámetros

Se requieren los siguientes parámetros para inicializar un objeto adjunto, definir sus metadatos y los datos binarios que se subirán al caso.

Parámetros
filename	Nombre del archivo que se creará dentro de los resultados del caso.
file_contents	Son los datos binarios sin procesar que representan el contenido del archivo.
title	Es el título visible del adjunto tal como aparece en la IU de la plataforma. El valor predeterminado es 'Script Result Attachment'.

Atributos

Los siguientes atributos definen los metadatos y el contenido binario del archivo adjunto que genera la secuencia de comandos de acción.

Atributos
title	str | None Es el título del archivo adjunto que se muestra en la interfaz de la plataforma.
filename	str Nombre específico del archivo que se creará.
file_contents	bytes Es el contenido binario sin procesar del archivo adjunto.
additional_data	dict | None Es un diccionario que contiene datos complementarios asociados con el adjunto.

class TIPCommon.base.action.data_models.CaseAttachment

clase TIPCommon.base.action.data_models.CaseAttachment(attachment_id: int, attachment_type: str, description: str, is_favorite: bool)

Bases: object

Esta clase representa un adjunto inmutable asociado a un caso.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos representan los metadatos específicos de un adjunto que ya se asoció con un caso en la plataforma.

Atributos
attachment_id	int Es el identificador único asignado por la plataforma para el archivo adjunto.
attachment_type	str Es la clasificación o el tipo de MIME del adjunto (por ejemplo, txt, csv o json).
description	str Es una descripción del contenido del adjunto definida por el usuario o generada por el sistema.
is_favorite	bool Indica si el adjunto se marcó como favorito para acceder rápidamente a él en el muro del caso.

class TIPCommon.base.action.data_models.CaseComment

clase TIPCommon.base.action.data_models.CaseComment(comment: str, creator_user_id: str, comment_id: int, comment_type: int, case_id: int, is_favorite: bool, modification_time_unix_time_in_ms: int, creation_time_unix_time_in_ms: int, alert_identifier: str, creator_full_name: str | None = None, is_deleted: bool | None = None, last_editor: str | None = None, last_editor_full_name: str | None = None, modification_time_unix_time_in_ms_for_client: int | None = None, comment_for_client: str | None = None)

Bases: object

CaseComment representa un registro inmutable de un comentario asociado a un caso o una alerta, que captura los detalles del creador y las marcas de tiempo de auditoría.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos definen los metadatos administrativos y de contenido de un comentario del caso.

Atributos
comment	str Es el contenido de texto principal del comentario.
comment_for_client	str | None Es una versión opcional del comentario adaptada para la visibilidad del cliente.
modification_time_unix_time_in_ms_for_client	int Es la marca de tiempo de modificación del comment_for_client en milisegundos Unix.
last_editor	str ID del último editor, como 77bdb7a4-8484-481d-9482-2449e33f9518.
last_editor_full_name	str Es el nombre visible completo del usuario que editó el comentario por última vez, como admin admin.
is_deleted	bool Indica si el comentario se marcó como borrado.
creator_user_id	str ID de usuario del creador, como 77bdb7a4-8484-481d-9482-2449e33f9518.
creator_full_name	str Nombre visible completo del creador, como System.
comment_id	int Es el identificador único asignado por la plataforma para el comentario.
comment_type	int Es la clasificación del tipo de comentario.
case_id	int Es el ID del caso asociado con este comentario.
is_favorite	bool Indica si el comentario está fijado como favorito.
modification_time_unix_time_in_ms	int Es la hora de la última modificación del comentario en milisegundos de Unix, como 1686040471269.
creation_time_unix_time_in_ms	int Es la fecha y hora de creación del comentario en milisegundos de Unix, como 1686040471269.
alert_identifier	str Es el identificador específico de la alerta relacionada con el comentario, como SUSPICIOUS PHISHING EMAIL_83765943-9437-4771-96F6-BD0FB291384E.

class TIPCommon.base.action.data_models.CaseInsight

clase TIPCommon.base.action.data_models.CaseInsight(triggered_by: str, title: str, content: str, severity: InsightSeverity, insight_type: InsightType, entity_identifier: str = '', additional_data: Any | None = None, additional_data_type: Any | None = None, additional_data_title: str | None = None)

Bases: object

CaseInsight representa un resumen estructurado inmutable de un hallazgo o una alerta que se muestra en el muro del caso.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos administran cómo se categorizan y presentan las estadísticas a los analistas dentro de la plataforma.

Atributos
title	str Es el título que se muestra para la estadística en el muro de casos.
triggered_by	str Es el nombre de la integración o el usuario que generó la estadística.
content	str Es el cuerpo del mensaje detallado o el hallazgo de la estadística.
severity	InsightSeverity Es el nivel de urgencia de la estadística. Los valores posibles son los siguientes: info warning error
insight_type	InsightType Categoriza la estadística. Los valores posibles son los siguientes: general entity
entity_identifier	str | None Es el identificador específico de una entidad si la estadística se centra en la entidad.
additional_data	Any | None Son los datos complementarios asociados con la estadística.
additional_data_type	Any | None Es la clasificación del tipo de datos para el atributo additional_data.
additional_data_title	str | None Es el título visible del bloque de datos complementarios.

class TIPCommon.base.action.data_models.CasePriority

clase TIPCommon.base.action.data_models.CasePriority(value)

Bases: Enum

CasePriority define los niveles de gravedad basados en números enteros que se asignan a los casos dentro de la plataforma.

Constantes

Constante	Valor
CRITICAL	100
HIGH	80
INFORMATIONAL	0
LOW	40
MEDIUM	60

class TIPCommon.base.action.data_models.CaseStage

clase TIPCommon.base.action.data_models.CaseStage(value)

Bases: Enum

CaseStage especifica las fases operativas por las que puede pasar un caso durante su ciclo de vida.

Constantes

Constante	Valor
ASSESSMENT	'Assessment'
IMPROVEMENT	"Mejora"
INCIDENT	"Incidente"
INVESTIGATION	Investigación
RESEARCH	Investigación
TRIAGE	'Triaje'

class TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses

clase TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses(value)

Bases: Enum

CloseCaseOrAlertInconclusiveRootCauses proporciona opciones de causa raíz para situaciones en las que no se puede realizar una determinación definitiva.

Constantes

Constante	Valor
NO_CLEAR_CONCLUSION	"Sin conclusiones claras"

class TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses

clase TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses(value)

Bases: Enum

CloseCaseOrAlertMaintenanceRootCauses define las causas raíz relacionadas con las pruebas programadas, el mantenimiento del sistema o el desarrollo de reglas.

Constantes

Constante	Valor
LAB_TEST	"Prueba de laboratorio"
OTHER	Otro
RULE_UNDER_CONSTRUCTION	“Regla en construcción”

class TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses

clase TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CloseCaseOrAlertMaliciousRootCauses proporciona categorías específicas para amenazas confirmadas, problemas de infraestructura o fallas del sistema.

Constantes

Constante	Valor
EXTERNAL_ATTACK	"Ataque externo"
INFRASTRUCTURE_ISSUE	Problema de infraestructura
IRRELEVANT_TCP_UDP_PORT	"Puerto TCP/UDP irrelevante"
MISCONFIGURED_SYSTEM	“Sistema mal configurado”
OTHER	Otro
SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION	"Ya se está investigando un caso similar"
SYSTEM_APPLICATION_MALFUNCTION	"Falla del sistema o de la aplicación"
SYSTEM_CLOCKED_THE_ATTACK	"El sistema bloqueó el ataque"
UNFORESEEN_EFFECTS_OF_CHANGE	"Efectos imprevistos del cambio"
UNKNOWN	'Unknown'

class TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses

clase TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CloseCaseOrAlertNotMaliciousRootCauses define categorías para actividades benignas, acciones legítimas o errores que no representan una amenaza.

Constantes

Constante	Valor
EMPLOYEE_ERROR	“Error del empleado”
HUMAN_ERROR	"Error humano"
LAB_TEST	"Prueba de laboratorio"
LEGIT_ACTION	"Acción legítima"
MISCONFIGURED_SYSTEM	“Sistema mal configurado”
NONE	"Ninguno"
NORMAL_BEHAVIOR	"Comportamiento normal"
OTHER	Otro
PENETRATION_TEST	"Prueba de penetración"
RULE_UNDER_CONSTRUCTION	“Regla en construcción”
SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION	"Ya se está investigando un caso similar"
UNKNOWN	'Unknown'
USER_MISTAKE	“Error del usuario”

class TIPCommon.base.action.data_models.CloseCaseOrAlertReasons

clase TIPCommon.base.action.data_models.CloseCaseOrAlertReasons(value)

Bases: Enum

CloseCaseOrAlertReasons proporciona categorías estandarizadas de alto nivel sobre por qué se cierra un caso o una alerta.

Constantes

Constante	Valor
MALICIOUS	0
NOT_MALICIOUS	1
MAINTENANCE	2
INCONCLUSIVE	3

class TIPCommon.base.action.data_models.Content

clase TIPCommon.base.action.data_models.Content(content: str, title: str = 'Script Result Content')

Bases: object

Content representa un resultado de texto inmutable generado por una secuencia de comandos para agregar al muro del caso.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos definen el contenido textual o basado en Markdown que se muestra en los resultados de los casos en la plataforma.

Atributos
title	str | None Es el título visible del bloque de contenido tal como aparece en la IU de resultados de la secuencia de comandos.
content	str Es el contenido principal del mensaje, que se puede proporcionar como una cadena de texto sin procesar o con formato de Markdown.

class TIPCommon.base.action.data_models.DataTable

clase TIPCommon.base.action.data_models.DataTable(data_table: list[str], title: str = 'Script Result Data Table')

Bases: object

DataTable representa una lista de cadenas con formato CSV que se renderizan como una tabla estructurada en los resultados de la búsqueda.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos definen la estructura y la visualización de los datos tabulares dentro del conjunto de resultados de la acción.

Atributos
title	str | None Es el encabezado que se muestra sobre la tabla de datos en la interfaz de la plataforma.
data_table	list[str] Es una lista de cadenas en la que cada elemento representa una fila con formato CSV que construye la tabla.

class TIPCommon.base.action.data_models.EntityInsight

clase TIPCommon.base.action.data_models.EntityInsight(entity: DomainEntityInfo, message: str, triggered_by: str | None = None, original_requesting_user: str | None = None)

Bases: object

EntityInsight se usa para crear hallazgos específicos asociados a una entidad, que suelen mostrarse en la vista de detalles de la entidad.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Los siguientes atributos definen la relación entre una entidad y los hallazgos que genera una secuencia de comandos de integración.

Atributos
entity	Entity Es el objeto de entidad que se enriquece con hallazgos nuevos.
message	str Es la observación, el hallazgo o el mensaje descriptivo principal de la entidad.
triggered_by	str | None Es el nombre de la integración que identificó el hallazgo.
original_requesting_user	str | None Es el identificador único del usuario que inició la solicitud originalmente.

class TIPCommon.base.action.data_models.EntityTypesEnum

clase TIPCommon.base.action.data_models.EntityTypesEnum(value)

Bases: Enum

EntityTypesEnum proporciona constantes para todos los tipos de entidades que reconoce Google SecOps.

Constantes

Las siguientes constantes definen los tipos de entidades estandarizados que admite la plataforma para las tareas de enriquecimiento y automatización.

Constante	Valor
ADDRESS	'ADDRESS'
ALERT	'ALERT'
APPLICATION	'APPLICATION'
CHILD_HASH	'CHILDHASH'
CHILD_PROCESS	'CHILDPROCESS'
CLUSTER	'CLUSTER'
CONTAINER	'CONTAINER'
CREDIT_CARD	'CREDITCARD'
CVE	"CVE"
CVE_ID	'CVEID'
DATABASE	'DATABASE'
DEPLOYMENT	“DEPLOYMENT”
DESTINATION_DOMAIN	'DESTINATIONDOMAIN'
DOMAIN	'DOMAIN'
EMAIL_MESSAGE	'EMAILSUBJECT'
EVENT	'EVENT'
FILE_HASH	'FILEHASH'
FILE_NAME	'FILENAME'
GENERIC	'GENERICENTITY'
HOST_NAME	"HOSTNAME"
IP_SET	"IPSET"
MAC_ADDRESS	"MacAddress"
PARENT_HASH	'PARENTHASH'
PARENT_PROCESS	'PARENTPROCESS'
PHONE_NUMBER	'PHONENUMBER'
POD	'POD'
PROCESS	'PROCESS'
SERVICE	'SERVICE'
SOURCE_DOMAIN	'SOURCEDOMAIN'
THREAT_ACTOR	'THREATACTOR'
THREAT_CAMPAIGN	'THREATCAMPAIGN'
THREAT_SIGNATURE	'THREATSIGNATURE'
URL	'DestinationURL'
USB	"USB"
USER	'USERUNIQNAME'

class TIPCommon.base.action.data_models.ExecutionState

clase TIPCommon.base.action.data_models.ExecutionState(value)

Bases: Enum

ExecutionState representa el indicador de estado final que se devuelve a la plataforma para determinar el éxito o el fracaso de una acción.

Constantes

Constante	Valor
COMPLETED	0
IN_PROGRESS	1
FAILED	2
TIMED_OUT	3

class TIPCommon.base.action.data_models.FullDetailsConfigurationParameter

clase TIPCommon.base.action.data_models.FullDetailsConfigurationParameter(input_dict: dict[str, Any])

Bases: object

FullDetailsConfigurationParameter encapsula un parámetro de configuración de integración general con sus metadatos completos recuperados de la API.

Atributos

Los siguientes atributos administran los metadatos, la identificación y las restricciones de configuración de los parámetros.

table> Atributos full_dict

dict[str, Any]

Es el diccionario original que se recibió de la respuesta de la API.

id

int | None

Es el identificador único asignado por la plataforma para el parámetro.

integration_identifier

str

Es el identificador de la integración asociada a este parámetro, como VirusTotalV3.

creation_time

int

Es la marca de tiempo que indica cuándo se creó el parámetro, en milisegundos de Unix.

modification_time

int

Es la marca de tiempo que indica cuándo se modificó el parámetro por última vez, en milisegundos de Unix.

is_mandatory

bool

Define si el parámetro es obligatorio para la función de integración.

description

str | None

Es la descripción detallada del propósito del parámetro.

name

str

Es el nombre del identificador interno del parámetro.

display_name

str

Es el nombre del parámetro legible por humanos que se muestra en la interfaz de la plataforma.

value

Any

Es el valor predeterminado asignado al parámetro.

type

IntegrationParamType

Es la clasificación del tipo de datos del parámetro.

optional_values

list

Es una lista de valores opcionales proporcionados para los tipos de parámetros de lista desplegable (DDL).

class TIPCommon.base.action.data_models.HTMLReport

clase TIPCommon.base.action.data_models.HTMLReport(report_name: str, report_contents: str, ...)

Bases: object

HTMLReport representa una visualización personalizada basada en HTML que se puede agregar a los resultados del caso.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Atributos
title	str | None Es el título visible del informe en el muro del caso.
report_name	str Es el identificador interno o el nombre de archivo del informe.
report_contents	str Es la cadena HTML sin procesar que define el contenido del informe.

class TIPCommon.base.action.data_models.IntegrationParamType

clase TIPCommon.base.action.data_models.IntegrationParamType(value)

Bases: Enum

IntegrationParamType especifica los tipos de datos admitidos para la configuración de la integración.

Constantes

Constante	Valor
NULL	-1
BOOLEAN	0
INTEGER	1
STRING	2
PASSWORD	3
IP	4
EMAIL	8

class TIPCommon.base.action.data_models.Link

clase TIPCommon.base.action.data_models.Link(link: str, title: str = 'Script Result Link')

Bases: object

Link representa un resultado de URL externa que se mostrará como un hipervínculo en el muro de casos.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hashing (se almacena en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Atributos
title	str | None Es el texto visible del hipervínculo.
link	str Es la URL de destino del vínculo.

class TIPCommon.base.action.data_models.Markdown

clase TIPCommon.base.action.data_models.Markdown(markdown_name: str, markdown_content: str, ...)

Bases: object

Markdown proporciona una forma estructurada de devolver contenido con formato de texto enriquecido usando la sintaxis de Markdown.

Nota: Esta clase es inmutable. Después de asignar valores y crear el objeto, no se pueden asignar valores nuevos a los atributos. La clase admite el hash (almacenado en un conjunto o como clave de diccionario) y el operador ==.

Atributos

Atributos
title	str | None Es el título visible del bloque de Markdown.
markdown_content	str Es el contenido formateado en sintaxis de Markdown.
markdown_name	str Es el nombre único asignado a este resultado de Markdown.

class TIPCommon.base.action.data_models.ScriptParameter

clase TIPCommon.base.action.data_models.ScriptParameter(input_dict: dict[str, Any])

Bases: object

ScriptParameter representa un solo parámetro de entrada para una secuencia de comandos de acción, y administra su valor, estado predeterminado y visibilidad dentro de los cuadernos de estrategias o las acciones manuales.

Atributos

Los siguientes atributos administran los metadatos, la priorización de valores y las restricciones de datos para los parámetros de secuencias de comandos individuales.

Atributos
full_dict	dict[str, Any] Es el diccionario original que se recibió de la respuesta de la API.
id	int | None Es el identificador único asignado por la plataforma para el parámetro.
creation_time	int Es la marca de tiempo que indica cuándo se creó el parámetro, en milisegundos de Unix.
modification_time	int Es la marca de tiempo que indica cuándo se modificó el parámetro por última vez, en milisegundos de Unix.
custom_action_id	int | None Es el identificador de la acción personalizada asociada con este parámetro.
is_mandatory	bool Indica si se debe proporcionar el parámetro para que se ejecute la secuencia de comandos de acción.
default_value	Any Es el valor predeterminado del parámetro. Este valor tiene prioridad sobre value en las ejecuciones de la guía.
description	str | None Es la descripción detallada del propósito del parámetro.
name	str | None Es el nombre del identificador interno del parámetro.
value	Any Es el valor actual del parámetro. Este valor tiene prioridad sobre default_value en las ejecuciones de acciones manuales.
type	ActionParamType Es la clasificación del tipo de datos del parámetro.
optional_values	list Es una lista de valores opcionales que se proporcionan para los tipos de parámetros de lista desplegable (DDL).

Resultados de la ejecución de la secuencia de comandos

Las siguientes clases y funciones definen las estructuras estandarizadas para devolver datos de acciones y conectores a la plataforma.

class TIPCommon.base.data_models.ActionJsonOutput

clase TIPCommon.base.data_models.ActionJsonOutput(title='JsonResult', content='', type=None, is_for_entity=False, json_result=None)

Bases: object

ActionJsonOutput representa la carga útil JSON estructurada para una acción, lo que permite una categorización específica y una segmentación a nivel de la entidad.

Atributos

Atributos
title	str Es el título visible del bloque de resultados JSON.
content	str Es el contenido textual o un resumen que acompaña a los datos JSON.
type	str | None Es un tipo de clasificación opcional para el resultado en formato JSON.
is_for_entity	bool Indica si el resultado JSON está asociado específicamente con una entidad.
json_result	JSON | None Es la carga útil de datos JSON estructurados real.

class TIPCommon.base.data_models.ActionOutput

clase TIPCommon.base.data_models.ActionOutput(output_message, result_value, execution_state, json_output, debug_output='')

Bases: object

ActionOutput encapsula la estructura de resultado completa para una acción, combinando mensajes legibles, estado y JSON estructurado.

Atributos

Atributos
output_message	str Es el mensaje de resumen principal que se muestra al analista.
result_value	str | bool Es el resultado lógico de la acción (p.ej., éxito o falla).
execution_state	ExecutionState Es el estado final del ciclo de vida de la ejecución de la acción.
json_output	ActionJsonOutput | None Son los resultados estructurados en formato JSON de la acción.
debug_output	str Es información de diagnóstico opcional para solucionar problemas.

class TIPCommon.base.data_models.ConnectorJsonOutput

clase TIPCommon.base.data_models.ConnectorJsonOutput(alerts, overflow_alerts=<factory>, log_items=<factory>, log_rows=<factory>, variables=<factory>)

Bases: object

ConnectorJsonOutput define los datos estructurados que devuelve un conector, incluidas las alertas incorporadas, los detalles de desbordamiento y los registros de ejecución.

Atributos

Atributos
alerts	list[AlertInfo | CaseInfo] Es una lista de objetos de alertas o casos transferidos correctamente.
overflow_alerts	list[OverflowAlertDetails] Es una lista de alertas que superaron los límites de transferencia y se controlaron como desbordamiento.
log_items	list Es una lista de entradas de registro estructuradas que se generaron durante la ejecución del conector.
variables	dict Es un diccionario de variables de estado que se conservan entre las ejecuciones del conector.

class TIPCommon.base.data_models.ConnectorOutput

clase TIPCommon.base.data_models.ConnectorOutput(json_output, debug_output='')

Bases: object

ConnectorOutput representa el contenedor de nivel superior para los resultados de la ejecución del conector, que encapsula los datos JSON estructurados y las cadenas de depuración opcionales.

Atributos

Atributos
json_output	ConnectorJsonOutput | None Son los resultados JSON estructurados que contienen datos de registro y de transferencia.
debug_output	str Es una cadena de depuración opcional para el seguimiento de diagnóstico interno.

TIPCommon.base.data_models.alert_info_from_json

TIPCommon.base.data_models.alert_info_from_json(json_) → AlertInfo

Crea un objeto AlertInfo analizando un diccionario de atributos. Por lo general, se usa para reconstruir objetos de alerta durante la transformación o las pruebas de datos.

Devoluciones

Devuelve un objeto AlertInfo completamente inicializado según las propiedades definidas en el diccionario JSON proporcionado.

Módulo Interfaces

Este módulo define contratos abstractos estándar para los componentes de secuencias de comandos fundamentales.

class TIPCommon.base.interfaces.apiable.Apiable

clase TIPCommon.base.interfaces.apiable.Apiable(authenticated_session: AuthenticatedSession, configuration: ApiParams)

Bases: ABC, Generic[ApiParams]

Apiable es una interfaz base abstracta para las clases que encapsulan la lógica de comunicación de la API, lo que garantiza una estructura coherente para las interacciones con servicios externos.

class TIPCommon.base.interfaces.authable.Authable

clase TIPCommon.base.interfaces.authable.Authable

Bases: ABC, Generic[AuthParams]

Authable es una interfaz base abstracta para las clases que administran flujos de trabajo de autenticación, y proporciona un esquema estandarizado para establecer sesiones seguras con servicios externos.

Métodos abstractos

Los siguientes métodos abstractos se deben implementar en las subclases para definir la lógica de autenticación específica que requiere el servicio de destino.

Métodos abstractos
authenticate_session()	authenticate_session(params: AuthParams) → None Autentica el atributo self.session con el params proporcionado (como dataclass, TypedDict o namedtuple). Usa este método para establecer la autenticación con el servicio asociado a la sesión después de que se haya inicializado el objeto de sesión.

class TIPCommon.base.interfaces.logger.Logger

clase TIPCommon.base.interfaces.logger.Logger

Bases: ABC

La interfaz Logger garantiza que las secuencias de comandos del mercado proporcionen resultados de diagnóstico estandarizados.

Métodos abstractos

Se deben implementar los siguientes métodos para controlar varios niveles de gravedad de registro y la generación de informes de excepciones.

Métodos abstractos
debug()	debug(msg: str, *args, **kwargs) → None Registra un mensaje con el nivel de gravedad DEBUG.
info()	info(msg: str, *args, **kwargs) → None Registra un mensaje con el nivel de gravedad INFO.
warn()	warn(warning_msg: str, *args, **kwargs) → None Registra un mensaje con el nivel de gravedad WARNING.
error()	error(error_msg: str, *args, **kwargs) → None Registra un mensaje con el nivel de gravedad ERROR.
exception()	exception(ex: Exception, *args, **kwargs) → None Registra un mensaje con el nivel de gravedad ERROR, incluido el seguimiento de pila de la excepción.

class TIPCommon.base.interfaces.session.Session

clase TIPCommon.base.interfaces.session.Session

Bases: ABC, Generic[_R]

La interfaz Session proporciona un esquema coherente para administrar sesiones de API con varias bibliotecas HTTP.

Atributos

Los siguientes atributos administran la configuración y los parámetros de seguridad de la sesión de comunicación HTTP establecida.

Atributos
headers	dict Es un diccionario que contiene los encabezados HTTP que se enviarán con cada solicitud de la sesión.
verify	bool Es un valor booleano que indica si la sesión debe verificar el certificado SSL del servidor.

Métodos abstractos

Los siguientes métodos abstractos definen los verbos HTTP estándar y el distribuidor de solicitudes principal que deben implementar las subclases.

Métodos abstractos
get()	get(url: str, *args, **kwargs) → _R Recupera un recurso del servidor con una solicitud GET de HTTP.
post()	post(url: str, *args, **kwargs) → _R Envía datos al servidor para crear un recurso con una solicitud HTTP POST.
put()	put(url: str, *args, **kwargs) → _R Actualiza o crea un recurso en el servidor con una solicitud HTTP PUT.
patch()	patch(url: str, *args, **kwargs) → _R Aplica modificaciones parciales a un recurso con una solicitud HTTP PATCH.
delete()	delete(url: str, *args, **kwargs) → _R Quita un recurso especificado del servidor con una solicitud HTTP DELETE.
request()	request(method: str, *args, **kwargs) → _R Es el despachador de solicitudes principal que se usa para realizar una solicitud HTTP con un método especificado.

Módulo de empleos

Esto proporciona el framework para las secuencias de comandos de procesamiento en segundo plano que se ejecutan según un programa definido dentro de la plataforma.

class TIPCommon.base.job.base_job.Job

clase TIPCommon.base.job.base_job.Job(name: str)

Bases: ABC, Generic[ApiClient]

Job es una clase base abstracta diseñada para tareas programadas que realizan operaciones independientes en segundo plano, como la sincronización de datos o las verificaciones de estado.

Parámetros

El siguiente parámetro es obligatorio para inicializar el trabajo y registrarlo en la plataforma.

Parámetros
name	Es el identificador único que se usa para registrar e identificar el script de trabajo.

Atributos

Las siguientes propiedades proporcionan acceso al contexto de ejecución, la configuración y los clientes de servicios integrados del trabajo.

Atributos
api_client	ApiClient | None Proporciona el cliente de API inicializado o la colección de clientes para interactuar con servicios externos.
error_msg	str Almacena los mensajes de error que se encontraron durante la ejecución del trabajo para generar informes de diagnóstico.
job_start_time	int Es la marca de tiempo de Unix que representa el momento en que comenzó la ejecución del trabajo.
logger	ScriptLogger Proporciona la interfaz de registro para capturar datos informativos, de advertencia y de error durante la ejecución.
name	str Es el nombre registrado de la secuencia de comandos del trabajo.
params	Container Es un contenedor que contiene los parámetros de configuración específicos proporcionados a la instancia del trabajo.
soar_job	SiemplifyJob Representa la instancia de trabajo de la plataforma subyacente y proporciona acceso a hooks de ejecución de bajo nivel.

Métodos

Los siguientes métodos administran la organización y el ciclo de vida de ejecución del trabajo.

Métodos
start()	Firma: start(**kwargs) → None Es el punto de entrada principal que activa la lógica de ejecución del trabajo.

class TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob

clase TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob(name: str, integration_identifier: str)

Bases: Job, Generic[ApiClient]

RefreshTokenRenewalJob proporciona los métodos de ciclo de vida que influyen en el procesamiento de trabajos para el mantenimiento de tokens. No es necesario que las subclases anulen estos métodos.

Atributos

Atributos
api_client	ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None Es el cliente o los clientes de API inicializados que se usan para las interacciones con servicios externos.

class TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

clase TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple(success_list, failure_list)

Bases: tuple

SuccessFailureTuple es una tupla con nombre especializada que se usa para categorizar los resultados de las operaciones de trabajo por lotes en éxitos y errores.

Atributos

Atributos
success_list	list Es una lista que contiene los identificadores o los objetos que se procesaron correctamente.
failure_list	list Es una lista que contiene los identificadores o los objetos que no se pudieron procesar.

TIPCommon.base.job.base_job_refresh_token.validate_param_csv_to_multi_value

TIPCommon.base.job.base_job_refresh_token.validate_param_csv_to_multi_value(param_name, param_csv_value, delimiter=',') → list[str]

Esta función valida y analiza una cadena de parámetros separados por comas (CSV) en una lista de elementos únicos. Está diseñado para controlar formatos complejos, incluidos valores únicos, cadenas entre comillas y entradas mixtas.

Parámetros

Parámetros
param_name	str Es el nombre o la clave del parámetro que se valida.
param_csv_value	str | None Es la cadena CSV sin procesar que se proporciona en la configuración del trabajo. Devuelve una lista vacía si es None.

Se genera el error

Se genera una excepción ValueError si la cadena de entrada contiene una cantidad no válida de comillas dobles, comillas que no coinciden o si algún valor individual dentro del CSV no pasa la validación.

Devoluciones

Es una lista list[str] de cadenas validadas y únicas que se analizan a partir de la entrada. Si no se identifican valores válidos o si la entrada es None, se devuelve una lista vacía.

class TIPCommon.base.job.data_models.JobParameter

clase TIPCommon.base.job.data_models.JobParameter(input_dict: MutableMapping[str, Any])

Bases: object

JobParameter representa un parámetro de configuración individual para una secuencia de comandos de trabajo, y administra su estado de metadatos y valores.

Atributos

Atributos
full_dict	dict[str, Any] Diccionario original que se recibió de la API durante la inicialización del trabajo.
id	int | None Es el identificador único asignado por la plataforma para el parámetro del trabajo.
is_mandatory	bool Indica si se debe proporcionar el parámetro para que se ejecute el trabajo.
name	str | None Es el nombre del identificador interno del parámetro.
type	ActionParamType Es la clasificación del tipo de datos del parámetro.
value	Any Es el valor predeterminado del parámetro, que suele tener prioridad en las ejecuciones de trabajos automatizadas.

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