TIPCommon.base

O módulo TIPCommon.base serve como referência técnica fundamental para o desenvolvimento de integração no Google SecOps, fornecendo lógica principal para ações, jobs em segundo plano e normalização de dados multiplataforma.

Análise de dados de ações

Esta seção contém funções utilitárias necessárias para analisar dados de casos de respostas brutas da API em objetos estruturados para uso em tarefas de automação.

TIPCommon.base.action.action_parser.parse_case_attachment

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

Essa utilidade converte dados brutos de anexos JSON de uma resposta da API em um objeto CaseAttachment estruturado.

Parâmetros

Parâmetros
attachment	Os dados JSON brutos do anexo, conforme recuperados da resposta da API.

TIPCommon.base.action.action_parser.parse_case_comment

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

Essa função analisa dados brutos de comentários JSON em um objeto CaseComment para facilitar o acesso aos metadados de comentários.

Parâmetros

Parâmetros
comment	Os dados JSON brutos do comentário, conforme recuperados da resposta da API.

class TIPCommon.base.action.base_action.Action

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

Bases: ABC, Generic[ApiClient]

A classe base Action oferece uma infraestrutura unificada para o desenvolvimento de automação, incluindo gerenciamento de propriedades e fluxos de execução gerais.

Aviso: essa classe requer Python 3. Os ambientes legados do Python 2 não são compatíveis.

Parâmetros

Parâmetros
name	O identificador do script da ação.

Atributos

Os atributos a seguir gerenciam o estado interno da ação e fornecem acesso a recursos do SDK e clientes de integração.

Atributos
_soar_action	SiemplifyAction O objeto do SDK SiemplifyAction.
_api_client	Apiable O cliente de API da integração.
_name	str O nome do script que usa essa ação.
_action_start_time	int O horário de início da ação no Unix.
_logger	SiemplifyLogger O objeto de logger usado para registrar ações.
_params	Container O contêiner de parâmetros para essa ação.
global_context	dict Um dicionário para armazenar o contexto, se necessário.
_entity_types	list[EntityTypesEnum] Os tipos de entidade compatíveis com a ação.
_entities_to_update	list[Entity] As entidades a serem atualizadas quando a ação terminar.
json_results	JSON Os resultados em JSON da ação.
_attachments	list[Attachment] Os anexos de resultado do caso a serem adicionados.
_contents	list[Content] O conteúdo do resultado do caso a ser adicionado.
_data_tables	list[DataTable] As tabelas de dados de resultados de caso a serem adicionadas.
_html_reports	list[HTMLReport] Os relatórios HTML de resultados de caso a serem adicionados.
_links	list[Link] Os links de resultado do caso a serem adicionados.
_markdowns	list[Markdown] Os markdowns de resultado do caso a serem adicionados.
_entity_insights	list[EntityInsight] Os insights da entidade de caso a serem adicionados.
_case_insights	list[CaseInsight] Os insights de caso a serem adicionados.
_execution_state	ExecutionState O indicador do estado de execução final da ação.
_result_value	bool O valor do resultado final da ação.
_output_message	str A mensagem de saída da ação quando ela é concluída.
_error_output_message	str A mensagem de saída da ação quando ela falha.

Métodos

Métodos padrão usados para gerenciar o ciclo de vida e a formatação de saída de um script de ação.

- run()	Executa a ação.
- _get_adjusted_json_results()	Ajusta o resultado JSON para uma estrutura específica.

Métodos abstratos

Os desenvolvedores precisam substituir esses métodos para definir a lógica exclusiva de uma ação personalizada.

Métodos abstratos
_validate_params()	Valida os parâmetros desta ação.
_init_api_clients()	Inicializa os clientes de API da ação.
_perform_action()	Executa a lógica principal da ação.

Outros métodos

Esses métodos opcionais são acionados durante fases específicas do ciclo de vida de execução da ação para processar alertas ou limpar 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 do SDK

Esses métodos oferecem acesso conveniente ao SDK subjacente, permitindo que as ações interajam com casos, alertas e configurações da 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()

Exemplo de implementação

O exemplo a seguir demonstra como implementar uma ação personalizada herdando da classe 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()

Propriedades

As propriedades a seguir oferecem acesso somente leitura ou gerenciado a metadados de ações, resultados e objetos do SDK.

action_start_time

property action_start_time: int

Retorna um int que representa o horário de início da ação no formato Unix.

api_client

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

Retorna um objeto Apiable que representa o cliente da API configurado para a integração.

anexos

property attachments: list[Attachment]

Retorna uma lista de objetos Attachment que representam os anexos de resultado do caso associados a essa ação. Todos os anexos nesta lista são enviados para o resultado do caso por padrão.

case_insights

property case_insights: list[CaseInsight]

Retorna uma lista de objetos CaseInsight que representam descobertas de alto nível associadas a essa ação. Todos os insights de caso nesta lista são enviados para o resultado do caso por padrão.

contents

property contents: list[Content]

Retorna uma lista de objetos Content que representam resultados de texto para o caso. Todo o conteúdo desta lista é enviado para o resultado do caso por padrão.

data_tables

property data_tables: list[DataTable]

Retorna uma lista de objetos DataTable que representam insights de dados tabulares para o caso. Todas as tabelas de dados nessa lista são enviadas para o resultado do caso por padrão.

entities_to_update

property entities_to_update: list[DomainEntityInfo]

Retorna uma lista de objetos Entity para atualizar na plataforma assim que a ação for concluída.

entity_insights

property entity_insights: list[EntityInsight]

Retorna uma lista de objetos EntityInsight que representam descobertas vinculadas a entidades específicas. Todos os insights de entidade nesta lista são enviados para o resultado do caso por padrão.

entity_types

property entity_types: list[EntityTypesEnum]

Retorna uma lista de objetos EntityTypesEnum que representam os tipos de entidade que a ação foi projetada para processar. Se uma ação for executada em entidades, ela só vai processar os tipos que aparecem nessa lista.

error_output_message

property error_output_message: str

Recebe ou define a mensagem mostrada na plataforma em caso de falha na execução. O valor padrão é Action ACTION_NAME failed.

execution_state

property execution_state: ExecutionState

Retorna um objeto ExecutionState que representa o indicador de status de processamento final. Os status possíveis são:

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

global_context

global_context: dict

Um dicionário usado para armazenar e recuperar informações de contexto durante a execução de ações.

html_reports

property html_reports: list[HTMLReport]

Retorna uma lista de objetos HTMLReport que representam relatórios visuais para o resultado do caso. Por padrão, todos os relatórios HTML nesta lista são enviados para o resultado do caso.

is_first_run

property is_first_run: bool

Retorna true se esta for a execução inicial da ação ou false caso contrário.

json_results

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

Retorna o resultado JSON formatado para exibição no mural do caso e uso na lógica do playbook downstream.

links

property links: list[Link]

Retorna uma lista de objetos Link que representam URLs de referência externos para o resultado do caso. Todos os links nesta lista são enviados para o resultado do caso por padrão.

logger

property logger: NewLineLogger

Retorna a instância NewLineLogger usada para geração de registros específicos do script.

reduções de preço

property markdowns: list[Markdown]

Retorna uma lista de objetos Markdown que representam insights de texto formatado. Todas as marcações nesta lista são enviadas para o resultado do caso por padrão.

nome

property name: str

Retorna o nome da string do script de ação.

output_message

property output_message: str

Recebe ou define a mensagem mostrada na plataforma que resume uma execução de ação bem-sucedida.

params

property params: Container

Retorna um objeto Container que descreve os parâmetros de entrada da ação, com cada parâmetro exposto como um atributo snake_case.

result_value

property result_value: bool

Recebe ou define o indicador de sucesso retornado à plataforma.

• True: a ação foi concluída.
• False: a ação falhou.

run

run(**kwargs)

Método padrão para acionar a lógica de execução da ação.

soar_action

property soar_action: SiemplifyAction

Retorna o objeto SiemplifyAction do SDK subjacente usado para interação direta com a plataforma.

class TIPCommon.base.action.base_enrich_action.EnrichAction

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

Bases: Action

EnrichAction é uma classe base especializada projetada para ações que atualizam propriedades de entidades com dados externos.

Parâmetros

O parâmetro a seguir é necessário para inicializar a ação de enriquecimento e registrá-la na plataforma.

Parâmetros
name	O identificador exclusivo do script de ação de enriquecimento.

Atributos

Os atributos a seguir gerenciam os dados usados durante as iterações de entidades e definem o conteúdo incluído nos resultados da ação.

Atributos
enrichment_data	dict Os dados de enriquecimento da entidade atual em cada uma das iterações da entidade. No final de cada iteração, o atributo additional_properties da entidade é atualizado com self.enrichment_data, o que significa que esse valor é definido sempre com o novo valor.
entity_results	Any Resultados de entidade incluídos na saída JSON para esse objeto.
global_context	dict Um dicionário usado para armazenar e compartilhar dados de contexto em diferentes fases da execução da ação de enriquecimento.

Métodos abstratos

Os seguintes métodos abstratos precisam ser implementados em subclasses para definir os tipos de entidade específicos e a lógica de enriquecimento da ação.

Métodos abstratos
_get_entity_types()	Recebe o tipo de entidades em que a ação é executada.
_perform_enrich_action()	Executa a lógica de enriquecimento principal em uma entidade.

Métodos particulares

Esses métodos internos processam a orquestração da lógica de enriquecimento e não devem ser modificados.

Métodos particulares
_perform_action()	Esse método combina os outros métodos abstratos com mais lógica de enriquecimento OOTB e a transmite para a classe mãe para usar no método start(). Aviso:não substitua esse método.

Módulo "Modelos de dados"

Este módulo fornece definições estruturadas para objetos, enums e constantes de integração cruzada.

class TIPCommon.base.action.data_models.ActionParamType

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

Bases: Enum

O ActionParamType define os tipos de dados da UI compatíveis com parâmetros de script de ação.

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

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

Bases: object

Esse modelo representa um anexo de resultado de script para fazer upload no mural do caso.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Parâmetros

Os seguintes parâmetros são necessários para inicializar um objeto de anexo, definindo os metadados e os dados binários a serem enviados para o caso.

Parâmetros
filename	O nome do arquivo a ser criado nos resultados do caso.
file_contents	Os dados binários brutos que representam o conteúdo do arquivo.
title	O título de exibição do anexo conforme aparece na UI da plataforma. O padrão é 'Script Result Attachment'.

Atributos

Os atributos a seguir definem os metadados e o conteúdo binário do anexo de arquivo gerado pelo script de ação.

Atributos
title	str | None O título do anexo exibido na interface da plataforma.
filename	str O nome específico do arquivo a ser criado.
file_contents	bytes O conteúdo binário bruto do arquivo anexado.
additional_data	dict | None Um dicionário que contém dados complementares associados ao anexo.

class TIPCommon.base.action.data_models.CaseAttachment

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

Bases: object

Essa classe representa um anexo imutável associado a um caso.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir representam os metadados específicos de um anexo que já foi associado a um caso na plataforma.

Atributos
attachment_id	int O identificador exclusivo atribuído pela plataforma ao anexo.
attachment_type	str A classificação ou o tipo MIME do anexo (por exemplo, txt, csv ou json).
description	str Uma descrição definida pelo usuário ou gerada pelo sistema do conteúdo do anexo.
is_favorite	bool Indica se o anexo foi marcado como favorito para acesso rápido no mural do caso.

class TIPCommon.base.action.data_models.CaseComment

class 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 um registro imutável de um comentário associado a um caso ou alerta, capturando detalhes do criador de conteúdo e carimbos de data/hora de auditoria.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir definem o conteúdo e os metadados administrativos de um comentário de caso.

Atributos
comment	str O conteúdo de texto principal do comentário.
comment_for_client	str | None Uma versão opcional do comentário adaptada para a visibilidade do cliente.
modification_time_unix_time_in_ms_for_client	int O carimbo de data/hora da modificação do comment_for_client em milissegundos do Unix.
last_editor	str O ID do último editor, como 77bdb7a4-8484-481d-9482-2449e33f9518.
last_editor_full_name	str O nome de exibição completo do usuário que editou o comentário pela última vez, como admin admin.
is_deleted	bool Indica se o comentário foi marcado como excluído.
creator_user_id	str O ID do usuário criador, como 77bdb7a4-8484-481d-9482-2449e33f9518.
creator_full_name	str O nome de exibição completo do criador de conteúdo, como System.
comment_id	int O identificador inteiro exclusivo atribuído pela plataforma ao comentário.
comment_type	int A classificação do tipo de comentário.
case_id	int O ID do caso associado a este comentário.
is_favorite	bool Indica se o comentário foi fixado como favorito.
modification_time_unix_time_in_ms	int É o horário da última modificação do comentário em milissegundos do Unix, como 1686040471269.
creation_time_unix_time_in_ms	int O horário de criação do comentário em milissegundos Unix, como 1686040471269.
alert_identifier	str O identificador específico do alerta relacionado ao comentário, como SUSPICIOUS PHISHING EMAIL_83765943-9437-4771-96F6-BD0FB291384E.

class TIPCommon.base.action.data_models.CaseInsight

class 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 um resumo imutável e estruturado de descoberta ou alerta mostrado no mural do caso.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir gerenciam como os insights são categorizados e apresentados aos analistas na plataforma.

Atributos
title	str O título exibido para o insight no painel de casos.
triggered_by	str O nome da integração ou do usuário que gerou o insight.
content	str O corpo da mensagem detalhada ou a descoberta do insight.
severity	InsightSeverity O nível de urgência do insight. Os valores possíveis são: info warning error
insight_type	InsightType Categoriza o insight. Os valores possíveis são: general entity
entity_identifier	str | None O identificador específico de uma entidade se o insight for focado nela.
additional_data	Any | None Dados complementares associados ao insight.
additional_data_type	Any | None A classificação do tipo de dados para o atributo additional_data.
additional_data_title	str | None O título de exibição do bloco de dados complementares.

class TIPCommon.base.action.data_models.CasePriority

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

Bases: Enum

CasePriority define os níveis de gravidade baseados em números inteiros atribuídos aos casos na plataforma.

Constantes

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

class TIPCommon.base.action.data_models.CaseStage

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

Bases: Enum

CaseStage especifica as fases operacionais pelas quais um caso pode passar durante o ciclo de vida.

Constantes

Constante	Valor
ASSESSMENT	"Avaliação"
IMPROVEMENT	"Melhoria"
INCIDENT	"Incidente"
INVESTIGATION	"Investigação"
RESEARCH	"Pesquisa"
TRIAGE	"Triagem"

class TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses

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

Bases: Enum

CloseCaseOrAlertInconclusiveRootCauses oferece opções de causa raiz para cenários em que não é possível fazer uma determinação definitiva.

Constantes

Constante	Valor
NO_CLEAR_CONCLUSION	"Nenhuma conclusão clara"

class TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses

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

Bases: Enum

CloseCaseOrAlertMaintenanceRootCauses define causas raiz relacionadas a testes programados, manutenção do sistema ou desenvolvimento de regras.

Constantes

Constante	Valor
LAB_TEST	"Teste de laboratório"
OTHER	"Outro"
RULE_UNDER_CONSTRUCTION	"Regra em construção"

class TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses

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

Bases: Enum

O CloseCaseOrAlertMaliciousRootCauses oferece categorias específicas para ameaças confirmadas, problemas de infraestrutura ou falhas no sistema.

Constantes

Constante	Valor
EXTERNAL_ATTACK	"Ataque externo"
INFRASTRUCTURE_ISSUE	"Problema de infraestrutura"
IRRELEVANT_TCP_UDP_PORT	'Porta TCP/UDP irrelevante'
MISCONFIGURED_SYSTEM	"Sistema mal configurado"
OTHER	"Outro"
SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION	"Um caso semelhante já está em investigação"
SYSTEM_APPLICATION_MALFUNCTION	"Mau funcionamento do sistema/aplicativo"
SYSTEM_CLOCKED_THE_ATTACK	"O sistema bloqueou o ataque"
UNFORESEEN_EFFECTS_OF_CHANGE	"Efeitos imprevistos da mudança"
UNKNOWN	'Unknown'

class TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses

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

Bases: Enum

CloseCaseOrAlertNotMaliciousRootCauses define categorias para atividades benignas, ações legítimas ou erros que não representam uma ameaça.

Constantes

Constante	Valor
EMPLOYEE_ERROR	"Erro do funcionário"
HUMAN_ERROR	"Erro humano"
LAB_TEST	"Teste de laboratório"
LEGIT_ACTION	"Ação legítima"
MISCONFIGURED_SYSTEM	"Sistema mal configurado"
NONE	"Nenhum"
NORMAL_BEHAVIOR	"Comportamento normal"
OTHER	"Outro"
PENETRATION_TEST	"Teste de penetração"
RULE_UNDER_CONSTRUCTION	"Regra em construção"
SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION	"Um caso semelhante já está em investigação"
UNKNOWN	'Unknown'
USER_MISTAKE	"Erro do usuário"

class TIPCommon.base.action.data_models.CloseCaseOrAlertReasons

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

Bases: Enum

CloseCaseOrAlertReasons fornece categorias padronizadas de alto nível para o motivo do encerramento de um caso ou alerta.

Constantes

Constante	Valor
MALICIOUS	0
NOT_MALICIOUS	1
MAINTENANCE	2
INCONCLUSIVE	3

class TIPCommon.base.action.data_models.Content

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

Bases: object

Content representa um resultado de texto imutável gerado por um script para adicionar ao mural de casos.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir definem o conteúdo textual ou baseado em Markdown exibido nos resultados de casos na plataforma.

Atributos
title	str | None O título de exibição do bloco de conteúdo como aparece na UI de resultados do script.
content	str O conteúdo principal da mensagem, que pode ser fornecido como uma string de texto bruta ou formatado como Markdown.

class TIPCommon.base.action.data_models.DataTable

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

Bases: object

DataTable representa uma lista de strings formatadas em CSV renderizadas como uma tabela estruturada nos resultados do caso.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir definem a estrutura e a exibição de dados tabulares no conjunto de resultados da ação.

Atributos
title	str | None O título exibido acima da tabela de dados na interface da plataforma.
data_table	list[str] Uma lista de strings em que cada elemento representa uma linha formatada em CSV que constrói a tabela.

class TIPCommon.base.action.data_models.EntityInsight

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

Bases: object

O EntityInsight é usado para criar descobertas específicas associadas a uma entidade, geralmente mostradas na visualização de detalhes dela.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Os atributos a seguir definem a relação entre uma entidade e as descobertas geradas por um script de integração.

Atributos
entity	Entity O objeto de entidade que está sendo enriquecido com novas descobertas.
message	str A observação, a descoberta ou a mensagem descritiva principal da entidade.
triggered_by	str | None O nome da integração que identificou a descoberta.
original_requesting_user	str | None O identificador exclusivo do usuário que iniciou a solicitação.

class TIPCommon.base.action.data_models.EntityTypesEnum

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

Bases: Enum

EntityTypesEnum fornece constantes para todos os tipos de entidade reconhecidos pelo Google SecOps.

Constantes

As constantes a seguir definem os tipos de entidades padronizados compatíveis com a plataforma para tarefas de enriquecimento e automação.

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

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

Bases: Enum

ExecutionState representa o indicador de status final retornado à plataforma para determinar o sucesso ou a falha de uma ação.

Constantes

Constante	Valor
COMPLETED	0
IN_PROGRESS	1
FAILED	2
TIMED_OUT	3

class TIPCommon.base.action.data_models.FullDetailsConfigurationParameter

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

Bases: object

FullDetailsConfigurationParameter encapsula um parâmetro de configuração de integração geral com todos os metadados recuperados da API.

Atributos

Os atributos a seguir gerenciam metadados, identificação e restrições de configuração de parâmetros.

table> Attributes full_dict

dict[str, Any]

O dicionário original recebido da resposta da API.

id

int | None

O identificador exclusivo atribuído pela plataforma ao parâmetro.

integration_identifier

str

O identificador da integração associada a esse parâmetro, como VirusTotalV3.

creation_time

int

O carimbo de data/hora que indica quando o parâmetro foi criado, em milissegundos do Unix.

modification_time

int

O carimbo de data/hora que indica quando o parâmetro foi modificado pela última vez, em milissegundos Unix.

is_mandatory

bool

Define se o parâmetro é obrigatório para a integração com a função.

description

str | None

A descrição detalhada da finalidade do parâmetro.

name

str

O nome do identificador interno do parâmetro.

display_name

str

O nome legível do parâmetro, conforme exibido na interface da plataforma.

value

Any

O valor padrão atribuído ao parâmetro.

type

IntegrationParamType

A classificação do tipo de dados do parâmetro.

optional_values

list

Uma lista de valores opcionais fornecidos para tipos de parâmetros de lista suspensa (DDL).

class TIPCommon.base.action.data_models.HTMLReport

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

Bases: object

O HTMLReport representa uma visualização personalizada baseada em HTML para adicionar aos resultados do caso.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Atributos
title	str | None O título de exibição do relatório no painel de casos.
report_name	str O identificador interno ou nome do arquivo do relatório.
report_contents	str A string HTML bruta que define o conteúdo do relatório.

class TIPCommon.base.action.data_models.IntegrationParamType

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

Bases: Enum

IntegrationParamType especifica os tipos de dados compatíveis para configurações de configuração de integração.

Constantes

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

class TIPCommon.base.action.data_models.Link

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

Bases: object

Link representa um resultado de URL externo a ser exibido como um hiperlink no mural de casos.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Atributos
title	str | None O texto de exibição do hiperlink.
link	str O URL de destino do link.

class TIPCommon.base.action.data_models.Markdown

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

Bases: object

O Markdown oferece uma maneira estruturada de retornar conteúdo formatado em rich text usando a sintaxe do Markdown.

Observação: essa classe é imutável. Depois de atribuir valores e criar o objeto, não é possível atribuir novos valores aos atributos. A classe oferece suporte a hash (armazenado em um conjunto ou como uma chave de dicionário) e ao operador ==.

Atributos

Atributos
title	str | None O título de exibição do bloco de markdown.
markdown_content	str O conteúdo formatado na sintaxe Markdown.
markdown_name	str O nome exclusivo atribuído a esse resultado de Markdown.

class TIPCommon.base.action.data_models.ScriptParameter

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

Bases: object

ScriptParameter representa um único parâmetro de entrada para um script de ação, gerenciando o valor, o estado padrão e a visibilidade dele em playbooks ou ações manuais.

Atributos

Os atributos a seguir gerenciam os metadados, a priorização de valores e as restrições de dados para parâmetros de script individuais.

Atributos
full_dict	dict[str, Any] O dicionário original recebido da resposta da API.
id	int | None O identificador exclusivo atribuído pela plataforma ao parâmetro.
creation_time	int O carimbo de data/hora que indica quando o parâmetro foi criado, em milissegundos do Unix.
modification_time	int O carimbo de data/hora que indica quando o parâmetro foi modificado pela última vez, em milissegundos Unix.
custom_action_id	int | None O identificador da ação personalizada associada a esse parâmetro.
is_mandatory	bool Indica se o parâmetro precisa ser fornecido para que o script de ação seja executado.
default_value	Any O valor padrão do parâmetro. Esse valor tem prioridade sobre value nas execuções de playbook.
description	str | None A descrição detalhada da finalidade do parâmetro.
name	str | None O nome do identificador interno do parâmetro.
value	Any O valor atual do parâmetro. Esse valor tem prioridade sobre default_value em execuções manuais de ações.
type	ActionParamType A classificação do tipo de dados do parâmetro.
optional_values	list Uma lista de valores opcionais fornecidos para tipos de parâmetros de lista suspensa (DDL).

Resultados da execução do script

As classes e funções a seguir definem as estruturas padronizadas para retornar dados de ações e conectores para a plataforma.

class TIPCommon.base.data_models.ActionJsonOutput

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

Bases: object

ActionJsonOutput representa o payload JSON estruturado de uma ação, permitindo categorização específica e segmentação no nível da entidade.

Atributos

Atributos
title	str O título de exibição do bloco de resultados JSON.
content	str Conteúdo textual ou um resumo que acompanha os dados JSON.
type	str | None Um tipo de classificação opcional para a saída JSON.
is_for_entity	bool Indica se o resultado JSON está especificamente associado a uma entidade.
json_result	JSON | None O payload de dados JSON estruturados real.

class TIPCommon.base.data_models.ActionOutput

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

Bases: object

ActionOutput encapsula a estrutura completa de resultados de uma ação, combinando mensagens legíveis por humanos, estado e JSON estruturado.

Atributos

Atributos
output_message	str A principal mensagem de resumo exibida para o analista.
result_value	str | bool O resultado lógico da ação (por exemplo, sucesso/falha).
execution_state	ExecutionState O estado final do ciclo de vida da execução da ação.
json_output	ActionJsonOutput | None Os resultados JSON estruturados da ação.
debug_output	str Informações de diagnóstico opcionais para solução de problemas.

class TIPCommon.base.data_models.ConnectorJsonOutput

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

Bases: object

ConnectorJsonOutput define os dados estruturados retornados por um conector, incluindo alertas ingeridos, detalhes de estouro e registros de execução.

Atributos

Atributos
alerts	list[AlertInfo | CaseInfo] Uma lista de objetos de alerta ou caso ingeridos com sucesso.
overflow_alerts	list[OverflowAlertDetails] Uma lista de alertas que excederam os limites de ingestão e foram tratados como excesso.
log_items	list Uma lista de entradas de registro estruturadas geradas durante a execução do conector.
variables	dict Um dicionário de variáveis de estado persistentes entre execuções de conector.

class TIPCommon.base.data_models.ConnectorOutput

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

Bases: object

ConnectorOutput representa o contêiner de nível superior para resultados da execução do conector, encapsulando os dados JSON estruturados e strings de depuração opcionais.

Atributos

Atributos
json_output	ConnectorJsonOutput | None Os resultados JSON estruturados que contêm dados de ingestão e de registros.
debug_output	str String de depuração opcional para rastreamento de diagnóstico interno.

TIPCommon.base.data_models.alert_info_from_json

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

Cria um objeto AlertInfo analisando um dicionário de atributos. Isso normalmente é usado para reconstruir objetos de alerta durante a transformação ou teste de dados.

Retorna

Retorna um objeto AlertInfo totalmente inicializado com base nas propriedades definidas no dicionário JSON fornecido.

Módulo "Interfaces"

Esse módulo define contratos abstratos padrão para componentes de script fundamentais.

class TIPCommon.base.interfaces.apiable.Apiable

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

Bases: ABC, Generic[ApiParams]

Apiable é uma interface base abstrata para classes que encapsulam a lógica de comunicação da API, garantindo uma estrutura consistente para interações de serviços externos.

class TIPCommon.base.interfaces.authable.Authable

class TIPCommon.base.interfaces.authable.Authable

Bases: ABC, Generic[AuthParams]

Authable é uma interface base abstrata para classes que gerenciam fluxos de trabalho de autenticação, fornecendo um modelo padronizado para estabelecer sessões seguras com serviços externos.

Métodos abstratos

Os seguintes métodos abstratos precisam ser implementados em subclasses para definir a lógica de autenticação específica exigida pelo serviço de destino.

Métodos abstratos
authenticate_session()	authenticate_session(params: AuthParams) → None Autentica o atributo self.session usando o params fornecido (como um dataclass, TypedDict ou namedtuple). Use esse método para estabelecer a autenticação com o serviço associado à sessão depois que o objeto de sessão for inicializado.

class TIPCommon.base.interfaces.logger.Logger

class TIPCommon.base.interfaces.logger.Logger

Bases: ABC

A interface Logger garante que os scripts do marketplace forneçam uma saída de diagnóstico padronizada.

Métodos abstratos

Os métodos a seguir precisam ser implementados para processar vários níveis de gravidade de registro e relatórios de exceção.

Métodos abstratos
debug()	debug(msg: str, *args, **kwargs) → None Registra uma mensagem com o nível de gravidade DEBUG.
info()	info(msg: str, *args, **kwargs) → None Registra uma mensagem com o nível de gravidade INFO.
warn()	warn(warning_msg: str, *args, **kwargs) → None Registra uma mensagem com o nível de gravidade WARNING.
error()	error(error_msg: str, *args, **kwargs) → None Registra uma mensagem com o nível de gravidade ERROR.
exception()	exception(ex: Exception, *args, **kwargs) → None Registra uma mensagem com o nível de gravidade ERROR, incluindo o stack trace de exceção.

class TIPCommon.base.interfaces.session.Session

class TIPCommon.base.interfaces.session.Session

Bases: ABC, Generic[_R]

A interface Session oferece um modelo consistente para gerenciar sessões de API usando várias bibliotecas HTTP.

Atributos

Os atributos a seguir gerenciam as configurações de configuração e segurança da sessão de comunicação HTTP estabelecida.

Atributos
headers	dict Um dicionário que contém os cabeçalhos HTTP a serem enviados com cada solicitação na sessão.
verify	bool Um booleano que indica se a sessão deve verificar o certificado SSL do servidor.

Métodos abstratos

Os métodos abstratos a seguir definem os verbos HTTP padrão e o dispatcher de solicitação principal que as subclasses precisam implementar.

Métodos abstratos
get()	get(url: str, *args, **kwargs) → _R Recupera um recurso do servidor usando uma solicitação HTTP GET.
post()	post(url: str, *args, **kwargs) → _R Envia dados ao servidor para criar um recurso usando uma solicitação HTTP POST.
put()	put(url: str, *args, **kwargs) → _R Atualiza ou cria um recurso no servidor usando uma solicitação HTTP PUT.
patch()	patch(url: str, *args, **kwargs) → _R Aplica modificações parciais a um recurso usando uma solicitação HTTP PATCH.
delete()	delete(url: str, *args, **kwargs) → _R Remove um recurso especificado do servidor usando uma solicitação HTTP DELETE.
request()	request(method: str, *args, **kwargs) → _R O dispatcher de solicitação principal usado para realizar uma solicitação HTTP com um método especificado.

Módulo "Jobs"

Isso fornece a estrutura para scripts de processamento em segundo plano que são executados em uma programação definida na plataforma.

class TIPCommon.base.job.base_job.Job

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

Bases: ABC, Generic[ApiClient]

Job é uma classe base abstrata projetada para tarefas programadas que realizam operações independentes em segundo plano, como sincronização de dados ou verificações de integridade.

Parâmetros

O parâmetro a seguir é necessário para inicializar e registrar o job na plataforma.

Parâmetros
name	O identificador exclusivo usado para registrar e identificar o script do job.

Atributos

As propriedades a seguir fornecem acesso ao contexto de execução, à configuração e aos clientes de serviço integrados do job.

Atributos
api_client	ApiClient | None Fornece o cliente de API inicializado ou a coleção de clientes para interagir com serviços externos.
error_msg	str Armazena mensagens de erro encontradas durante a execução do job para relatórios de diagnóstico.
job_start_time	int O carimbo de data/hora do Unix que representa quando a execução do job começou.
logger	ScriptLogger Fornece a interface de registro para capturar dados informativos, de aviso e de erro durante a execução.
name	str O nome registrado do script do job.
params	Container Um contêiner que contém os parâmetros de configuração específicos fornecidos à instância do job.
soar_job	SiemplifyJob Representa a instância de job da plataforma subjacente, fornecendo acesso a hooks de execução de baixo nível.

Métodos

Os métodos a seguir gerenciam a orquestração e o ciclo de vida de execução do job.

Métodos
start()	Assinatura: start(**kwargs) → None O ponto de entrada principal que aciona a lógica de execução do job.

class TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob

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

Bases: Job, Generic[ApiClient]

O RefreshTokenRenewalJob fornece os métodos de ciclo de vida que influenciam o processamento de jobs para manutenção de tokens. As subclasses não precisam substituir esses métodos.

Atributos

Atributos
api_client	ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None O cliente ou os clientes de API inicializados usados para interações de serviços externos.

class TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

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

Bases: tupla

SuccessFailureTuple é uma tupla nomeada especializada usada para categorizar os resultados das operações de job em lote em sucessos e falhas.

Atributos

Atributos
success_list	list Uma lista que contém os identificadores ou objetos processados com sucesso.
failure_list	list Uma lista que contém os identificadores ou objetos que não foram processados.

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]

Essa função valida e analisa uma string de parâmetro separada por vírgulas (CSV) em uma lista de elementos únicos. Ele foi projetado para processar formatos complexos, incluindo valores únicos, strings entre aspas e entradas mistas.

Parâmetros

Parâmetros
param_name	str O nome ou a chave do parâmetro que está sendo validado.
param_csv_value	str | None A string CSV bruta fornecida na configuração do job. Retorna uma lista vazia se None.

Gera

Uma exceção ValueError será gerada se a string de entrada tiver um número inválido de aspas duplas, aspas incompatíveis ou se algum valor individual no CSV não passar na validação.

Retorna

Uma list[str] de strings exclusivas e validadas analisadas da entrada. Se nenhum valor válido for identificado ou se a entrada for None, uma lista vazia será retornada.

class TIPCommon.base.job.data_models.JobParameter

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

Bases: object

JobParameter representa um parâmetro de configuração individual para um script de job, gerenciando os metadados e o estado do valor.

Atributos

Atributos
full_dict	dict[str, Any] O dicionário original recebido da API durante a inicialização do job.
id	int | None O identificador exclusivo atribuído pela plataforma para o parâmetro do job.
is_mandatory	bool Indica se o parâmetro precisa ser fornecido para que o job seja executado.
name	str | None O nome do identificador interno do parâmetro.
type	ActionParamType A classificação do tipo de dados do parâmetro.
value	Any O valor padrão do parâmetro, que geralmente é priorizado em execuções de jobs automatizadas.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.