TIPCommon.base

TIPCommon.base.action.action_parser.parse_case_attachment

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

Parses a JSON attachment and returns a CaseAttachment object.

Parameters

Returns

The parsed CaseAttachment object.

Return type

CaseAttachment

TIPCommon.base.action.action_parser.parse_case_comment

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

Parses a JSON comment and returns a CaseComment object.

Parameters

Returns

The parsed CaseComment object.

Return type

CaseComment

class TIPCommon.base.action.base_action.Action

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

Bases: ABC, Generic[ApiClient]

A unified generic infrastructure implementation for the Google SecOps action development.

The Action base class provides template abstract methods to override in the inherited action classes, generic properties, and general flows as methods that are executed when calling the action's run method.

Parameters

Attributes

Methods

Abstract methods

Additional methods

These are methods that are called during the action execution and affect the alerts processing phase but are not mandatory to override.

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

SDK wrapper methods

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

Example

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

property action_start_time

property action_start_time: int

Returns an int representing the action starting time in Unix.

property api_client

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

Returns an Apiable object.

property attachments

property attachments: list[Attachment]

All the attachments in the list are sent to the case result by default.

Returns a list of Attachment objects representing the insights for this case.

property case_insights

property case_insights: list[CaseInsight]

All the case insights in the list are sent to the case result by default.

Returns a list of CaseInsight objects representing the insights for this case.

property contents

property contents: list[Content]

All list contents are sent to the case result by default.

Returns a list of Content objects representing the insights for this case.

property data_tables

property data_tables: list[DataTable]

By default, all data tables in the list are sent to the case result.

Returns a list of DataTable objects representing the insights for this case.

property entities_to_update

property entities_to_update: list[DomainEntityInfo]

All entities in the list are sent to the platform for updating.

Returns a list of Entity objects representing the entities that should be updated in the case.

property entity_insights

property entity_insights: list[EntityInsight]

All entity insights in the list are sent to the case result by default.

Returns a list of EntityInsight objects representing the insights for this case.

property entity_types

property entity_types: list[EntityTypesEnum]

If the action works with entities, it only processes entities whose type is in the entity_types list. Otherwise, the action skips the entity.

Returns a list of EntityTypesEnum objects representing entity types the action can process.

property error_output_message

property error_output_message: str

The action output message in case of a failed run.

An output message that should appear in case of a failure during the action runtime. Default value is ActionSCRIPT_NAMEfailed.

property execution_state

property execution_state: ExecutionState

The action's execution state—a status indicator represented by an integer to pass back to the platform.

Possible statuses are as follows:

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

Returns the ExecutionState object representing the current execution state.

property html_reports

property html_reports: list[HTMLReport]

All the HTML reports in the list will be sent to the case result by default.

Returns a list of HTMLReport objects representing the insights for this case.

property is_first_run

property is_first_run: bool

Indicates whether this is the first run.

Returns:

True if this is the first run, False otherwise.

property json_results

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

Returns the action's JSON result to be sent to the case wall.

property links

property links: list[Link]

All the links in the list will be sent to the case result by default.

Returns a list of Link objects representing the insights for this case.

property logger

property logger: NewLineLogger

Returns the NewLineLogger object for actions.

property name

property name: str

property output_message

property output_message: str

The action's output message in case of a successful run.

The output message that summarizes the result of the action.

property params

property params: [Container]

Returns a Container object that describes the action's parameters, with each parameter exposed as a snake_case attribute.

property result_value

property result_value: bool

The action's result value to be passed back to the platform.

Possible values:

• True: Action Succeeded
• False: Action Failed

property soar_action

property soar_action: SiemplifyAction

Returns the SDK SiemplifyAction object.

class TIPCommon.base.action.base_enrich_action.EnrichAction

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

Bases: Action

A class that represents an entity enrichment action.

This class inherits from the TIPCommon.base.actions.base_action::Action class.

Parameters

Attributes

Abstract methods

Private methods

class TIPCommon.base.action.data_models.ActionParamType

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

Bases: Enum

Constants

• 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

An action script-result attachment.

This class is immutable: once created, its attributes cannot be modified. It supports hashing (for example, use in sets or as dictionary keys) and equality comparison using the == operator.

Attributes

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

A case attachment.

This class is immutable; after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

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

A case comment.

This class is immutable; after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

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

A case insight.

This class is immutable: after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

class TIPCommon.base.action.data_models.CasePriority

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

Bases: Enum

Constants

• 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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Constants

• ASSESSMENT = 'Assessment'

• IMPROVEMENT = 'Improvement'

• INCIDENT = 'Incident'

• INVESTIGATION = 'Investigation'

• RESEARCH = 'Research'

• TRIAGE = 'Triage'

class TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses

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

Bases: Enum

Constants

• NO_CLEAR_CONCLUSION = 'No clear conclusion'

class TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses

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

Bases: Enum

Constants

• LAB_TEST = 'Lab test'

• OTHER = 'Other'

• RULE_UNDER_CONSTRUCTION = 'Rule under construction'

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

Constants

• EXTERNAL_ATTACK = 'External attack'

• INFRASTRUCTURE_ISSUE = 'Infrastructure issue'

• IRRELEVANT_TCP_UDP_PORT = 'Irrelevant TCP/UDP port'

• MISCONFIGURED_SYSTEM = 'Misconfigured system'

• OTHER = 'Other'

• SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION = 'Similar case is already under investigation'

• SYSTEM_APPLICATION_MALFUNCTION = 'System/application malfunction'

• SYSTEM_CLOCKED_THE_ATTACK = 'System blocked the attack'

• UNFORESEEN_EFFECTS_OF_CHANGE = 'Unforeseen effects of change'

• 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

Constants

• EMPLOYEE_ERROR = 'Employee error'

• HUMAN_ERROR = 'Human error'

• LAB_TEST = 'Lab test'

• LEGIT_ACTION = 'Legit action'

• MISCONFIGURED_SYSTEM = 'Misconfigured system'

• NONE = 'None'

• NORMAL_BEHAVIOR = 'Normal behavior'

• OTHER = 'Other'

• PENETRATION_TEST = 'Penetration test'

• RULE_UNDER_CONSTRUCTION = 'Rule under construction'

• SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION = 'Similar case is already under investigation'

• UNKNOWN = 'Unknown'

• USER_MISTAKE = 'User mistake'

class TIPCommon.base.action.data_models.CloseCaseOrAlertReasons

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

Bases: Enum

### Constants

• INCONCLUSIVE = 3

• MAINTENANCE = 2

• MALICIOUS = 0

• NOT_MALICIOUS = 1

class TIPCommon.base.action.data_models.Content

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

Bases: object

An action script-result content.

This class is immutable: after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the ==operator.

Attributes

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

An action script-result data table.

This class is immutable; after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

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

An entity insight.

This class is immutable: after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

class TIPCommon.base.action.data_models.EntityTypesEnum

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

Bases: Enum

Constants

• 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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Constants

• COMPLETED = 0

• FAILED = 2

• IN_PROGRESS = 1

• TIMED_OUT = 3

class TIPCommon.base.action.data_models.FullDetailsConfigurationParameter

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

Bases: object

A general script parameter object.

Attributes

class TIPCommon.base.action.data_models.HTMLReport

class TIPCommon.base.action.data_models.HTMLReport(report_name: str, report_contents: str, title: str = 'Script Result HTML Report')

Bases: object

An action script-result link.

This class is immutable: after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

class TIPCommon.base.action.data_models.IntegrationParamType

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

Bases: Enum

Constants

• BOOLEAN = 0

• EMAIL = 8

• INTEGER = 1

• IP = 4

• NULL = -1

• PASSWORD = 3

• STRING = 2

class TIPCommon.base.action.data_models.Link

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

Bases: object

An action script-result link.

This class is immutable: after assigning values and creating the object, new values cannot be assigned to the attributes. The class supports hashing (stored in a set or as a dict key) and the == operator.

Attributes

class TIPCommon.base.action.data_models.ScriptParameter

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

Bases: object

A general script parameter object.

Attributes

class TIPCommon.base.interfaces.apiable.Apiable

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

Bases: ABC, Generic[ApiParams]

An interface for classes that manage API calls to external services.

class TIPCommon.base.interfaces.authable.Authable

class TIPCommon.base.interfaces.authable.Authable

Bases: ABC, Generic[AuthParams]

An interface for classes that manage authentication with external services.

Abstract methods

Attributes

class TIPCommon.base.interfaces.logger.Logger

class TIPCommon.base.interfaces.logger.Logger

Bases: ABC

A logger interface designed for marketplace scripts, verifying compatibility when the passed logger is replaced or mocked.

Abstract methods

class TIPCommon.base.interfaces.session.Session

class TIPCommon.base.interfaces.session.Session

Bases: ABC, Generic[_R]

This class manages API sessions using a session object. It supports various session types and mocks with libraries like requests or httpx.

Attributes

Abstract methods

class TIPCommon.base.job.base_job.Job

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

Bases: ABC, Generic[ApiClient]

A class that represents a job script in Google Security Operations SOAR.

Methods

• start(**kwargs) → None

property api_client

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

Provides the API client or clients for interacting with external services.

property error_msg

property error_msg: str

Stores any error message encountered during the job's execution.

property job_start_time

property job_start_time: int

Represents the timestamp when the job started.

property logger

property logger: ScriptLogger

Provides logging functionality for the job script.

property name

property name: str

Holds the name of the job script.

property params

property params: Container

Contains the configuration parameters provided to the job.

property soar_job

property soar_job: SiemplifyJob

Represents the underlying Google Security Operations SOAR job instance.

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]

This section describes lifecycle methods that influence job processing. Subclasses are not required to override them.

property api_client

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

Holds the API client or clients used for external service interactions.

class TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

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

Bases: tuple

Attributes

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: str, param_csv_value: str | None, delimiter: str = ',') → list[str]

Validates and parses a comma-separated parameter value into a list of unique elements. This function handles single values, quoted strings and mixed formats.

Parameters

Raises

ValueError – When the double quotes count is invalid, some values are invalid, or some values have mismatched double quotes.

Returns

A list of unique values provided in the job parameter. If no valid values are found, an empty list is returned.

Return type

list[str]

class TIPCommon.base.job.data_models.JobParameter

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

Bases: object

A general script parameter object.

Attributes

class TIPCommon.base.data_models.ActionJsonOutput

class TIPCommon.base.data_models.ActionJsonOutput(title: 'str' = 'JsonResult', content: 'str' = '', type: 'str | None' = None, is_for_entity: 'bool' = False, json_result: 'JSON | None' = None)

Bases: object

Represents the structured JSON output for an action.

class TIPCommon.base.data_models.ActionOutput

class TIPCommon.base.data_models.ActionOutput(output_message: 'str', result_value: 'str | bool', execution_state: 'ExecutionState', json_output: 'ActionJsonOutput | None', debug_output: 'str' = '')

Bases: object

Represents the complete output structure for an action.

class TIPCommon.base.data_models.ConnectorJsonOutput

class TIPCommon.base.data_models.ConnectorJsonOutput(alerts: 'list[AlertInfo | CaseInfo]', overflow_alerts: 'list[OverflowAlertDetails]' = <factory>, log_items: 'list' = <factory>, log_rows: 'list[str]' = <factory>, variables: 'dict' = <factory>)

Bases: object

Represents the structured JSON output for a connector.

class TIPCommon.base.data_models.ConnectorOutput

class TIPCommon.base.data_models.ConnectorOutput(json_output: 'ConnectorJsonOutput | None', debug_output: 'str' = '')

Bases: object

Represents the complete output structure for a connector.

TIPCommon.base.data_models.alert_info_from_json

TIPCommon.base.data_models.alert_info_from_json(json_: MutableMapping[str, Any])→ AlertInfo

Creates an AlertInfo object from a JSON of attributes.

Returns

The created AlertInfo object.

Return type

AlertInfo

Need more help? Get answers from Community members and Google SecOps professionals.