MCP Tools Reference: chronicle.googleapis.com

Tool: execute_manual_action

This is the default tool to use when you are asked to perform an action for which there is no straightforward, built-in tool. The system is built with a wide array of integrations, and each integration exposes its own set of custom actions.

When a user asks you to perform an action that you don't immediately recognize, do not say that you can't do it. Instead, you should first query the available actions from the integrations to determine if the requested action is possible. To do this, use the list_integrations and list_integration_actions tools to discover available capabilities. If you find a relevant action, you can then run it using this execute_manual_action tool.

IMPORTANT: Do not assume any of the values from the examples provided in this documentation. You MUST use the available MCP tools (like list_cases, list_case_alerts, list_integrations) to fetch the required IDs and identifiers if they are not provided by the user. If the necessary information cannot be found with other tools, you must ask the user to provide it.

Executes a specific action from a SOAR integration on a given case or alert.

This is a key tool for taking manual or automated response actions, such as blocking an IP, isolating a host, or enriching an entity with threat intelligence. It allows users to trigger capabilities from third-party tools directly within the Chronicle SOAR environment.

Workflow Integration: - A core component of both manual and automated response workflows in Chronicle SOAR. - Integrates with UI elements that allow an analyst to manually run an action on a case, alert, or entity. - Essential for playbooks that need to execute actions from third-party tools (e.g., EDR, firewall, threat intelligence platforms). - Enables the creation of custom response workflows by chaining together different actions to automate complex processes.

Use Cases: - An analyst manually runs a 'block_ip' action from a firewall integration on a malicious IP address found in a case. - A playbook automatically executes an 'isolate_host' action from an EDR integration when a critical malware alert is received. - A user runs a 'get_whois' action from a threat intelligence integration to enrich a suspicious domain entity. - An automated triage process executes a 'create_ticket' action to open a ticket in an external system like Jira or ServiceNow.

IMPORTANT: Special Handling for Script-Based Actions

When executing actions from integrations (e.g. Siemplify or SiemplifyUtilities), the parameters MUST be structured in a specific way:

1. action_provider MUST be "Scripts".

   • Do not use the integration name (e.g., "SiemplifyUtilities") as the provider. The provider is always "Scripts".

2. action_name MUST be prefixed with the integration name.

   • The format is IntegrationName_ActionName.
   • Example: For the "Ping" action in "SiemplifyUtilities", the action_name is "SiemplifyUtilities_Ping".

3. The properties argument is MANDATORY and MUST contain the following keys:

   • ScriptName: The full name of the script, which is the same as the prefixed action_name.
   • Example: "SiemplifyUtilities_Ping"
   • IntegrationInstance: The unique identifier (GUID) for the integration instance. This must be retrieved by first calling list_integrations to find the integration ID, and then calling list_integration_instances with that ID to get the instance GUID.
   • Example: "ec7ade21-27c1-458a-a1a5-417c4b56cb13"
   • ScriptParametersEntityFields: A JSON string representing the parameters for the script itself. If the action takes no parameters (like Ping), this MUST be an empty JSON object represented as a string: "{}".
   • Example for Ping: "{}"
   • Example for an action needing a comment: "{"Comment":"My new comment"}"

Args: project_id (str): Google Cloud project ID (required). customer_id (str): Chronicle customer ID (required). region (str): Chronicle region (e.g., "us", "europe") (required). case_id (int): The identifier of the case where the action is being executed. This is a required field. action_provider (str): The name of the integration that provides the action (e.g., 'VirusTotal', 'MyEDRIntegration'). This is a required field. action_name (str): The name of the action to execute (e.g., 'block_ip', 'isolate_host'). This is a required field. target_entities (list of dict, required): A list of entity objects to run the action on. For actions that do not target a specific entity (like a 'Ping'), you MUST provide an empty list []. properties (dict, optional): A dictionary of parameters required by the action. The keys and values depend on the specific action being executed. scope (str, required): The scope of the action. For actions that apply to all entities, you MUST provide the value "All entities". alert_group_identifiers (list of str, required): A list of alert group identifiers to associate with the action. This field MUST always be provided with a non-empty list of identifiers. is_predefined_scope (bool, required): This flag controls how the action's targets are selected. Set to 'true' if you are using the 'scope' parameter with a predefined value like "All entities". This tells the system to resolve the entities automatically. Set to 'false' if you are providing a specific list of entities in the 'target_entities' parameter.

Returns: ApiActionResultDataModel: A response object containing the result of the executed action. This includes the following key fields: - status (str): The status of the action (e.g., "COMPLETED", "FAILED"). - output (str): Any output or message from the action. - result_id (str): A unique identifier for the result. Returns an error message if the action could not be executed, for example, if the integration is not configured, the parameters are invalid, or the action fails on the third-party tool.

Parameter Gathering Workflow

Before executing an action, you should ask the user if they can provide the required identifiers (case_id, alert_group_identifiers, IntegrationInstance GUID, etc.). If they cannot, you must use the following tools to find them.

1. How to get case_id: - Use the list_cases tool to find the ID of the target case. You can filter by display name, priority, status, and other fields to locate the correct one.

2. How to get alert_group_identifiers: - Use the list_case_alerts tool with the case_id from the previous step. The response will contain a list of alerts, each with an alert_group_identifiers field.

3. How to get IntegrationInstance for script-based actions: - The IntegrationInstance GUID is required in the properties dictionary for script-based actions (where action_provider is 'Scripts'). To get this GUID: 1. Call list_integrations filtering by Identifier (e.g., filter='Identifier="SiemplifyUtilities"') to find the integration. 2. Extract the integration ID from the end of the name field in the result (e.g., 117a4d71-f60a-4a66-a8e0-f2e23a492b40). 3. Call list_integration_instances using this integration ID as the integration_id parameter. 4. Extract the instance GUID from the end of the name field of the desired instance in the list_integration_instances response (e.g., ec7ade21-27c1-4a58-a1a5-417c4b56cb13) and use this for the IntegrationInstance value.

4. Other Parameters: - For other parameters like action_provider, action_name, properties, target_entities, and scope, you may need to ask the user for the correct values if they are not available from other tools.

Example Usage: # Execute a 'block_ip' action on a specific IP address entity execute_manual_action( project_id='123', region='us', customer_id='abc', case_id=456, action_provider='MyFirewallIntegration', action_name='block_ip', target_entities=[ { 'identifier': '198.51.100.10', 'entity_type': 'IP' } ], is_predefined_scope=True )

# Execute an action with parameters
        execute_manual_action(
            project_id='123',
            region='us',
            customer_id='abc',
            case_id=456,
            action_provider='MyTicketingSystem',
            action_name='create_ticket',
            properties={
                'summary': 'Suspicious activity detected on host X',
                'priority': 'High'
            },
            is_predefined_scope=False
        )

        # Execute a script-based action with a target entity
        execute_manual_action(
            project_id='123',
            region='us',
            customer_id='abc',
            case_id=4,
            action_provider='Scripts',
            action_name='Siemplify_Case Comment',
            target_entities=[
                {
                    'Identifier': 'VICTOR',
                    'EntityType': 'USERUNIQNAME',
                    # ... other entity fields
                }
            ],
            properties={
                'ScriptName': 'Siemplify_Case Comment',
                'ScriptParametersEntityFields': '{\"Comment\":\"A new comment\"}',
                'IntegrationInstance': '1cc25d02-4f1b-4575-9884-cdc06cb0384e'
            },
            alert_group_identifiers=['Remote Failed loginmb3gaK8tSe1/yLj6eavhOmBZ4NsyC7c0Wf2WYku0sz8=_d2be7ac9-75d9-48df-831e-0a9794264cd6'],
            is_predefined_scope=False
        )

        # Execute a script-based action like 'Ping' from SiemplifyUtilities with alert group identifiers
        execute_manual_action(
            project_id='123',
            region='us',
            customer_id='abc',
            case_id=4,
            action_provider='Scripts',  # MUST be 'Scripts' for this type of action
            action_name='SiemplifyUtilities_Ping', # MUST be prefixed
            properties={
                'ScriptName': 'SiemplifyUtilities_Ping',
                'IntegrationInstance': 'ec7ade21-27c1-458a-a1a5-417c4b56cb13',
                'ScriptParametersEntityFields': '{}' # Empty JSON string for no params
          },
            scope='All entities',
            alert_group_identifiers=['Remote Failed loginmb3gaK8tSe1/yLj6eavhOmBZ4NsyC7c0Wf2WYku0sz8=_d2be7ac9-75d9-48df-831e-0a9794264cd6'],
            is_predefined_scope=True
        )
        

Next Steps (using MCP-enabled tools): - Use 'get_action_result_by_id' with the returned result ID to check the status and get the full details of an asynchronous action. - Use 'list_case_comments' to see if the action added any comments to the case timeline. - Use 'create_case_comment' to manually add a note about the action that was taken.

The following sample demonstrate how to use curl to invoke the execute_manual_action MCP tool.

Curl Request
curl --location 'https://chronicle.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "execute_manual_action", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }'

Input Schema

Request message for ExecuteManualAction. Next ID: 12

ExecuteManualActionRequest

JSON representation
{ "projectId": string, "customerId": string, "region": string, "caseId": integer, "actionProvider": string, "actionName": string, "targetEntities": [ { object (LegacyCaseApiSecurityEntityDataModel) } ], "properties": { string: string, ... }, "scope": string, "alertGroupIdentifiers": [ string ], "isPredefinedScope": boolean }

Fields
projectId	string Project ID of the customer.
customerId	string Customer ID of the customer.
region	string Region of the customer.
caseId	integer Case ID.
actionProvider	string Action provider.
actionName	string Action name.
targetEntities[]	object (LegacyCaseApiSecurityEntityDataModel) Target entities.
properties	map (key: string, value: string) Properties. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
scope	string Scope.
alertGroupIdentifiers[]	string Alert group identifiers.
isPredefinedScope	boolean Whether the scope is predefined.

LegacyCaseApiSecurityEntityDataModel

JSON representation

{ "caseId": string, "identifier": string, "entityType": string, "environment": string, "fields": [ { object (LegacyCaseContextGroupDataModel) } ], "sourceUrl": string, // Union field _is_internal can be only one of the following: "isInternal": boolean // End of list of possible types for union field _is_internal. // Union field _is_suspicious can be only one of the following: "isSuspicious": boolean // End of list of possible types for union field _is_suspicious. // Union field _is_artifact can be only one of the following: "isArtifact": boolean // End of list of possible types for union field _is_artifact. // Union field _is_enriched can be only one of the following: "isEnriched": boolean // End of list of possible types for union field _is_enriched. // Union field _is_vulnerable can be only one of the following: "isVulnerable": boolean // End of list of possible types for union field _is_vulnerable. // Union field _is_pivot can be only one of the following: "isPivot": boolean // End of list of possible types for union field _is_pivot. // Union field _is_manually_created can be only one of the following: "isManuallyCreated": boolean // End of list of possible types for union field _is_manually_created. }

Fields
caseId	string (int64 format) Optional. CaseId is the ID of the case.
identifier	string Optional. Identifier is the identifier of the entity.
entityType	string Optional. EntityType is the type of the entity.
environment	string Optional. Environment is the environment of the entity.
fields[]	object (LegacyCaseContextGroupDataModel) Optional. Fields is a list of context group data models.
sourceUrl	string Optional. SourceUrl is the source URL of the entity.
Union field _is_internal. _is_internal can be only one of the following:
isInternal	boolean Optional. IsInternal indicates if the entity is internal.
Union field _is_suspicious. _is_suspicious can be only one of the following:
isSuspicious	boolean Optional. IsSuspicious indicates if the entity is suspicious.
Union field _is_artifact. _is_artifact can be only one of the following:
isArtifact	boolean Optional. IsArtifact indicates if the entity is an artifact.
Union field _is_enriched. _is_enriched can be only one of the following:
isEnriched	boolean Optional. IsEnriched indicates if the entity is enriched.
Union field _is_vulnerable. _is_vulnerable can be only one of the following:
isVulnerable	boolean Optional. IsVulnerable indicates if the entity is vulnerable.
Union field _is_pivot. _is_pivot can be only one of the following:
isPivot	boolean Optional. IsPivot indicates if the entity is a pivot.
Union field _is_manually_created. _is_manually_created can be only one of the following:
isManuallyCreated	boolean Optional. IsManuallyCreated indicates if the entity was manually created.

LegacyCaseContextGroupDataModel

JSON representation
{ "groupName": string, "items": [ { object (LegacyCaseContextStringItemDataModel) } ], // Union field _is_highlight can be only one of the following: "isHighlight": boolean // End of list of possible types for union field _is_highlight. // Union field _hide_options can be only one of the following: "hideOptions": boolean // End of list of possible types for union field _hide_options. }

Fields
groupName	string Optional. GroupName is the name of the context group.
items[]	object (LegacyCaseContextStringItemDataModel) Optional. Items is a list of context string items.
Union field _is_highlight. _is_highlight can be only one of the following:
isHighlight	boolean Optional. IsHighlight indicates if the context group is highlighted.
Union field _hide_options. _hide_options can be only one of the following:
hideOptions	boolean Optional. hideOptions indicates if the options are hidden.

LegacyCaseContextStringItemDataModel

JSON representation
{ "originalName": string, "name": string, "value": string }

Fields
originalName	string Optional. OriginalName is the original name of the context string item.
name	string Optional. Name is the name of the context string item.
value	string Optional. Value is the value of the context string item.

PropertiesEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

Output Schema

ApiActionResultDataModel represents the result of an API action.

ApiActionResultDataModel

JSON representation

{ "id": string, "executingUser": string, "providerIdentifier": string, "integration": string, "actionIdentifier": string, "caseId": string, "entityIdentifier": string, "message": string, "resultJsonObject": string, "targetedEntitiesJsonObject": string, "resultEntitiesJsonObject": string, "resultValue": string, "resultName": string, "properties": { string: string, ... }, "indicatorIdentifier": string, "workflowId": string, "workflowStep": string, "workflowStepInstanceName": string, "integrationInstanceIdentifier": string, "integrationInstanceName": string, "integrationInstanceEnvironment": string, "alertDisplayName": string, "scriptResultEntityData": [ { object (ScriptResultEntityData) } ], "parameters": [ { object (WidgetApiWorkflowStepParameterDataModel) } ], "blockStepId": string, "creationTimeUnixTimeInMs": string, "executionTimeMs": string, "firstResultUnixTime": string, "modificationTimeUnixTimeInMs": string, "propertiesSerializableDictionary": { string: string, ... }, "startLoopStepIdentifier": string, "tenantId": string, "workflowInstanceId": string, // Union field _action_category can be only one of the following: "actionCategory": enum (ActionCategoryEnum) // End of list of possible types for union field _action_category. // Union field _should_create_activity can be only one of the following: "shouldCreateActivity": boolean // End of list of possible types for union field _should_create_activity. // Union field _result_code can be only one of the following: "resultCode": integer // End of list of possible types for union field _result_code. // Union field _is_favorite can be only one of the following: "isFavorite": boolean // End of list of possible types for union field _is_favorite. // Union field _status can be only one of the following: "status": enum (ActionStatusEnum) // End of list of possible types for union field _status. // Union field _is_async_polling_result can be only one of the following: "isAsyncPollingResult": boolean // End of list of possible types for union field _is_async_polling_result. // Union field _is_skipped_and_not_executed can be only one of the following: "isSkippedAndNotExecuted": boolean // End of list of possible types for union field _is_skipped_and_not_executed. // Union field _is_start_loop_step_result can be only one of the following: "isStartLoopStepResult": boolean // End of list of possible types for union field _is_start_loop_step_result. // Union field _loop_iteration can be only one of the following: "loopIteration": integer // End of list of possible types for union field _loop_iteration. }

Fields
id	string (int64 format) Required. Id is the unique identifier of the action result.
executingUser	string Optional. ExecutingUser is the user who executed the action.
providerIdentifier	string Optional. ProviderIdentifier is the identifier of the action provider.
integration	string Optional. Integration is the name of the integration.
actionIdentifier	string Optional. ActionIdentifier is the identifier of the action.
caseId	string (int64 format) Optional. CaseId is the ID of the case associated with the action.
entityIdentifier	string Optional. EntityIdentifier is the identifier of the entity associated with the action.
message	string Optional. Message is the message associated with the action result.
resultJsonObject	string Optional. ResultJsonObject is the result JSON object.
targetedEntitiesJsonObject	string Optional. TargetedEntitiesJsonObject is the targeted entities JSON object.
resultEntitiesJsonObject	string Optional. ResultEntitiesJsonObject is the result entities JSON object.
resultValue	string Optional. ResultValue is the result value.
resultName	string Optional. ResultName is the name of the result.
properties	map (key: string, value: string) Optional. Properties is a map of properties. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
indicatorIdentifier	string Optional. IndicatorIdentifier is the identifier of the indicator.
workflowId	string Optional. WorkflowId is the ID of the workflow.
workflowStep	string Optional. WorkflowStep is the ID of the workflow step.
workflowStepInstanceName	string Optional. WorkflowStepInstanceName is the name of the workflow step instance.
integrationInstanceIdentifier	string Optional. IntegrationInstanceIdentifier is the identifier of the integration instance.
integrationInstanceName	string Optional. IntegrationInstanceName is the name of the integration instance.
integrationInstanceEnvironment	string Optional. IntegrationInstanceEnvironment is the environment of the integration instance.
alertDisplayName	string Optional. AlertDisplayName is the display name of the alert.
scriptResultEntityData[]	object (ScriptResultEntityData) Optional. ScriptResultEntityData is a list of script result entity data.
parameters[]	object (WidgetApiWorkflowStepParameterDataModel) Optional. Parameters is a list of workflow step parameters.
blockStepId	string Optional. BlockStepId is the ID of the block step.
creationTimeUnixTimeInMs	string (int64 format) Optional. CreationTimeUnixTimeInMs is the creation time of the action result in milliseconds since the Unix epoch.
executionTimeMs	string (int64 format) Optional. ExecutionTimeMs is the execution time of the action in milliseconds since the Unix epoch.
firstResultUnixTime	string (int64 format) Optional. FirstResultUnixTime is the time of the first result in milliseconds since the Unix epoch.
modificationTimeUnixTimeInMs	string (int64 format) Optional. ModificationTimeUnixTimeInMs is the modification time of the action result in milliseconds since the Unix epoch.
propertiesSerializableDictionary	map (key: string, value: string) Optional. PropertiesSerializableDictionary is a map of properties. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
startLoopStepIdentifier	string Optional. StartLoopStepIdentifier is the ID of the start loop step.
tenantId	string Optional. TenantId is the ID of the tenant.
workflowInstanceId	string (int64 format) Optional. WorkflowInstanceId is the ID of the workflow instance.
Union field _action_category. _action_category can be only one of the following:
actionCategory	enum (ActionCategoryEnum) Optional. ActionCategory is the category of the action.
Union field _should_create_activity. _should_create_activity can be only one of the following:
shouldCreateActivity	boolean Optional. ShouldCreateActivity indicates whether an activity should be created.
Union field _result_code. _result_code can be only one of the following:
resultCode	integer Optional. ResultCode is the result code of the action.
Union field _is_favorite. _is_favorite can be only one of the following:
isFavorite	boolean Optional. IsFavorite indicates whether the action result is a favorite.
Union field _status. _status can be only one of the following:
status	enum (ActionStatusEnum) Optional. Status is the status of the action result.
Union field _is_async_polling_result. _is_async_polling_result can be only one of the following:
isAsyncPollingResult	boolean Optional. IsAsyncPollingResult indicates if the result is an async polling result.
Union field _is_skipped_and_not_executed. _is_skipped_and_not_executed can be only one of the following:
isSkippedAndNotExecuted	boolean Optional. IsSkippedAndNotExecuted indicates if the action is skipped and not executed.
Union field _is_start_loop_step_result. _is_start_loop_step_result can be only one of the following:
isStartLoopStepResult	boolean Optional. IsStartLoopStepResult indicates if the result is a start loop step result.
Union field _loop_iteration. _loop_iteration can be only one of the following:
loopIteration	integer Optional. LoopIteration is the loop iteration number.

PropertiesEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

ScriptResultEntityData

JSON representation

{ "title": string, "type": string, "csvLines": [ string ], "attachments": { string: string, ... }, "htmls": { string: string, ... }, "links": [ string ], "content": string, "rawJson": string, "entity": string, "markdowns": { string: string, ... }, // Union field _is_for_entity can be only one of the following: "isForEntity": boolean // End of list of possible types for union field _is_for_entity. }

Fields
title	string Output only. The title of the result entity data.
type	string Output only. The type of the result entity data.
csvLines[]	string Output only. The csv lines of the result entity data.
attachments	map (key: string, value: string) Output only. The attachments of the result entity data. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
htmls	map (key: string, value: string) Output only. The htmls of the result entity data. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
links[]	string Output only. The links of the result entity data.
content	string Output only. The content of the result entity data.
rawJson	string Output only. The raw json of the result entity data.
entity	string Output only. The entity of the result entity data.
markdowns	map (key: string, value: string) Output only. The markdowns of the result entity data. An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
Union field _is_for_entity. _is_for_entity can be only one of the following:
isForEntity	boolean Output only. The flag that indicates whether the result entity data is for entity.

AttachmentsEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

HtmlsEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

MarkdownsEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

WidgetApiWorkflowStepParameterDataModel

JSON representation
{ "name": string, "value": string, "defaultValue": string, // Union field _type can be only one of the following: "type": enum (CustomActionParameterType) // End of list of possible types for union field _type. // Union field _is_mandatory can be only one of the following: "isMandatory": boolean // End of list of possible types for union field _is_mandatory. }

Fields
name	string Output only. The name of the parameter.
value	string Output only. The value of the parameter.
defaultValue	string Output only. The default value of the parameter.
Union field _type. _type can be only one of the following:
type	enum (CustomActionParameterType) Output only. The type of the parameter.
Union field _is_mandatory. _is_mandatory can be only one of the following:
isMandatory	boolean Output only. Whether the parameter is mandatory.

PropertiesSerializableDictionaryEntry

JSON representation
{ "key": string, "value": string }

Fields
key	string
value	string

Tool Annotations

Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ❌