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 |
L'oggetto SDK |
_api_client |
Il client API dell'integrazione. |
_name |
Il nome dello script che utilizza questa azione. |
_action_start_time |
L'ora di inizio dell'azione in Unix. |
_logger |
L'oggetto logger utilizzato per il logging nelle azioni. |
_params |
Il container dei parametri per questa azione. |
global_context |
Un dizionario per archiviare il contesto, se necessario. |
_entity_types |
I tipi di entità supportati dall'azione. |
_entities_to_update |
Le entità da aggiornare al termine dell'azione. |
json_results |
I risultati JSON dell'azione. |
_attachments |
Gli allegati dei risultati del caso da aggiungere. |
_contents |
I contenuti dei risultati del caso da aggiungere. |
_data_tables |
Le tabelle di dati dei risultati del caso da aggiungere. |
_html_reports |
I report HTML dei risultati del caso da aggiungere. |
_links |
I link ai risultati della richiesta da aggiungere. |
_markdowns |
I markdown dei risultati del caso da aggiungere. |
_entity_insights |
Gli insight sulle entità del caso da aggiungere. |
_case_insights |
Gli insight sulla richiesta da aggiungere. |
_execution_state |
L'indicatore dello stato di esecuzione finale dell'azione. |
_result_value |
Il valore del risultato finale dell'azione. |
_output_message |
Il messaggio di output dell'azione quando l'operazione va a buon fine. |
_error_output_message |
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 = 0ExecutionState.IN_PROGRESS = 1ExecutionState.FAILED = 2ExecutionState.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.
link
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 |
I dati di arricchimento per l'entità corrente in ciascuna delle iterazioni dell'entità. Al termine di ogni iterazione, l'attributo |
entity_results |
Risultati delle entità inclusi nell'output JSON per questo oggetto. |
global_context |
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 |
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
| Costante | Valore |
|---|---|
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
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 |
Il titolo dell'allegato visualizzato nell'interfaccia della piattaforma. |
filename |
Il nome specifico del file da creare. |
file_contents |
I contenuti binari non elaborati del file allegato. |
additional_data |
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 |
L'identificatore univoco assegnato dalla piattaforma per l'allegato. |
attachment_type |
La classificazione o il tipo MIME dell'allegato (ad esempio, |
description |
Una descrizione dei contenuti dell'allegato definita dall'utente o generata dal sistema. |
is_favorite |
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 |
Il contenuto di testo principale del commento. |
comment_for_client |
Una versione facoltativa del commento personalizzata per la visibilità del cliente. |
modification_time_unix_time_in_ms_for_client |
Il timestamp della modifica di |
last_editor |
L'ID dell'ultimo editor, ad esempio |
last_editor_full_name |
Il nome visualizzato completo dell'utente che ha modificato il commento per ultimo, ad esempio |
is_deleted |
Indica se il commento è stato contrassegnato come eliminato. |
creator_user_id |
L'ID utente del creator, ad esempio |
creator_full_name |
Il nome visualizzato completo del creator, ad esempio |
comment_id |
L'identificatore univoco intero assegnato dalla piattaforma per il commento. |
comment_type |
La classificazione dei caratteri tipografici del commento. |
case_id |
L'ID della richiesta associata a questo commento. |
is_favorite |
Indica se il commento è stato fissato come preferito. |
modification_time_unix_time_in_ms |
L'ora dell'ultima modifica del commento in millisecondi Unix, ad esempio |
creation_time_unix_time_in_ms |
L'ora di creazione del commento in millisecondi Unix, ad esempio |
alert_identifier |
L'identificatore specifico dell'avviso relativo al commento, ad esempio |
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 |
Il titolo visualizzato per l'insight nella bacheca richieste. |
triggered_by |
Il nome dell'integrazione o dell'utente che ha generato l'insight. |
content |
Il corpo del messaggio dettagliato o il risultato dell'insight. |
severity |
Il livello di urgenza dell'insight. I valori possibili sono: infowarningerror |
insight_type |
Categorizza l'insight. I valori possibili sono: generalentity |
entity_identifier |
L'identificatore specifico di un'entità se l'insight è incentrato sull'entità. |
additional_data |
Dati supplementari associati all'insight. |
additional_data_type |
La classificazione del tipo di dati per l'attributo |
additional_data_title |
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 |
|---|---|
CRITICAL | 100 |
HIGH | 80 |
INFORMATIONAL | 0 |
LOW | 40 |
MEDIUM | 60 |
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" |
OTHER | Altra |
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" |
OTHER | Altra |
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" |
OTHER | Altra |
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 |
|---|---|
MALICIOUS | 0 |
NOT_MALICIOUS | 1 |
MAINTENANCE | 2 |
INCONCLUSIVE | 3 |
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 |
Il titolo visualizzato per il blocco di contenuti così come appare nell'interfaccia utente dei risultati dello script. |
content |
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 |
L'intestazione visualizzata sopra la tabella dei dati nell'interfaccia della piattaforma. |
data_table |
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 |
L'oggetto entità che viene arricchito con nuovi risultati. |
message |
L'osservazione, il risultato o il messaggio descrittivo principale per l'entità. |
triggered_by |
Il nome dell'integrazione che ha identificato il risultato. |
original_requesting_user |
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 |
|---|---|
COMPLETED | 0 |
IN_PROGRESS | 1 |
FAILED | 2 |
TIMED_OUT | 3 |
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 |
Il titolo visualizzato per il report nella bacheca richieste. |
report_name |
L'identificatore interno o il nome file del report. |
report_contents |
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 |
BOOLEAN | 0 |
INTEGER | 1 |
STRING | 2 |
PASSWORD | 3 |
IP | 4 |
EMAIL | 8 |
class TIPCommon.base.action.data_models.Link
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 | |
|---|---|
title |
Il testo visualizzato per il link ipertestuale. |
link |
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 |
Il titolo visualizzato per il blocco di markdown. |
markdown_content |
I contenuti formattati nella sintassi Markdown. |
markdown_name |
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 |
Il dizionario originale ricevuto dalla risposta dell'API. |
id |
L'identificatore univoco assegnato dalla piattaforma per il parametro. |
creation_time |
Il timestamp che indica quando è stato creato il parametro, in millisecondi Unix. |
modification_time |
Il timestamp che indica l'ultima modifica del parametro, in millisecondi Unix. |
custom_action_id |
L'identificatore dell'azione personalizzata associata a questo parametro. |
is_mandatory |
Indica se il parametro deve essere fornito per l'esecuzione dello script di azione. |
default_value |
Il valore predefinito del parametro. Questo valore ha la priorità su |
description |
La descrizione dettagliata dello scopo del parametro. |
name |
Il nome dell'identificatore interno del parametro. |
value |
Il valore attuale del parametro. Questo valore ha la priorità su |
type |
La classificazione del tipo di dati del parametro. |
optional_values |
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 |
Il titolo visualizzato per il blocco di risultati JSON. |
content |
Contenuti testuali o un riepilogo che accompagna i dati JSON. |
type |
Un tipo di classificazione facoltativo per l'output JSON. |
is_for_entity |
Indica se il risultato JSON è associato specificamente a un'entità. |
json_result |
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 |
Il messaggio di riepilogo principale visualizzato dall'analista. |
result_value |
Il risultato logico dell'azione (ad es. riuscito/non riuscito). |
execution_state |
Lo stato finale del ciclo di vita dell'esecuzione dell'azione. |
json_output |
I risultati JSON strutturati dell'azione. |
debug_output |
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 |
Un elenco di oggetti di avvisi o richieste importati correttamente. |
overflow_alerts |
Un elenco di avvisi che hanno superato i limiti di importazione e sono stati gestiti come overflow. |
log_items |
Un elenco di voci di log strutturate generate durante l'esecuzione del connettore. |
variables |
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 |
I risultati JSON strutturati contenenti i dati di importazione e di log. |
debug_output |
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() |
Autentica l'attributo 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() |
Registra un messaggio con il livello di gravità |
info() |
Registra un messaggio con il livello di gravità |
warn() |
Registra un messaggio con il livello di gravità |
error() |
Registra un messaggio con il livello di gravità |
exception() |
Registra un messaggio con il livello di gravità |
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 |
Un dizionario contenente le intestazioni HTTP da inviare con ogni richiesta nella sessione. |
verify |
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() |
Recupera una risorsa dal server utilizzando una richiesta GET. |
post() |
Invia i dati al server per creare una risorsa utilizzando una richiesta POST HTTP. |
put() |
Aggiorna o crea una risorsa sul server utilizzando una richiesta HTTP PUT. |
patch() |
Applica modifiche parziali a una risorsa utilizzando una richiesta HTTP PATCH. |
delete() |
Rimuove una risorsa specificata dal server utilizzando una richiesta HTTP DELETE. |
request() |
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 |
Fornisce il client API inizializzato o la raccolta di client per l'interazione con i servizi esterni. |
error_msg |
Memorizza eventuali messaggi di errore riscontrati durante l'esecuzione del job per i report diagnostici. |
job_start_time |
Il timestamp Unix che rappresenta l'inizio dell'esecuzione del job. |
logger |
Fornisce l'interfaccia di logging per l'acquisizione di dati informativi, di avviso e di errore durante l'esecuzione. |
name |
Il nome registrato dello script del job. |
params |
Un container contenente i parametri di configurazione specifici forniti all'istanza del job. |
soar_job |
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: 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 |
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 |
Un elenco contenente gli identificatori o gli oggetti elaborati correttamente. |
failure_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 |
Il nome o la chiave del parametro in fase di convalida. |
param_csv_value |
La stringa CSV non elaborata fornita nella configurazione del job. Restituisce un elenco vuoto se |
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 |
Il dizionario originale ricevuto dall'API durante l'inizializzazione del job. |
id |
L'identificatore univoco assegnato dalla piattaforma per il parametro del job. |
is_mandatory |
Indica se il parametro deve essere fornito per l'esecuzione del job. |
name |
Il nome dell'identificatore interno del parametro. |
type |
La classificazione del tipo di dati del parametro. |
value |
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.