Console
    Start free

    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.

    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.

    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

    Project ID of the customer.
    customerId

    string

    Customer ID of the customer.
    region

    string

    Region of the customer.
    pageSize

    integer

    Page size.
    pageToken

    string

    Page token.
    filter

    string

    Filter.
    orderBy

    string

    Order by.
    expand

    string

    Expand.

    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 
 , 
 "moveEnvironment" 
 : 
 { 
 object (  MoveEnvironment 
 
) 
 } 
 , 
 "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 
 
) 
 } 
 ] 
 , 
 // 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.

    moveEnvironment

    object ( MoveEnvironment )

    Optional. Case environment move details.

    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.

    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.

    MoveEnvironment

    JSON representation 
     { 
 "shouldDeleteOldCase" 
 : 
 boolean 
 }
    Fields
    shouldDeleteOldCase

    boolean

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

    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.

    Tool Annotations

    Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: