MCP Tools Reference: chronicle.googleapis.com

Tool: 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.

Example Usage:

  • list_cases(projectId='123', region='us', customerId='abc', pageSize=10)
  • list_cases(projectId='123', region='us', customerId='abc', filter="priority='PRIORITY_CRITICAL'", orderBy="CreateTime desc")
  • list_cases(projectId='123', region='us', customerId='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.

The following sample demonstrate how to use curl to invoke the list_cases 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": "list_cases",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for ListCases. Next ID: 9

ListCasesRequest

JSON representation 
{
  "projectId": string,
  "customerId": string,
  "region": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "orderBy": string,
  "expand": string
}
Fields
projectId

string

Required. Google Cloud project ID.
customerId

string

Required. Chronicle customer ID.
region

string

Required. Chronicle region (e.g., "us", "europe").
pageSize

integer

The maximum number of cases to return in a single response. The default is 50, and the maximum is 1000. If this value is greater than 1000, 1000 will be used.
pageToken

string

A token for fetching a specific page of results, obtained from a previous call.
filter

string

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'"
orderBy

string

A comma-separated list of fields to sort the results by. Add 'desc' for descending order. Example: "Priority desc, CreateTime asc"
expand

string

A comma-separated list of related resources to include in the response. Supported values: 'tasks', 'tags', 'products'.

Output Schema

Response message for ListCases.

ListCasesResponse

JSON representation 
{
  "cases": [
    {
      object (Case)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}
Fields
cases[]

object (Case)

The list of cases.
nextPageToken

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
totalSize

integer

The total number of results matching the request.

Case

JSON representation 
{
  "name": string,
  "creatorUserId": string,
  "creatorUser": string,
  "lastModifyingUserId": string,
  "lastModifyingUser": string,
  "createTime": string,
  "updateTime": string,
  "displayName": string,
  "alertCount": integer,
  "stage": string,
  "priority": enum (Priority),
  "assignee": string,
  "assignedUser": string,
  "description": string,
  "type": enum (CaseType),
  "environment": string,
  "status": enum (CaseStatus),
  "score": number,
  "workflowStatus": enum (WorkflowStatus),
  "sla": {
    object (Sla)
  },
  "alertsSla": {
    object (Sla)
  },
  "source": string,
  "tags": [
    {
      object (CaseTag)
    }
  ],
  "products": [
    {
      object (CaseProduct)
    }
  ],
  "closureDetails": {
    object (CaseClosureDetails)
  },
  "tasks": [
    {
      object (Task)
    }
  ],
  "moveEnvironment": {
    object (MoveEnvironment)
  },
  "dataAccessScopes": [
    string
  ],
  "customFieldValues": [
    {
      object (CustomFieldValue)
    }
  ],

  // Union field _important can be only one of the following:
  "important": boolean
  // End of list of possible types for union field _important.

  // Union field _incident can be only one of the following:
  "incident": boolean
  // End of list of possible types for union field _incident.

  // Union field _overflow_case can be only one of the following:
  "overflowCase": boolean
  // End of list of possible types for union field _overflow_case.

  // Union field _involved_suspicious_entity can be only one of the following:
  "involvedSuspiciousEntity": boolean
  // End of list of possible types for union field _involved_suspicious_entity.
}
Fields
name

string

Identifier. The unique name(ID) of the Case. Format: projects/{project}/locations/{location}/instances/{instance}/cases/{case}
creatorUserId

string

Output only. Case creator id. Used for homepage/requests feature.
creatorUser

string

Output only. Resource association for the creator.
lastModifyingUserId

string

Output only. Last user who modified the case. replaced old property name: LastModifyingUser.
lastModifyingUser

string

Output only. Resource association for the modifying user.
createTime

string (int64 format)

Output only. The creation time of the record in milliseconds.
updateTime

string (int64 format)

Output only. The modification time of the record in milliseconds.
displayName

string

Required. Case title, limited to 200 characters. Replaces old property: Title.
alertCount

integer

Output only. Alerts in case.
stage

string

Required. The stage of the Case. For example, "Triage", "Incident", "Investigation". Stages are defined in "chronicle.googleapis.com/CaseStageDefinition". The default stage option is "Triage".
priority

enum (Priority)

Required. Default value is HIGH. Case priority. For example, "Informative", "Low", "Medium", "High", "Critical".
assignee

string

Optional. This can be a user or a @SocRole, default value is the default soc-role defined in Settings.
assignedUser

string

Output only. Resource association for the assignee.
description

string

Optional. Case description. Limit chars to 1000.
type

enum (CaseType)

Required. Case type.
environment

string

Required. Case logical environments.
status

enum (CaseStatus)

Output only. Case data status.
score

number

Optional. Attack exposure score, how risky the case.
workflowStatus

enum (WorkflowStatus)

Output only. Case playbook status.
sla

object (Sla)

Optional. SLA for the case.
alertsSla

object (Sla)

Optional. Aggregated alerts SLA. (alert has SLA as well).
source

string

Output only. The source that created the case. Possible values: "Server", "User", "Simulated", "Merge", "AlertMove"
tags[]

object (CaseTag)

Optional. CaseTags associated with the case.
products[]

object (CaseProduct)

Optional. Products associated with the case. Contains Name of product (e.g. WinEventLog:Security/DLP_Product). Replaces old property: "Product".
closureDetails

object (CaseClosureDetails)

Optional. Case closure details.
tasks[]

object (Task)

Output only. Tasks associated with the case.
moveEnvironment

object (MoveEnvironment)

Optional. Case environment move details.
dataAccessScopes[]

string

Output only. Data Access Scopes.
customFieldValues[]

object (CustomFieldValue)

Optional. Custom field values associated with the case.

Union field _important.

_important can be only one of the following:
important

boolean

Optional. Additional way to specify case importance. The default is false.

Union field _incident.

_incident can be only one of the following:
incident

boolean

Optional. Additional way to specify if the case marked as incident. The default is false.

Union field _overflow_case.

_overflow_case can be only one of the following:
overflowCase

boolean

Output only. Case without events, was reduced by the connector service due to a large amount of data. During ingestion if the "alert package" crosses a specific threshold, the alert will be trimmed due to security reasons (DDOS attacks, etc..)

Union field _involved_suspicious_entity.

_involved_suspicious_entity can be only one of the following:
involvedSuspiciousEntity

boolean

Optional. If has involved suspicious entity in the case.

Sla

JSON representation 
{
  "expirationTime": string,
  "criticalExpirationTime": string,
  "expirationStatus": enum (SlaExpirationStatus),
  "remainingTimeSinceLastPause": integer
}
Fields
expirationTime

string (int64 format)

Required. SLA expiration time in unix format as milliseconds. Old prop: SlaExpiration.
criticalExpirationTime

string (int64 format)

Required. SLA critical expiration time in unix format as milliseconds, old prop: SlaCriticalExpiration.
expirationStatus

enum (SlaExpirationStatus)

Output only. SLA expiration status.
remainingTimeSinceLastPause

integer

Output only. Remaining time since last pause.

CaseTag

JSON representation 
{
  "displayName": string,
  "alert": string,

  // Union field _priority can be only one of the following:
  "priority": integer
  // End of list of possible types for union field _priority.
}
Fields
displayName

string

Output only. The name of the tag
alert

string

Output only. For tags set by playbook action, this is relevant during MoveAlert. Replaces old property: "Indicator".

Union field _priority.

_priority can be only one of the following:
priority

integer

Output only. During ingestion if more than one tag matches the criteria, the one with the priority will be chosen. Available options: 1-5.

CaseProduct

JSON representation 
{
  "displayName": string,
  "alert": string
}
Fields
displayName

string

Output only. Display name of the product.
alert

string

Output only. Replaces old property: "AlertIdentifier".

CaseClosureDetails

JSON representation 
{
  "reason": enum (CloseReason),
  "rootCause": string,
  "caseClosedAction": enum (CaseClosedAction),
  "comment": string
}
Fields
reason

enum (CloseReason)

Output only. Case closure reason.
rootCause

string

Output only. Case closure root cause.
caseClosedAction

enum (CaseClosedAction)

Output only. Case closed action.
comment

string

Output only. Case closure comment.

Task

JSON representation 
{
  "name": string,
  "id": string,
  "createTime": string,
  "updateTime": string,
  "content": string,
  "dueTime": string,
  "title": string,
  "author": string,
  "lastAuthor": string,
  "assignee": string,
  "status": enum (Status),
  "resolver": string,
  "comment": string,
  "resolutionTime": string,
  "caseId": integer,

  // Union field _favorite can be only one of the following:
  "favorite": boolean
  // End of list of possible types for union field _favorite.
}
Fields
name

string

Identifier. The unique name(ID) of the task. Format: projects/{project}/locations/{location}/instances/{instance}/tasks/{task}
id

string (int64 format)

Output only. The unique ID of the task.
createTime

string (int64 format)

Output only. The creation time of the task.
updateTime

string (int64 format)

Output only. The last update time of the task.
content

string

Required. The task content, limited to 4096 characters.
dueTime

string (int64 format)

Optional. The due time for the task in ms. When specified during task creation, must be in the future. Is optional as deadlines can exist without a specific scheduled time.
title

string

Required. The task title, minimum length of 3 characters and maximum of 50 characters.
author

string

Output only. The user who created the task.
lastAuthor

string

Output only. The last editor of the task.
assignee

string

Required. The assignee of the task.
status

enum (Status)

Required. The status of the task. todo change to task startus enum
resolver

string

Output only. The user who resolved the task.
comment

string

Required. Comment added during task resolution, limited to 4096 characters.
resolutionTime

string (int64 format)

Output only. The resolution time of the task in ms.
caseId

integer (uint32 format)

Optional. Associated case id (if task is related to a specific case) Can be optional as tasks may exist independently or be associated with a specific case.

Union field _favorite.

_favorite can be only one of the following:
favorite

boolean

Optional. Determines whether the task is marked as favorite.

MoveEnvironment

JSON representation 
{
  "shouldDeleteOldCase": boolean
}
Fields
shouldDeleteOldCase

boolean

Optional. If the case should be deleted on move to the new environment.

CustomFieldValue

JSON representation 
{
  "name": string,
  "customFieldId": string,
  "scope": enum (CustomFieldScope),
  "scopeId": string,
  "values": [
    string
  ],
  "valuesSearchText": string
}
Fields
name

string

Identifier. Unique identifier of the resource.
customFieldId

string (int64 format)

Required. The id of the parent CustomField that owns this CustomFieldValue
scope

enum (CustomFieldScope)

Output only. Scope of the value.
scopeId

string

Required. Identifier of the value referencing case or alert.
values[]

string

Required. The custom field value.
valuesSearchText

string

Output only. Specific field represents the values field for faster search.

Tool Annotations

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