MCP Tools Reference: chronicle.googleapis.com

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.

Tool Annotations

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