TIPCommon.base

Il modulo TIPCommon.base funge da riferimento tecnico fondamentale per lo sviluppo dell'integrazione all'interno di Google SecOps, fornendo la logica di base per azioni, job in background e normalizzazione dei dati multipiattaforma.

Analisi dei dati delle azioni

Questa sezione contiene le funzioni di utility necessarie per analizzare i dati dei casi dalle risposte dell'API non elaborate in oggetti strutturati da utilizzare nelle attività di automazione.

TIPCommon.base.action.action_parser.parse_case_attachment

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

Questa utilità converte i dati degli allegati JSON non elaborati di una risposta dell'API in un oggetto CaseAttachment strutturato.

Parametri

Parametri
attachment I dati JSON non elaborati dell'allegato recuperati dalla risposta dell'API.

TIPCommon.base.action.action_parser.parse_case_comment

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

Questa funzione analizza i dati dei commenti JSON non elaborati in un oggetto CaseComment per un accesso più semplice ai metadati dei commenti.

Parametri

Parametri
comment I dati JSON non elaborati del commento recuperati dalla risposta dell'API.

class TIPCommon.base.action.base_action.Action

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

Basi: ABC, Generic[ApiClient]

La classe base Action fornisce un'infrastruttura unificata per lo sviluppo di automazioni, tra cui la gestione delle proprietà e i flussi di esecuzione generali.

Parametri

Parametri
name L'identificatore dello script dell'azione.

Attributi

I seguenti attributi gestiscono lo stato interno dell'azione e forniscono l'accesso alle risorse dell'SDK e ai client di integrazione.

Attributi
_soar_action

SiemplifyAction

L'oggetto SDK SiemplifyAction.

_api_client

Apiable

Il client API dell'integrazione.

_name

str

Il nome dello script che utilizza questa azione.

_action_start_time

int

L'ora di inizio dell'azione in Unix.

_logger

SiemplifyLogger

L'oggetto logger utilizzato per il logging nelle azioni.

_params

Container

Il container dei parametri per questa azione.

global_context

dict

Un dizionario per archiviare il contesto, se necessario.

_entity_types

list[EntityTypesEnum]

I tipi di entità supportati dall'azione.

_entities_to_update

list[Entity]

Le entità da aggiornare al termine dell'azione.

json_results

JSON

I risultati JSON dell'azione.

_attachments

list[Attachment]

Gli allegati dei risultati del caso da aggiungere.

_contents

list[Content]

I contenuti dei risultati del caso da aggiungere.

_data_tables

list[DataTable]

Le tabelle di dati dei risultati del caso da aggiungere.

_html_reports

list[HTMLReport]

I report HTML dei risultati del caso da aggiungere.

list[Link]

I link ai risultati della richiesta da aggiungere.

_markdowns

list[Markdown]

I markdown dei risultati del caso da aggiungere.

_entity_insights

list[EntityInsight]

Gli insight sulle entità del caso da aggiungere.

_case_insights

list[CaseInsight]

Gli insight sulla richiesta da aggiungere.

_execution_state

ExecutionState

L'indicatore dello stato di esecuzione finale dell'azione.

_result_value

bool

Il valore del risultato finale dell'azione.

_output_message

str

Il messaggio di output dell'azione quando l'operazione va a buon fine.

_error_output_message

str

Il messaggio di output dell'azione quando non va a buon fine.

Metodi

Metodi standard utilizzati per gestire il ciclo di vita e la formattazione dell'output di uno script di azione.

- run() Avvia l'esecuzione dell'azione.
- _get_adjusted_json_results() Adatta il risultato JSON a una struttura specifica.

Metodi astratti

Gli sviluppatori devono eseguire l'override di questi metodi per definire la logica univoca di un'azione personalizzata.

Metodi astratti
_validate_params() Convalida i parametri per questa azione.
_init_api_clients() Inizializza i client API dell'azione.
_perform_action() Esegue la logica principale dell'azione.

Metodi aggiuntivi

Questi metodi facoltativi vengono attivati durante fasi specifiche del ciclo di vita dell'esecuzione dell'azione per gestire gli avvisi o pulire le risorse.

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

Metodi wrapper dell'SDK

Questi metodi forniscono un accesso pratico all'SDK sottostante, consentendo alle azioni di interagire con richieste, avvisi e configurazioni della piattaforma.

  • _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()

Esempio di implementazione

L'esempio seguente mostra come implementare un'azione personalizzata ereditando dalla 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()

Proprietà

Le seguenti proprietà forniscono l'accesso in sola lettura o gestito ai metadati delle azioni, ai risultati e agli oggetti SDK.

action_start_time

property action_start_time: int

Restituisce un int che rappresenta l'ora di inizio dell'azione in formato Unix.

api_client

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

Restituisce un oggetto Apiable che rappresenta il client API configurato per l'integrazione.

dannosi

property attachments: list[Attachment]

Restituisce un elenco di oggetti Attachment che rappresentano gli allegati dei risultati della richiesta associati a questa azione. Per impostazione predefinita, tutti gli allegati in questo elenco vengono inviati al risultato della richiesta.

case_insights

property case_insights: list[CaseInsight]

Restituisce un elenco di oggetti CaseInsight che rappresentano i risultati di alto livello associati a questa azione. Tutti gli insight sul caso in questo elenco vengono inviati al risultato del caso per impostazione predefinita.

contenuti

property contents: list[Content]

Restituisce un elenco di oggetti Content che rappresentano i risultati di testo per la richiesta. Tutti i contenuti di questo elenco vengono inviati al risultato del caso per impostazione predefinita.

data_tables

property data_tables: list[DataTable]

Restituisce un elenco di oggetti DataTable che rappresentano gli insight sui dati tabulari per la richiesta. Per impostazione predefinita, tutte le tabelle di dati in questo elenco vengono inviate al risultato del caso.

entities_to_update

property entities_to_update: list[DomainEntityInfo]

Restituisce un elenco di oggetti Entity da aggiornare nella piattaforma al termine dell'azione.

entity_insights

property entity_insights: list[EntityInsight]

Restituisce un elenco di oggetti EntityInsight che rappresentano i risultati legati a entità specifiche. Tutti gli insight sulle entità in questo elenco vengono inviati al risultato del caso per impostazione predefinita.

entity_types

property entity_types: list[EntityTypesEnum]

Restituisce un elenco di oggetti EntityTypesEnum che rappresentano i tipi di entità che l'azione è progettata per elaborare. Se un'azione viene eseguita su entità, elabora solo i tipi visualizzati in questo elenco.

error_output_message

property error_output_message: str

Recupera o imposta il messaggio visualizzato nella piattaforma in caso di esecuzione non riuscita. Il valore predefinito è Action ACTION_NAME failed.

execution_state

property execution_state: ExecutionState

Restituisce un oggetto ExecutionState che rappresenta l'indicatore dello stato di elaborazione finale. Sono disponibili i seguenti stati:

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

global_context

global_context: dict

Un dizionario utilizzato per archiviare e recuperare le informazioni di contesto durante l'esecuzione dell'azione.

html_reports

property html_reports: list[HTMLReport]

Restituisce un elenco di oggetti HTMLReport che rappresentano i report visivi per il risultato della richiesta. Per impostazione predefinita, tutti i report HTML in questo elenco vengono inviati al risultato del caso.

is_first_run

property is_first_run: bool

Restituisce true se si tratta dell'esecuzione iniziale dell'azione, altrimenti false.

json_results

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

Restituisce il risultato JSON formattato da visualizzare nella bacheca della richiesta e da utilizzare nella logica del playbook downstream.

property links: list[Link]

Restituisce un elenco di oggetti Link che rappresentano gli URL di riferimento esterni per il risultato della richiesta. Per impostazione predefinita, tutti i link in questo elenco vengono inviati al risultato della richiesta.

logger

property logger: NewLineLogger

Restituisce l'istanza NewLineLogger utilizzata per il logging specifico dello script.

markdown

property markdowns: list[Markdown]

Restituisce un elenco di oggetti Markdown che rappresentano insight sul testo formattato. Tutti i markdown in questo elenco vengono inviati al risultato del caso per impostazione predefinita.

nome

property name: str

Restituisce il nome della stringa dello script dell'azione.

output_message

property output_message: str

Recupera o imposta il messaggio visualizzato nella piattaforma che riassume l'esecuzione di un'azione riuscita.

params

property params: Container

Restituisce un oggetto Container che descrive i parametri di input dell'azione, con ogni parametro esposto come attributo snake_case.

result_value

property result_value: bool

Recupera o imposta l'indicatore di successo restituito alla piattaforma.

  • True: l'azione è riuscita.
  • False: l'azione non è riuscita.

run

run(**kwargs)

Metodo standard per attivare la logica di esecuzione dell'azione.

soar_action

property soar_action: SiemplifyAction

Restituisce l'oggetto SDK SiemplifyAction sottostante utilizzato per l'interazione diretta con la piattaforma.

class TIPCommon.base.action.base_enrich_action.EnrichAction

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

Basi: Azione

EnrichAction è una classe base specializzata progettata per le azioni che aggiornano le proprietà delle entità con dati esterni.

Parametri

Il seguente parametro è obbligatorio per inizializzare l'azione di arricchimento e registrarla all'interno della piattaforma.

Parametri
name L'identificatore univoco dello script dell'azione di arricchimento.

Attributi

I seguenti attributi gestiscono i dati utilizzati durante le iterazioni delle entità e definiscono i contenuti inclusi nei risultati di output dell'azione.

Attributi
enrichment_data

dict

I dati di arricchimento per l'entità corrente in ciascuna delle iterazioni dell'entità. Al termine di ogni iterazione, l'attributo additional_properties dell'entità viene aggiornato con self.enrichment_data, il che significa che questo valore viene impostato ogni volta con il nuovo valore.

entity_results

Any

Risultati delle entità inclusi nell'output JSON per questo oggetto.

global_context

dict

Un dizionario utilizzato per archiviare e condividere i dati di contesto tra diverse fasi dell'esecuzione dell'azione di arricchimento.

Metodi astratti

I seguenti metodi astratti devono essere implementati nelle sottoclassi per definire i tipi di entità specifici e la logica di arricchimento per l'azione.

Metodi astratti
_get_entity_types() Recupera il tipo di entità su cui viene eseguita l'azione.
_perform_enrich_action() Esegui la logica di arricchimento principale su un'entità.

Metodi privati

Questi metodi interni gestiscono l'orchestrazione della logica di arricchimento e non devono essere modificati.

Metodi privati
_perform_action()

Questo metodo combina gli altri metodi astratti con una logica di arricchimento OOTB più ampia e la trasmette alla classe principale per l'utilizzo nel metodo start().

Modulo Modelli di dati

Questo modulo fornisce definizioni strutturate per oggetti, enum e costanti di integrazione incrociata.

class TIPCommon.base.action.data_models.ActionParamType

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

Basi: Enum

ActionParamType definisce i tipi di dati della UI supportati per i parametri degli script di azione.

Costanti

CostanteValore
BOOLEAN1
CASE_PRIORITIES7
CLOSE_CASE_REASONS5
CLOSE_ROOT_CAUSE6
CODE20
CONTENT11
DDL15
EMAIL_CONTENT10
ENTITY_TYPE13
MULTI_VALUES14
NULL-1
PASSWORD12
PLAYBOOK_NAME2
STAGE4
STRING0
USER3

class TIPCommon.base.action.data_models.Attachment

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

Basi: object

Questo modello rappresenta un allegato con i risultati dello script da caricare nella bacheca della richiesta.

Parametri

I seguenti parametri sono obbligatori per inizializzare un oggetto allegato, definendo i relativi metadati e i dati binari da caricare nella richiesta.

Parametri
filename Il nome del file da creare all'interno dei risultati della richiesta.
file_contents I dati binari non elaborati che rappresentano i contenuti del file.
title Il titolo visualizzato per l'allegato così come appare nell'interfaccia utente della piattaforma; il valore predefinito è 'Script Result Attachment'.

Attributi

I seguenti attributi definiscono i metadati e i contenuti binari dell'allegato file generato dallo script di azione.

Attributi
title

str | None

Il titolo dell'allegato visualizzato nell'interfaccia della piattaforma.

filename

str

Il nome specifico del file da creare.

file_contents

bytes

I contenuti binari non elaborati del file allegato.

additional_data

dict | None

Un dizionario contenente dati supplementari associati all'allegato.

class TIPCommon.base.action.data_models.CaseAttachment

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

Basi: object

Questa classe rappresenta un allegato immutabile associato a una richiesta.

Attributi

I seguenti attributi rappresentano i metadati specifici di un allegato che è già stato associato a una richiesta all'interno della piattaforma.

Attributi
attachment_id

int

L'identificatore univoco assegnato dalla piattaforma per l'allegato.

attachment_type

str

La classificazione o il tipo MIME dell'allegato (ad esempio, txt, csv o json).

description

str

Una descrizione dei contenuti dell'allegato definita dall'utente o generata dal sistema.

is_favorite

bool

Indica se l'allegato è stato contrassegnato come preferito per un accesso rapido nella bacheca della richiesta.

class TIPCommon.base.action.data_models.CaseComment

classe 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)

Basi: object

CaseComment rappresenta un record immutabile di un commento associato a una richiesta o a un avviso, che acquisisce i dettagli dell'autore e i timestamp di controllo.

Attributi

I seguenti attributi definiscono i contenuti e i metadati amministrativi di un commento alla richiesta.

Attributi
comment

str

Il contenuto di testo principale del commento.

comment_for_client

str | None

Una versione facoltativa del commento personalizzata per la visibilità del cliente.

modification_time_unix_time_in_ms_for_client

int

Il timestamp della modifica di comment_for_client in millisecondi Unix.

last_editor

str

L'ID dell'ultimo editor, ad esempio 77bdb7a4-8484-481d-9482-2449e33f9518.

last_editor_full_name

str

Il nome visualizzato completo dell'utente che ha modificato il commento per ultimo, ad esempio admin admin.

is_deleted

bool

Indica se il commento è stato contrassegnato come eliminato.

creator_user_id

str

L'ID utente del creator, ad esempio 77bdb7a4-8484-481d-9482-2449e33f9518.

creator_full_name

str

Il nome visualizzato completo del creator, ad esempio System.

comment_id

int

L'identificatore univoco intero assegnato dalla piattaforma per il commento.

comment_type

int

La classificazione dei caratteri tipografici del commento.

case_id

int

L'ID della richiesta associata a questo commento.

is_favorite

bool

Indica se il commento è stato fissato come preferito.

modification_time_unix_time_in_ms

int

L'ora dell'ultima modifica del commento in millisecondi Unix, ad esempio 1686040471269.

creation_time_unix_time_in_ms

int

L'ora di creazione del commento in millisecondi Unix, ad esempio 1686040471269.

alert_identifier

str

L'identificatore specifico dell'avviso relativo al commento, ad esempio SUSPICIOUS PHISHING EMAIL_83765943-9437-4771-96F6-BD0FB291384E.

class TIPCommon.base.action.data_models.CaseInsight

classe 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)

Basi: object

CaseInsight rappresenta un riepilogo immutabile e strutturato di un risultato o di un avviso visualizzato nella bacheca della richiesta.

Attributi

I seguenti attributi gestiscono il modo in cui gli insight vengono classificati e presentati agli analisti all'interno della piattaforma.

Attributi
title

str

Il titolo visualizzato per l'insight nella bacheca richieste.

triggered_by

str

Il nome dell'integrazione o dell'utente che ha generato l'insight.

content

str

Il corpo del messaggio dettagliato o il risultato dell'insight.

severity

InsightSeverity

Il livello di urgenza dell'insight.

I valori possibili sono:

  • info
  • warning
  • error
  • insight_type

    InsightType

    Categorizza l'insight.

    I valori possibili sono:

  • general
  • entity
  • entity_identifier

    str | None

    L'identificatore specifico di un'entità se l'insight è incentrato sull'entità.

    additional_data

    Any | None

    Dati supplementari associati all'insight.

    additional_data_type

    Any | None

    La classificazione del tipo di dati per l'attributo additional_data.

    additional_data_title

    str | None

    Il titolo visualizzato per il blocco di dati supplementari.

    class TIPCommon.base.action.data_models.CasePriority

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

    Basi: Enum

    CasePriority definisce i livelli di gravità basati su numeri interi assegnati alle richieste all'interno della piattaforma.

    Costanti

    Costante Valore
    CRITICAL100
    HIGH80
    INFORMATIONAL0
    LOW40
    MEDIUM60

    class TIPCommon.base.action.data_models.CaseStage

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

    Basi: Enum

    CaseStage specifica le fasi operative che una richiesta può attraversare durante il suo ciclo di vita.

    Costanti

    Costante Valore
    ASSESSMENT"Assessment"
    IMPROVEMENT"Miglioramento"
    INCIDENT'Incident'
    INVESTIGATION"Indagine"
    RESEARCH'Research' (Ricerca)
    TRIAGE'Triage'

    class TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses

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

    Basi: Enum

    CloseCaseOrAlertInconclusiveRootCauses fornisce opzioni per le cause principali per gli scenari in cui non è possibile prendere una decisione definitiva.

    Costanti

    Costante Valore
    NO_CLEAR_CONCLUSION"Nessuna conclusione chiara"

    class TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses

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

    Basi: Enum

    CloseCaseOrAlertMaintenanceRootCauses definisce le cause principali relative a test pianificati, manutenzione del sistema o sviluppo di regole.

    Costanti

    Costante Valore
    LAB_TEST"Test di laboratorio"
    OTHERAltra
    RULE_UNDER_CONSTRUCTION"Regola in fase di sviluppo"

    class TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses

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

    Basi: Enum

    CloseCaseOrAlertMaliciousRootCauses fornisce categorie specifiche per minacce confermate, problemi di infrastruttura o malfunzionamenti del sistema.

    Costanti

    Costante Valore
    EXTERNAL_ATTACK"Attacco esterno"
    INFRASTRUCTURE_ISSUE"Problema di infrastruttura"
    IRRELEVANT_TCP_UDP_PORT"Porta TCP/UDP non pertinente"
    MISCONFIGURED_SYSTEM"Sistema configurato in modo errato"
    OTHERAltra
    SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION "È già in corso un'indagine su una richiesta simile"
    SYSTEM_APPLICATION_MALFUNCTION "Malfunzionamento del sistema/dell'applicazione"
    SYSTEM_CLOCKED_THE_ATTACK"Il sistema ha bloccato l'attacco"
    UNFORESEEN_EFFECTS_OF_CHANGE"Effetti imprevisti del cambiamento"
    UNKNOWN'Unknown' (Sconosciuto)

    class TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses

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

    Basi: Enum

    CloseCaseOrAlertNotMaliciousRootCauses definisce le categorie per attività benigne, azioni legittime o errori che non rappresentano una minaccia.

    Costanti

    Costante Valore
    EMPLOYEE_ERROR"Errore del dipendente"
    HUMAN_ERROR"Errore umano"
    LAB_TEST"Test di laboratorio"
    LEGIT_ACTION'Azione legittima'
    MISCONFIGURED_SYSTEM"Sistema configurato in modo errato"
    NONE'None'
    NORMAL_BEHAVIOR"Comportamento normale"
    OTHERAltra
    PENETRATION_TEST"Test di penetrazione"
    RULE_UNDER_CONSTRUCTION"Regola in fase di sviluppo"
    SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION "È già in corso un'indagine su una richiesta simile"
    UNKNOWN'Unknown' (Sconosciuto)
    USER_MISTAKE"Errore dell'utente"

    class TIPCommon.base.action.data_models.CloseCaseOrAlertReasons

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

    Basi: Enum

    CloseCaseOrAlertReasons fornisce categorie standardizzate di alto livello per i motivi per cui un caso o un avviso viene chiuso.

    Costanti

    Costante Valore
    MALICIOUS0
    NOT_MALICIOUS1
    MAINTENANCE2
    INCONCLUSIVE3

    class TIPCommon.base.action.data_models.Content

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

    Basi: object

    Content rappresenta un risultato di testo immutabile generato da uno script da aggiungere alla bacheca della richiesta.

    Attributi

    I seguenti attributi definiscono i contenuti testuali o basati su markdown visualizzati nei risultati della richiesta sulla piattaforma.

    Attributi
    title

    str | None

    Il titolo visualizzato per il blocco di contenuti così come appare nell'interfaccia utente dei risultati dello script.

    content

    str

    I contenuti principali del messaggio, che possono essere forniti come stringa di testo non elaborato o formattati come markdown.

    class TIPCommon.base.action.data_models.DataTable

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

    Basi: object

    DataTable rappresenta un elenco di stringhe in formato CSV visualizzate come tabella strutturata nei risultati della richiesta.

    Attributi

    I seguenti attributi definiscono la struttura e la visualizzazione dei dati tabulari all'interno del set di risultati dell'azione.

    Attributi
    title

    str | None

    L'intestazione visualizzata sopra la tabella dei dati nell'interfaccia della piattaforma.

    data_table

    list[str]

    Un elenco di stringhe in cui ogni elemento rappresenta una riga in formato CSV che costruisce la tabella.

    class TIPCommon.base.action.data_models.EntityInsight

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

    Basi: object

    EntityInsight viene utilizzato per creare risultati specifici associati a un'entità, spesso visualizzati nella visualizzazione dei dettagli dell'entità.

    Attributi

    I seguenti attributi definiscono la relazione tra un'entità e i risultati generati da uno script di integrazione.

    Attributi
    entity

    Entity

    L'oggetto entità che viene arricchito con nuovi risultati.

    message

    str

    L'osservazione, il risultato o il messaggio descrittivo principale per l'entità.

    triggered_by

    str | None

    Il nome dell'integrazione che ha identificato il risultato.

    original_requesting_user

    str | None

    L'identificatore univoco dell'utente che ha avviato la richiesta in origine.

    class TIPCommon.base.action.data_models.EntityTypesEnum

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

    Basi: Enum

    EntityTypesEnum fornisce costanti per tutti i tipi di entità riconosciuti da Google SecOps.

    Costanti

    Le seguenti costanti definiscono i tipi di entità standardizzati supportati dalla piattaforma per le attività di arricchimento e automazione.

    Costante Valore
    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

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

    Basi: Enum

    ExecutionState rappresenta l'indicatore dello stato finale restituito alla piattaforma per determinare l'esito positivo o negativo di un'azione.

    Costanti

    Costante Valore
    COMPLETED0
    IN_PROGRESS1
    FAILED2
    TIMED_OUT3

    class TIPCommon.base.action.data_models.FullDetailsConfigurationParameter

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

    Basi: object

    FullDetailsConfigurationParameter incapsula un parametro di configurazione dell'integrazione generale con i relativi metadati completi recuperati dall'API.

    Attributi

    I seguenti attributi gestiscono i metadati, l'identificazione e i vincoli di configurazione dei parametri.

    table> Attributi full_dict

    dict[str, Any]

    Il dizionario originale ricevuto dalla risposta dell'API.

    id

    int | None

    L'identificatore univoco assegnato dalla piattaforma per il parametro.

    integration_identifier

    str

    L'identificatore dell'integrazione associata a questo parametro, ad esempio VirusTotalV3.

    creation_time

    int

    Il timestamp che indica quando è stato creato il parametro, in millisecondi Unix.

    modification_time

    int

    Il timestamp che indica l'ultima modifica del parametro, in millisecondi Unix.

    is_mandatory

    bool

    Definisce se il parametro è obbligatorio per il funzionamento dell'integrazione.

    description

    str | None

    La descrizione dettagliata dello scopo del parametro.

    name

    str

    Il nome dell'identificatore interno del parametro.

    display_name

    str

    Il nome leggibile del parametro, così come viene visualizzato nell'interfaccia della piattaforma.

    value

    Any

    Il valore predefinito assegnato al parametro.

    type

    IntegrationParamType

    La classificazione del tipo di dati del parametro.

    optional_values

    list

    Un elenco di valori facoltativi forniti per i tipi di parametri dell'elenco a discesa (DDL).

    class TIPCommon.base.action.data_models.HTMLReport

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

    Basi: object

    HTMLReport rappresenta una visualizzazione personalizzata basata su HTML da aggiungere ai risultati del caso.

    Attributi

    Attributi
    title

    str | None

    Il titolo visualizzato per il report nella bacheca richieste.

    report_name

    str

    L'identificatore interno o il nome file del report.

    report_contents

    str

    La stringa HTML non elaborata che definisce i contenuti del report.

    class TIPCommon.base.action.data_models.IntegrationParamType

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

    Basi: Enum

    IntegrationParamType specifica i tipi di dati supportati per le impostazioni di configurazione dell'integrazione.

    Costanti

    Costante Valore
    NULL-1
    BOOLEAN0
    INTEGER1
    STRING2
    PASSWORD3
    IP4
    EMAIL8

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

    Basi: object

    Link rappresenta un risultato URL esterno da visualizzare come link ipertestuale nella bacheca della richiesta.

    Attributi

    Attributi

    str | None

    Il testo visualizzato per il link ipertestuale.

    str

    L'URL di destinazione del link.

    class TIPCommon.base.action.data_models.Markdown

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

    Basi: object

    Markdown fornisce un modo strutturato per restituire contenuti formattati in RTF utilizzando la sintassi Markdown.

    Attributi

    Attributi
    title

    str | None

    Il titolo visualizzato per il blocco di markdown.

    markdown_content

    str

    I contenuti formattati nella sintassi Markdown.

    markdown_name

    str

    Il nome univoco assegnato a questo risultato di markdown.

    class TIPCommon.base.action.data_models.ScriptParameter

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

    Basi: object

    ScriptParameter rappresenta un singolo parametro di input per uno script di azione, gestendone il valore, lo stato predefinito e la visibilità all'interno dei playbook o delle azioni manuali.

    Attributi

    I seguenti attributi gestiscono i metadati, la definizione della priorità dei valori e i vincoli dei dati per i singoli parametri dello script.

    Attributi
    full_dict

    dict[str, Any]

    Il dizionario originale ricevuto dalla risposta dell'API.

    id

    int | None

    L'identificatore univoco assegnato dalla piattaforma per il parametro.

    creation_time

    int

    Il timestamp che indica quando è stato creato il parametro, in millisecondi Unix.

    modification_time

    int

    Il timestamp che indica l'ultima modifica del parametro, in millisecondi Unix.

    custom_action_id

    int | None

    L'identificatore dell'azione personalizzata associata a questo parametro.

    is_mandatory

    bool

    Indica se il parametro deve essere fornito per l'esecuzione dello script di azione.

    default_value

    Any

    Il valore predefinito del parametro.

    Questo valore ha la priorità su value nelle esecuzioni del playbook.

    description

    str | None

    La descrizione dettagliata dello scopo del parametro.

    name

    str | None

    Il nome dell'identificatore interno del parametro.

    value

    Any

    Il valore attuale del parametro.

    Questo valore ha la priorità su default_value nelle esecuzioni di azioni manuali.

    type

    ActionParamType

    La classificazione del tipo di dati del parametro.

    optional_values

    list

    Un elenco di valori facoltativi forniti per i tipi di parametri dell'elenco a discesa (DDL).

    Risultati dell'esecuzione dello script

    Le seguenti classi e funzioni definiscono le strutture standardizzate per la restituzione dei dati da azioni e connettori alla piattaforma.

    class TIPCommon.base.data_models.ActionJsonOutput

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

    Basi: object

    ActionJsonOutput rappresenta il payload JSON strutturato per un'azione, consentendo una categorizzazione specifica e un targeting a livello di entità.

    Attributi

    Attributi
    title

    str

    Il titolo visualizzato per il blocco di risultati JSON.

    content

    str

    Contenuti testuali o un riepilogo che accompagna i dati JSON.

    type

    str | None

    Un tipo di classificazione facoltativo per l'output JSON.

    is_for_entity

    bool

    Indica se il risultato JSON è associato specificamente a un'entità.

    json_result

    JSON | None

    Il payload dei dati JSON strutturati effettivi.

    class TIPCommon.base.data_models.ActionOutput

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

    Basi: object

    ActionOutput incapsula la struttura completa dei risultati di un'azione, combinando messaggi leggibili, stato e JSON strutturato.

    Attributi

    Attributi
    output_message

    str

    Il messaggio di riepilogo principale visualizzato dall'analista.

    result_value

    str | bool

    Il risultato logico dell'azione (ad es. riuscito/non riuscito).

    execution_state

    ExecutionState

    Lo stato finale del ciclo di vita dell'esecuzione dell'azione.

    json_output

    ActionJsonOutput | None

    I risultati JSON strutturati dell'azione.

    debug_output

    str

    Informazioni diagnostiche facoltative per la risoluzione dei problemi.

    class TIPCommon.base.data_models.ConnectorJsonOutput

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

    Basi: object

    ConnectorJsonOutput definisce i dati strutturati restituiti da un connettore, inclusi gli avvisi importati, i dettagli dell'overflow e i log di esecuzione.

    Attributi

    Attributi
    alerts

    list[AlertInfo | CaseInfo]

    Un elenco di oggetti di avvisi o richieste importati correttamente.

    overflow_alerts

    list[OverflowAlertDetails]

    Un elenco di avvisi che hanno superato i limiti di importazione e sono stati gestiti come overflow.

    log_items

    list

    Un elenco di voci di log strutturate generate durante l'esecuzione del connettore.

    variables

    dict

    Un dizionario di variabili di stato persistenti tra le esecuzioni del connettore.

    class TIPCommon.base.data_models.ConnectorOutput

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

    Basi: object

    ConnectorOutput rappresenta il contenitore di primo livello per i risultati dell'esecuzione del connettore, che racchiude i dati JSON strutturati e le stringhe di debug facoltative.

    Attributi

    Attributi
    json_output

    ConnectorJsonOutput | None

    I risultati JSON strutturati contenenti i dati di importazione e di log.

    debug_output

    str

    Stringa di debug facoltativa per il monitoraggio della diagnostica interna.

    TIPCommon.base.data_models.alert_info_from_json

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

    Crea un oggetto AlertInfo analizzando un dizionario di attributi. In genere, viene utilizzato per ricostruire gli oggetti di avviso durante la trasformazione o il test dei dati.

    Restituisce

    Restituisce un oggetto AlertInfo completamente inizializzato in base alle proprietà definite nel dizionario JSON fornito.

    Modulo Interfacce

    Questo modulo definisce i contratti astratti standard per i componenti di base degli script.

    class TIPCommon.base.interfaces.apiable.Apiable

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

    Basi: ABC, Generic[ApiParams]

    Apiable è un'interfaccia di base astratta per le classi che incapsulano la logica di comunicazione dell'API, garantendo una struttura coerente per le interazioni con i servizi esterni.

    class TIPCommon.base.interfaces.authable.Authable

    classe TIPCommon.base.interfaces.authable.Authable

    Basi: ABC, Generic[AuthParams]

    Authable è un'interfaccia di base astratta per le classi che gestiscono i workflow di autenticazione, fornendo un progetto standardizzato per stabilire sessioni sicure con servizi esterni.

    Metodi astratti

    I seguenti metodi astratti devono essere implementati nelle sottoclassi per definire la logica di autenticazione specifica richiesta dal servizio di destinazione.

    Metodi astratti
    authenticate_session()

    authenticate_session(params: AuthParams) → None

    Autentica l'attributo self.session utilizzando l'attributo params fornito (ad esempio dataclass, TypedDict o namedtuple).

    Utilizza questo metodo per stabilire l'autenticazione con il servizio associato alla sessione dopo l'inizializzazione dell'oggetto sessione.

    class TIPCommon.base.interfaces.logger.Logger

    classe TIPCommon.base.interfaces.logger.Logger

    Base: ABC

    L'interfaccia Logger che garantisce che gli script di Content Hub forniscano un output diagnostico standardizzato.

    Metodi astratti

    Per gestire i vari livelli di gravità del logging e i report sulle eccezioni, è necessario implementare i seguenti metodi.

    Metodi astratti
    debug()

    debug(msg: str, *args, **kwargs) → None

    Registra un messaggio con il livello di gravità DEBUG.

    info()

    info(msg: str, *args, **kwargs) → None

    Registra un messaggio con il livello di gravità INFO.

    warn()

    warn(warning_msg: str, *args, **kwargs) → None

    Registra un messaggio con il livello di gravità WARNING.

    error()

    error(error_msg: str, *args, **kwargs) → None

    Registra un messaggio con il livello di gravità ERROR.

    exception()

    exception(ex: Exception, *args, **kwargs) → None

    Registra un messaggio con il livello di gravità ERROR, inclusa l'analisi dello stack delle eccezioni.

    class TIPCommon.base.interfaces.session.Session

    classe TIPCommon.base.interfaces.session.Session

    Basi: ABC, Generic[_R]

    L'interfaccia Session fornisce un progetto coerente per la gestione delle sessioni API utilizzando varie librerie HTTP.

    Attributi

    I seguenti attributi gestiscono le impostazioni di configurazione e sicurezza della sessione di comunicazione HTTP stabilita.

    Attributi
    headers

    dict

    Un dizionario contenente le intestazioni HTTP da inviare con ogni richiesta nella sessione.

    verify

    bool

    Un valore booleano che indica se la sessione deve verificare il certificato SSL del server.

    Metodi astratti

    I seguenti metodi astratti definiscono i verbi HTTP standard e il dispatcher delle richieste principale che le sottoclassi devono implementare.

    Metodi astratti
    get()

    get(url: str, *args, **kwargs) → _R

    Recupera una risorsa dal server utilizzando una richiesta GET.

    post()

    post(url: str, *args, **kwargs) → _R

    Invia i dati al server per creare una risorsa utilizzando una richiesta POST HTTP.

    put()

    put(url: str, *args, **kwargs) → _R

    Aggiorna o crea una risorsa sul server utilizzando una richiesta HTTP PUT.

    patch()

    patch(url: str, *args, **kwargs) → _R

    Applica modifiche parziali a una risorsa utilizzando una richiesta HTTP PATCH.

    delete()

    delete(url: str, *args, **kwargs) → _R

    Rimuove una risorsa specificata dal server utilizzando una richiesta HTTP DELETE.

    request()

    request(method: str, *args, **kwargs) → _R

    Il dispatcher di richieste di base utilizzato per eseguire una richiesta HTTP con un metodo specificato.

    Modulo dei job

    In questo modo, viene fornito il framework per gli script di elaborazione in background che vengono eseguiti in base a una pianificazione definita all'interno della piattaforma.

    class TIPCommon.base.job.base_job.Job

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

    Basi: ABC, Generic[ApiClient]

    Job è una classe base astratta progettata per attività pianificate che eseguono operazioni in background indipendenti, come la sincronizzazione dei dati o i controlli di integrità.

    Parametri

    Il seguente parametro è obbligatorio per inizializzare il job e registrarlo all'interno della piattaforma.

    Parametri
    name L'identificatore univoco utilizzato per registrare e identificare lo script del job.

    Attributi

    Le seguenti proprietà forniscono l'accesso al contesto di esecuzione, alla configurazione e ai client di servizi integrati del job.

    Attributi
    api_client

    ApiClient | None

    Fornisce il client API inizializzato o la raccolta di client per l'interazione con i servizi esterni.

    error_msg

    str

    Memorizza eventuali messaggi di errore riscontrati durante l'esecuzione del job per i report diagnostici.

    job_start_time

    int

    Il timestamp Unix che rappresenta l'inizio dell'esecuzione del job.

    logger

    ScriptLogger

    Fornisce l'interfaccia di logging per l'acquisizione di dati informativi, di avviso e di errore durante l'esecuzione.

    name

    str

    Il nome registrato dello script del job.

    params

    Container

    Un container contenente i parametri di configurazione specifici forniti all'istanza del job.

    soar_job

    SiemplifyJob

    Rappresenta l'istanza del job della piattaforma sottostante, fornendo l'accesso agli hook di esecuzione di basso livello.

    Metodi

    I seguenti metodi gestiscono il ciclo di vita di orchestrazione ed esecuzione del job.

    Metodi
    start()

    Firma: start(**kwargs) → None

    L'entry point principale che attiva la logica di esecuzione del job.

    class TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob

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

    Basi: Job, Generic[ApiClient]

    RefreshTokenRenewalJob fornisce i metodi del ciclo di vita che influenzano l'elaborazione dei job per la manutenzione dei token. Le sottoclassi non sono tenute a eseguire l'override di questi metodi.

    Attributi

    Attributi
    api_client

    ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None

    Il client o i client API inizializzati utilizzati per le interazioni con i servizi esterni.

    class TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

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

    Basi: tuple

    SuccessFailureTuple è una tupla denominata specializzata utilizzata per classificare i risultati delle operazioni dei job batch in esiti positivi e negativi.

    Attributi

    Attributi
    success_list

    list

    Un elenco contenente gli identificatori o gli oggetti elaborati correttamente.

    failure_list

    list

    Un elenco contenente gli identificatori o gli oggetti la cui elaborazione non è riuscita.

    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]

    Questa funzione convalida e analizza una stringa di parametri separati da virgole (CSV) in un elenco di elementi unici. È progettato per gestire formati complessi, tra cui valori singoli, stringhe tra virgolette e input misti.

    Parametri

    Parametri
    param_name

    str

    Il nome o la chiave del parametro in fase di convalida.

    param_csv_value

    str | None

    La stringa CSV non elaborata fornita nella configurazione del job. Restituisce un elenco vuoto se None.

    Aumenta

    Viene generata un'eccezione ValueError se la stringa di input contiene un numero non valido di virgolette doppie, virgolette non corrispondenti o se la convalida di singoli valori all'interno del file CSV non va a buon fine.

    Restituisce

    Un elenco list[str] di stringhe univoche e convalidate analizzate dall'input. Se non vengono identificati valori validi o se l'input è None, viene restituito un elenco vuoto.

    class TIPCommon.base.job.data_models.JobParameter

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

    Basi: object

    JobParameter rappresenta un singolo parametro di configurazione per uno script di job, gestendo i relativi metadati e lo stato del valore.

    Attributi

    Attributi
    full_dict

    dict[str, Any]

    Il dizionario originale ricevuto dall'API durante l'inizializzazione del job.

    id

    int | None

    L'identificatore univoco assegnato dalla piattaforma per il parametro del job.

    is_mandatory

    bool

    Indica se il parametro deve essere fornito per l'esecuzione del job.

    name

    str | None

    Il nome dell'identificatore interno del parametro.

    type

    ActionParamType

    La classificazione del tipo di dati del parametro.

    value

    Any

    Il valore predefinito del parametro; questo valore ha in genere la priorità nelle esecuzioni automatiche dei job.

    Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.