MCP Reference: chronicle.googleapis.com

A Model Context Protocol (MCP) server acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

Chronicle API provides tools for security analysts to investigate and mitigate threats.

Server Endpoints

An MCP service endpoint is the network address and communication interface (usually a URL) of the MCP server that an AI application (the Host for the MCP client) uses to establish a secure, standardized connection. It is the point of contact for the LLM to request context, call a tool, or access a resource.

The chronicle.googleapis.com MCP server uses [regional endpoints](/chronicle/docs/reference/rest?rep_location=africa-south1#regional-service-endpoint):

  • For example, https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp

MCP Tools

An MCP tool is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

The chronicle.googleapis.com MCP server has the following tools:

MCP Tools
get_case

Retrieves a single case by its resource name.

Fetches all details for a specific case, including its properties (such as priority, stage, and assignee), as well as any associated tasks, tags, and products. This tool is fundamental for drilling down into a specific incident after identifying it through a list view or search.

CRITICAL INSTRUCTION: When using this tool, you MUST ALWAYS also call the list_case_alerts tool for the same case ID to fetch the associated alerts. You must then synthesize the information from both tools to provide a comprehensive response. The response should include case details, associated alerts, and a summary of comments if available.

Here are the details for Case ID [Case ID]:

Case Details:

Name: [Name] Display Name: [Display Name] Status: [Status] Stage: [Stage] Priority: [Priority] Assignee: [Assignee] Last Modifying User ID: [Last Modifying User ID] Created Time: [Create Time] Updated Time: [Update Time] Alert Count: [Alert Count (calculate from list_case_alerts)] Important: [Important] Incident: [Incident] Type: [Type] Overflow Case: [Overflow Case] Environment: [Environment] Workflow Status: [Workflow Status] Source: [Source] Involved Suspicious Entity: [Involved Suspicious Entity] Move Environment: [Move Environment]

Associated Alerts:

Alert ID: [Alert ID] Display Name: [Alert Display Name] Rule Generator: [Rule Generator] Product: [Product] Vendor: [Vendor] Source System: [Source System (if available)] Priority: [Priority] Status: [Status] Start Time: [Start Time (if available)] End Time: [End Time (if available)] Source URL: [Source URL (if available)]

Comments: There are [Number of comments] comments associated with this case, including notes about [Topic 1], [Topic 2], and entries like "[Comment Snippet]" by [Author].

Example: There are 23 comments associated with this case, including notes about Meta-Analysis Reports, Triage Reports, and entries like "OneMCP works!" by Soary Siem.

Workflow Integration: - Used when an analyst clicks on a case in a queue or dashboard to view its full details in an investigation UI. - Essential for automated playbooks that need to retrieve the current state of a case before taking action, such as enrichment or remediation. - Provides the necessary data to populate a case investigation screen, showing all relevant information in one place. - Can be used to verify the result of an update operation by fetching the case after the update has been applied.

Use Cases: - An analyst retrieves a case to begin an investigation and understand its context. - An automated system fetches a case to extract entities for further enrichment from other threat intelligence sources. - A manager views a case to review its progress, check the SLA status, and see the latest comments. - A reporting script fetches case details to generate a detailed incident report.

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 (str): The numeric ID of the Case to retrieve (e.g., '12345'). This is a required field. expand (str, optional): A comma-separated list of related resources to include in the response. This allows you to get a more complete picture of the case in a single call. Supported values: 'tasks', 'tags', 'products'.

Returns: Case: The full Case object with all its details. If the 'expand' parameter is used, the corresponding related resources will be included. The Case object contains the following key fields: - Name (str): The full resource name of the case. - Id (int): The unique identifier for the case. - DisplayName (str): The title or display name of the case. - Stage (str): The current stage of the case (e.g., "Triage", "Investigation"). - Priority (str): The priority of the case (e.g., "PRIORITY_HIGH"). - Assignee (str): The user or group assigned to the case. - Description (str): A detailed description of the case. - Status (str): The current status of the case (e.g., "OPENED", "CLOSED"). - CreateTime (int): The creation timestamp of the case in milliseconds. - UpdateTime (int): The last update timestamp of the case in milliseconds. - Tags (list of str): A list of tags associated with the case. - Products (list of str): A list of products associated with the case. Returns an error message if the case is not found or the user does not have permission to view it.

Example Usage: # Get basic details for a specific case (and automatically fetch alerts as per instruction) get_case(project_id='123', region='us', customer_id='abc', case_id='456')

# Get a case and include its associated tasks and tags
get_case(project_id='123', region='us', customer_id='abc', case_id='456', expand='tasks,tags')

Next Steps (using MCP-enabled tools): - Use 'list_case_alerts' to fetch the details of all alerts associated with this case. - Use 'list_case_comments' to see the full history of comments and actions taken on the case.
list_case_comments

Lists all case comments for a given case in Google SecOps.

Retrieves a paginated list of all comments associated with a specific SOAR case, allowing for a comprehensive overview of the investigation history. This tool is essential for understanding the timeline of a case, reviewing actions taken, and gathering context from analyst notes.

Workflow Integration: - Used to build a complete timeline of an investigation in a SOAR UI or report. - Essential for generating audit trails or summaries of case activity for compliance or review. - Enables analysts to programmatically search and filter through all comments to find relevant information, such as notes from a specific user or comments made during a certain time frame. - Provides the necessary context for automated playbooks to make decisions based on the history of a case.

Use Cases: - Generate a complete audit trail of all actions and notes for a specific case to understand the investigation process. - Find a specific comment by filtering based on the user who wrote it, its content, or other metadata. - Display a chronological history of comments on a case detail page in a custom security dashboard. - Automate the process of reviewing cases by searching for keywords in comments.

Filtering and Ordering: - The 'filter' parameter allows for precise searching within comments. You can filter on fields like 'user', 'comment' content, 'create_time', and more. - The 'order_by' parameter controls the sorting of the returned comments. You can sort by fields like 'create_time' or 'update_time' in ascending or descending order.

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 (str): The numeric Case ID to list comments for (e.g., '12345'). This is a required field. page_size (int, optional): The maximum number of comments to return in a single response. If unspecified, the server will use a default page size. The maximum value is 1000. page_token (str, optional): A token for fetching a specific page of results. This is obtained from a previous call to list_case_comments. filter (str, optional): A filter string to apply to the list of comments. Supported fields include 'CreateTime', 'UpdateTime', 'User', 'Comment', 'DeletedByUser', 'IsFavorite', 'AlertIdentifier', and 'IsDeleted'. Example: filter="User='GUID' AND Comment='suspicious'" order_by (str, optional): A comma-separated list of fields to sort the results by. Add 'desc' for descending order. Supported fields are the same as for filtering. Example: "CreateTime desc"

Returns: ListCaseCommentsResponse: A response object containing a list of CaseComment objects and a next_page_token if more results are available. Each CaseComment object contains the following key fields: - Name (str): The full resource name of the comment. - Id (int): The unique identifier for the comment. - Comment (str): The content of the comment. - UserOwnerFullName (str): The full name of the user who created the comment. - LastEditorFullName (str): The full name of the user who last edited the comment. - CreateTime (int): The creation timestamp of the comment in milliseconds. - UpdateTime (int): The last update timestamp of the comment in milliseconds. - IsFavorite (bool): Indicates if the comment is marked as a favorite. - IsDeleted (bool): Indicates if the comment has been deleted. - AlertIdentifier (str): The identifier of the alert associated with the comment, if any. Returns an error message if the parent case is not found or the request is invalid.

Example Usage: # List all comments for a specific case list_case_comments(project_id='123', region='us', customer_id='abc', case_id='456')

# List comments from a specific user, sorted by update time
list_case_comments(project_id='123', region='us', customer_id='abc', case_id='456', filter="user='user@example.com'", order_by="update_time desc")

Next Steps (using MCP-enabled tools): - Iterate through the list of comments to extract key information or indicators. - Use 'create_case_comment' to add a new comment to the case based on your findings. - Use 'get_case_comment' with a comment's resource name to fetch its full details if needed.
list_cases

Lists all cases for a given Chronicle instance.

Retrieves a paginated list of all cases, allowing for a comprehensive overview of security incidents and investigations. This tool is essential for security operations, enabling analysts and managers to view, filter, and prioritize cases based on various criteria.

Workflow Integration: - Used to populate a case queue or dashboard in a security management UI, providing a real-time view of the incident landscape. - Essential for generating reports on case metrics, such as case volume, time to resolution, and analyst workload. - Enables automated systems to query for specific types of cases that may require automated enrichment or triage actions. - Provides the foundational data for building custom analytics and visualizations on top of Chronicle's case management system.

Use Cases: - An analyst lists all open cases assigned to them to prioritize their daily workload. - A SOC manager generates a report of all critical-priority cases created in the last week. - An automated playbook queries for all new cases related to a specific environment to begin an automated investigation. - Search for all cases with a specific tag to track a particular threat campaign.

Filtering and Ordering: - The 'filter' parameter allows for powerful, SQL-like queries to narrow down the list of cases. You can filter on fields like 'display_name', 'assignee', 'priority', 'stage', 'status', 'tags', 'products', 'environment', 'important', 'incident', 'description', 'CreateTime', 'UpdateTime', and more. - The Priority options are: ['PRIORITY_UNSPECIFIED', 'PRIORITY_INFO', 'PRIORITY_LOW', 'PRIORITY_MEDIUM', 'PRIORITY_HIGH', 'PRIORITY_CRITICAL']. - The Stage options are: ['Research', 'Improvement', 'Incident', 'Investigation', 'Assessment', 'Triage']. - The Status options are: ['OPENED', 'CLOSED']. - The 'CreateTime' and 'UpdateTime' fields are Unix timestamps in milliseconds and can be filtered using comparison operators (e.g., '>', '<', '>=', '<='). - The 'order_by' parameter controls the sorting of the returned cases. You can sort by fields like 'CreateTime', 'priority', or 'UpdateTime' in ascending or descending order.

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). page_size (int, optional): The maximum number of cases to return in a single response. The default is 50, and the maximum is 1000. page_token (str, optional): A token for fetching a specific page of results, obtained from a previous call. filter (str, optional): A filter string to apply to the list of cases. Supported fields include 'DisplayName', 'Assignee', 'Priority', 'Stage', 'Status', 'Tags', 'Products', 'Environment', 'CreateTime', 'UpdateTime', and more. Example: "Priority='PRIORITY_CRITICAL' AND Status='OPENED'" order_by (str, optional): A comma-separated list of fields to sort the results by. Add 'desc' for descending order. Example: "Priority desc, CreateTime asc" expand (str, optional): A comma-separated list of related resources to include in the response. Supported values: 'tasks', 'tags', 'products'.

Returns: ListCasesResponse: A response object containing a list of Case objects and a next_page_token if more results are available. Each Case object contains the following key fields: - Name (str): The full resource name of the case. - Id (int): The unique identifier for the case. - DisplayName (str): The title or display name of the case. - Stage (str): The current stage of the case (e.g., "Triage", "Investigation"). - Priority (str): The priority of the case (e.g., "PRIORITY_HIGH"). - Assignee (str): The user or group assigned to the case. - Description (str): A detailed description of the case. - Status (str): The current status of the case (e.g., "OPENED", "CLOSED"). - CreateTime (int): The creation timestamp of the case in milliseconds. - UpdateTime (int): The last update timestamp of the case in milliseconds. - Tags (list of str): A list of tags associated with the case. - Products (list of str): A list of products associated with the case. Returns an error message if the parent instance is not found or the request is invalid.

Example Usage: # List the first 10 cases for a specific instance list_cases(project_id='123', region='us', customer_id='abc', page_size=10)

# List all critical priority cases, sorted by their creation time
list_cases(project_id='123', region='us', customer_id='abc', filter="priority='PRIORITY_CRITICAL'", order_by="CreateTime desc")

# To list cases created in the last hour, filter by CreateTime using a unix timestamp in milliseconds for 1 hour ago, for example:
# list_cases(project_id='123', region='us', customer_id='abc', filter="CreateTime > 1730801400000")

Next Steps (using MCP-enabled tools): - Iterate through the list of cases to perform bulk operations or analysis. - Use 'get_case' with a case's resource name to fetch its full details. - Use 'update_case' to modify the properties of a specific case, such as its assignee or stage. - Use 'list_case_comments' to retrieve the discussion and history for a particular case.
update_case

Updates an existing case in Google SecOps.

Modifies various properties of a specific case. Only the fields provided in the arguments will be updated. Note: It is not possible to change the status of a case to 'CLOSED' using this tool. This can only be done via the 'execute_bulk_close_case' tool.

Workflow Integration: - A core function for managing the lifecycle of a security case, used in both manual and automated workflows. - Integrates with UI actions like assigning a case, changing its status, or adding a description. - Essential for automated playbooks that need to update a case's status after performing an action, such as "Case moved to 'Remediation' after host was isolated." - Can be used to synchronize case status with external ticketing or project management systems.

Use Cases: - An analyst assigns a case to themselves or another team member. - A SOC manager escalates a case by changing its priority from "Medium" to "Critical". - A user adds a detailed description or updates the title of a case to better reflect the investigation's findings. - Add or modify tags and products associated with the case.

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 (str): The numeric ID of the Case to update (e.g., '12345'). This is a required field. display_name (str, optional): The new display name for the case. stage (str, optional): The new stage of the case. The Stage options are: ['Research', 'Improvement', 'Incident', 'Investigation', 'Assessment', 'Triage']. priority (backstory.Priority, optional): The new priority of the case (e.g., "PRIORITY_HIGH", "PRIORITY_CRITICAL"). important (bool, optional): Whether the case is marked as important. incident (bool, optional): Whether the case is marked as an incident. assignee (str, optional): The user or role to assign to the case. description (str, optional): The new description for the case. environment (str, optional): The environment associated with the case. move_environment (google.cloud.chronicle.v1alpha.Case.MoveEnvironment, optional): Details about moving the case to a different environment.

Returns: Case: The updated Case object with the new values. The Case object contains the following key fields: - Name (str): The full resource name of the case. - Id (int): The unique identifier for the case. - DisplayName (str): The title or display name of the case. - Stage (str): The current stage of the case (e.g., "Triage", "Investigation"). - Priority (str): The priority of the case (e.g., "PRIORITY_HIGH"). - Assignee (str): The user or group assigned to the case. - Description (str): A detailed description of the case. - Status (str): The current status of the case (e.g., "OPENED", "CLOSED"). - CreateTime (int): The creation timestamp of the case in milliseconds. - UpdateTime (int): The last update timestamp of the case in milliseconds. - Tags (list of str): A list of tags associated with the case. - Products (list of str): A list of products associated with the case. Returns an error message if the case is not found, the user lacks permission, or the update is invalid.

Example Usage: # Update the assignee and priority of a case update_case( project_id='123', region='us', customer_id='abc', case_id='456', assignee='new_user@example.com', priority='PRIORITY_CRITICAL' )

# Change the stage and add a description
update_case(
    project_id='123',
    region='us',
    customer_id='abc',
    case_id='789',
    stage='Investigation',
    description='Escalated for further investigation due to new IOCs.'
)

# Mark as important
update_case(
    project_id='123',
    region='us',
    customer_id='abc',
    case_id='101',
    important=True
)

Next Steps (using MCP-enabled tools): - Use 'get_case' with the case's resource name to verify that the case has been updated correctly. - Use 'list_case_comments' to see if any comments were added as part of the update. - Use 'create_case_comment' to add a note explaining why the case was updated.
get_case_alert

Retrieves a single alert by its resource name.

Fetches all details for a specific alert within a case, including its properties (such as status, priority, and product), as well as optionally expanding to include related information like its SLA and involved entities. This tool is fundamental for drilling down into a specific alert after identifying it through a list view or search.

Workflow Integration: - Used when an analyst clicks on an alert within a case to view its full details in an investigation UI. - Essential for automated playbooks that need to retrieve the current state of an alert before taking action, such as enrichment or remediation. - Provides the necessary data to populate an alert investigation screen, showing all relevant information in one place. - Can be used to verify the result of an update operation by fetching the alert after the update has been applied.

Use Cases: - An analyst retrieves an alert to begin an investigation and understand its context, such as the rule that triggered it and the involved entities. - An automated system fetches an alert to extract entities (IPs, domains, hashes) for further enrichment from other threat intelligence sources. - A manager views an alert to review its details, check the SLA status, and see if a playbook has been run. - A reporting script fetches alert details to generate a detailed incident report.

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 (str): The numeric ID of the case (e.g., '12345'). case_alert_id (str): The numeric ID of the case alert to retrieve (e.g., '12345'). Do NOT use the alert title or identifier string. expand (str, optional): A comma-separated list of related resources to include in the response. This allows you to get a more complete picture of the alert in a single call. Supported values: 'sla', 'involvedRelations'.

Returns: CaseAlert: The full CaseAlert object with all its details. If the 'expand' parameter is used, the corresponding related resources will be included. The CaseAlert object contains the following key fields: - Name (str): The full resource name of the alert. - Id (int): The unique identifier for the alert. - DisplayName (str): The title or display name of the alert. - Priority (str): The priority of the alert (e.g., "HIGH"). - Status (str): The current status of the alert (e.g., "OPEN"). - CreateTime (int): The creation timestamp of the alert in milliseconds. - UpdateTime (int): The last update timestamp of the alert in milliseconds. - Product (str): The product that generated the alert. - Vendor (str): The vendor of the product that generated the alert. - RuleGenerator (str): The rule that generated the alert. Returns an error message if the alert is not found or the user does not have permission to view it.

Example Usage: # Get basic details for a specific alert get_case_alert(project_id='123', region='us', customer_id='abc', case_id='456', case_alert_id='789')
list_case_alerts

Lists all alerts within a case. This tool also provides alert_group_identifiers for each alert.

Workflow Integration: - Used when an analyst needs to see all alerts within a case, such as when investigating a specific case or reviewing the status of multiple alerts. - Essential for automated playbooks that need to check the status of multiple alerts before taking action. - Provides a comprehensive view of all alerts within a case, allowing for easy navigation and status monitoring. - Can be used to verify the result of an update operation by fetching the alert after the update has been applied.

Use Cases: - An analyst views all alerts within a case to see if any other alerts are firing for the same host or user. - A SOC manager reviews all alerts within a case to prioritize their investigation. - An automated playbook checks the status of multiple alerts before taking action. - A reporting script fetches all alerts within a case to generate a detailed incident report.

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 (str): The numeric ID of the case to list alerts for (e.g., '12345'). This is a required field. page_size (int, optional): The maximum number of alerts to return. The service may return fewer alerts than requested. If unspecified, the service will pick an appropriate default. page_token (str, optional): A page token, received from a previous ListCaseAlerts call. Provide this to retrieve the subsequent page. filter (str, optional): A filter expression to filter the list of alerts. Supported fields include 'Status', 'Priority', 'CreateTime', 'UpdateTime', and 'AlertGroupIdentifier'. Note that field names are case-sensitive and follow PascalCase as used in the backend. Example: filter="AlertGroupIdentifier='Remote Failed loginJIuSrw6JxVEAQsav/ew994J+AnKNOB+vrsfNpkO3ZQI=_923ec98b-4fb6-4a3f-809d-d6de2f201795'" order_by (str, optional): A comma-separated list of field names to order by. Supported fields: 'CreateTime', 'UpdateTime'.

Returns: ListCaseAlertsResponse: A paginated list of CaseAlert objects, each representing a single alert within the case. Each CaseAlert object contains the following key fields: - Name (str): The full resource name of the alert. - Id (int): The unique identifier for the alert. - DisplayName (str): The title or display name of the alert. - Priority (str): The priority of the alert (e.g., "HIGH"). - Status (str): The current status of the alert (e.g., "OPEN"). - CreateTime (int): The creation timestamp of the alert in milliseconds. - UpdateTime (int): The last update timestamp of the alert in milliseconds. - Product (str): The product that generated the alert. - Vendor (str): The vendor of the product that generated the alert. - RuleGenerator (str): The rule that generated the alert. Returns an error message if the parent case is not found or the user does not have permission to view it.

Example Usage: # List all alerts within a case list_case_alerts(project_id='123', region='us', customer_id='abc', case_id='456')

# List all alerts within a case with a filter
list_case_alerts(project_id='123', region='us', customer_id='abc', case_id='456', filter='status="OPEN"')

# List all alerts within a case with ordering
list_case_alerts(project_id='123', region='us', customer_id='abc', case_id='456', order_by='create_time desc')

Next Steps (using MCP-enabled tools): - Use 'get_case_alert' with the alert's resource name to retrieve its full details. - Use 'create_case_comment' to add a note to the parent case explaining why the alert status was changed. - Use 'update_case_alert' to change the status of an alert. - Use 'list_case_comments' to see if any comments were added as part of the update.
update_case_alert

Updates an existing case alert in Google SecOps.

This function modifies the priority, status, or closure_details of a specific alert within a case.

Workflow Integration: - A core function for managing the lifecycle of an alert, used in both manual and automated workflows. - Integrates with UI actions for changing an alert's priority, status (e.g., open, closed), or closing it with details. - Essential for automated playbooks that need to programmatically update an alert's state, such as escalating priority based on new findings or closing an alert after remediation. - Can be used to synchronize alert status and details with external ticketing or project management systems.

Use Cases: - A playbook automatically updates an alert's status to 'CLOSE' and sets closure_details with a reason of 'NOT_MALICIOUS' after automated analysis. - An analyst manually changes the priority of an alert to 'HIGH' based on their assessment. - An analyst updates the status to 'OPEN' to indicate they are actively investigating. - A SOC manager updates the closure_details for a set of related alerts after a breach investigation is complete.

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 (str): The numeric ID of the parent case containing the alert (e.g., '12345'). case_alert_id (str): The numeric ID of the alert to update (e.g., '12345'). Do NOT use the alert title or identifier string. priority (google.cloud.chronicle.v1alpha.LegacyCasePriority, optional): The new priority for the alert. Possible values are: - UNCHANGED - INFORMATIVE - LOW - MEDIUM - HIGH - CRITICAL status (google.cloud.chronicle.v1alpha.AlertStatus, optional): The new status for the alert. Possible values are: - OPEN - CLOSE closure_details (google.cloud.chronicle.v1alpha.AlertClosureDetails, optional): The closure details object. Providing this typically accompanies setting the status to CLOSE. - reason (enum): The reason for closing the alert (required). One of: - MALICIOUS - NOT_MALICIOUS - MAINTENANCE - INCONCLUSIVE - UNKNOWN - root_cause (str): The root cause of the alert (required). - comment (str): A comment about the alert. Optional.

Returns: CaseAlert: The updated CaseAlert object with the new values. The CaseAlert object contains the following key fields: - Name (str): The full resource name of the alert. - Id (int): The unique identifier for the alert. - DisplayName (str): The title or display name of the alert. - Priority (str): The priority of the alert (e.g., "HIGH"). - Status (str): The current status of the alert (e.g., "OPEN"). - CreateTime (int): The creation timestamp of the alert in milliseconds. - UpdateTime (int): The last update timestamp of the alert in milliseconds. - Product (str): The product that generated the alert. - Vendor (str): The vendor of the product that generated the alert. - RuleGenerator (str): The rule that generated the alert. Returns an error message if the alert is not found, the user lacks permission, or the update is invalid.

Example Usage: # Close a case alert as 'NOT_MALICIOUS' with a comment update_case_alert( project_id='123', region='us', customer_id='abc', case_id='456', case_alert_id='789', status='CLOSE', closure_details={ 'reason': 'NOT_MALICIOUS', 'root_cause': 'Benign activity verified', 'comment': 'Verified benign.' } )

# Update the priority of a case alert update_case_alert( project_id='123', region='us', customer_id='abc', case_id='456', case_alert_id='789', priority='HIGH' )

# Re-open an alert update_case_alert( project_id='123', region='us', customer_id='abc', case_id='456', case_alert_id='789', status='OPEN' )

Next Steps (using MCP-enabled tools): - Use 'get_case_alert' with the alert's resource name to verify that the alert has been updated correctly. - Use 'create_case_comment' to add a note to the parent case explaining why the alert was changed. - Use 'list_case_alerts' to see the updated status of the alert in the context of other alerts in the case.
create_case_comment

Creates a new case comment in Google SecOps.

Adds a new, structured comment to an existing SOAR case, enabling analysts to log notes, updates, or decisions within an investigation. This is a critical function for maintaining a clear and auditable record of all activities related to a security case.

Workflow Integration: - A fundamental part of documenting an investigation and maintaining an audit trail for compliance and review. - Integrates seamlessly with UI actions, such as an "Add Comment" button on a case details page, allowing for manual entry of findings. - Allows for automated systems and playbooks to log their actions directly into a case, providing a unified timeline of both human and machine activities. - Can be used to trigger other automated workflows; for example, adding a comment with a specific tag could initiate a new playbook.

Use Cases: - An analyst adds a manual note about their findings after investigating an alert, such as "Confirmed phishing email from sender X." - An automated playbook adds a comment detailing an action it took, like "Successfully isolated host Y from the network." - A user attaches an artifact or file to the case with a descriptive comment, which can be done by providing attachment details within the comment. - A manager adds a comment to assign the case to a different analyst or to provide guidance on the next steps.

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 (str): The numeric ID of the case to which the comment will be added (e.g., '12345'). This is a required field. comment (str): The content of the comment. This is a required field and can contain text, links, or other relevant information.

Returns: CaseComment: The newly created CaseComment object, including its unique, server-assigned resource name and creation timestamp. The CaseComment object contains the following key fields: - Name (str): The full resource name of the comment. - Id (int): The unique identifier for the comment. - Comment (str): The content of the comment. - UserOwnerFullName (str): The full name of the user who created the comment. - LastEditorFullName (str): The full name of the user who last edited the comment. - CreateTime (int): The creation timestamp of the comment in milliseconds. - UpdateTime (int): The last update timestamp of the comment in milliseconds. - IsFavorite (bool): Indicates if the comment is marked as a favorite. - IsDeleted (bool): Indicates if the comment has been deleted. - AlertIdentifier (str): The identifier of the alert associated with the comment, if any. Returns an error message if the parent case is not found, if the user does not have permission, or if the comment could not be created for other reasons.

Example Usage: # Create a new comment for a case create_case_comment( project_id='123', region='us', customer_id='abc', case_id='456', comment='Investigated suspicious login from external IP. The IP has been added to the blocklist.' )

Next Steps (using MCP-enabled tools): - Use 'list_case_comments' to see the newly created comment in the case's timeline along with other comments. - Use 'get_case_comment' with the returned resource name to retrieve its full details at a later time. - Use 'update_case' to change the status or other properties of the case based on the new comment.
execute_bulk_close_case

Closes one or more cases in bulk. This is the only tool that can change the status of a case to 'CLOSED'.

This tool allows for the efficient closure of multiple cases at once, which is useful for resolving incidents that have been fully investigated or for cleaning up old cases. It can also be used to close a single case.

Workflow Integration: - Used in automated playbooks to close cases after a successful remediation workflow. - Enables SOC managers or senior analysts to perform bulk cleanup of resolved or irrelevant cases from a queue. - Can be integrated into custom scripts for case management tasks, such as automatically closing cases that have been inactive for a certain period.

Use Cases: - A playbook automatically closes a set of related cases after the root cause has been addressed and all associated alerts have been triaged. - An analyst closes a single case after completing their investigation and documenting the findings. - A SOC manager selects multiple resolved cases from a dashboard and closes them in a single action.

Args: project_id (str): Google Cloud project ID (required). The ID of the Google Cloud project associated with the Chronicle instance. customer_id (str): Chronicle customer ID (required). The unique identifier for the Chronicle customer instance. region (str): Chronicle region (e.g., "us", "europe") (required). The geographical region where the Chronicle instance is hosted. cases_ids (list of int): A list of case IDs to be closed (required). Each ID uniquely identifies a case in Chronicle. close_reason (str): The reason for closing the cases (required). Possible values: 'MALICIOUS', 'NOT_MALICIOUS', 'MAINTENANCE', 'INCONCLUSIVE', 'UNKNOWN'. - MALICIOUS: The case was closed because malicious activity was confirmed. - NOT_MALICIOUS: The case was closed because the activity was determined to be benign. - MAINTENANCE: The case was closed due to maintenance or system-related activities. - INCONCLUSIVE: The investigation was inconclusive, and a definitive determination could not be made. - UNKNOWN: The reason for closure is unknown or not specified. root_cause (str, required): The root cause of the incident that led to the case closure. A detailed explanation of the underlying factor that caused the incident. close_comment (str, required): A comment to be added to each case upon closure. This provides additional context or notes regarding the closure.

Note: The ability to update custom fields via dynamic_parameters is intentionally omitted from this bulk operation, as the Google SecOps UI advises that custom fields are not updated during bulk closure and should be updated on a per-case basis.

Returns: An empty response object if the operation is successful. Returns an error message if the operation fails, for example, if one of the cases does not exist or the user does not have permission to close it.

Example Usage: # Close a single case execute_bulk_close_case( project_id='123', region='us', customer_id='abc', cases_ids=[456], close_reason='NOT_MALICIOUS', root_cause='False positive identified', close_comment='Closing due to false positive.' )

# Close multiple cases in bulk
execute_bulk_close_case(
    project_id='123',
    region='us',
    customer_id='abc',
    cases_ids=[101, 102, 103],
    close_reason='MALICIOUS',
    root_cause='Phishing campaign identified and blocked.'
)

Next Steps (using MCP-enabled tools): - Use 'list_cases' with a filter for 'status="CLOSED"' to verify that the cases have been closed. - Use 'get_case' for one of the closed cases to check that the close reason, root cause, and comment have been correctly applied.
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.

Get MCP tool specifications

To get the MCP tool specifications for all tools in an MCP server, use the tools/list method. The following example demonstrates how to use curl to list all tools and their specifications currently available within the MCP server.

Curl Request 
                      
curl --location 'https://chronicle.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'