# MCP Tools Reference: chronicle.googleapis.com

## Tool: `list_involved_entities`

Lists all involved entities for a given case alert in Chronicle SIEM.

Retrieves a paginated list of all entities associated with a specific SOAR case alert.

**Workflow Integration:**

- Used to populate a list of entities in the SOAR UI for a given case alert.
- Enables an analyst to quickly see all related entities when starting an investigation.

**Use Cases:**

- Display all involved entities on a case alert detail page.
- A playbook iterates through all entities to check for specific indicators.

**Example Usage:**

- `list_involved_entities(projectId='123', region='us', customerId='abc', caseId='1', caseAlertId='456')`

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

| Curl Request |
|---|
| ```bash 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_involved_entities", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for ListInvolvedEntities.

### ListInvolvedEntitiesRequest

| JSON representation |
|---|
| ``` { "projectId": string, "customerId": string, "region": string, "caseId": string, "caseAlertId": string, "pageSize": integer, "pageToken": string, "filter": string, "orderBy": string } ``` |

| Fields ||
|---|---|
| `projectId` | `string` Required. Google Cloud project ID. |
| `customerId` | `string` Required. Chronicle customer ID. |
| `region` | `string` Required. Chronicle region (e.g., "us", "europe"). |
| `caseId` | `string` The numeric ID of the parent case (e.g., "1"). |
| `caseAlertId` | `string` The numeric ID of the specific alert within the case (e.g., "789"). This is *not* the descriptive alert identifier string. You can find this numeric ID as the last part of the 'Name' field when you list alerts using 'list_case_alerts'. |
| `pageSize` | `integer` Maximum number of entities to return. |
| `pageToken` | `string` A token for fetching the next page of results. |
| `filter` | `string` A filter to apply to the list of entities. |
| `orderBy` | `string` The field to order the results by. |

## Output Schema

Response message for ListInvolvedEntities.

### ListInvolvedEntitiesResponse

| JSON representation |
|---|
| ``` { "involvedEntities": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.InvolvedEntity`) } ], "nextPageToken": string, "totalSize": integer } ``` |

| Fields ||
|---|---|
| `involvedEntities[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.InvolvedEntity`)`` The list of InvolvedEntities. |
| `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 InvolvedEntities. |

### InvolvedEntity

| JSON representation |
|---|
| ``` { "name": string, "id": string, "type": string, "threatSource": string, "operatingSystem": string, "networkTitle": string, "environment": string, "additionalProperties": string, "sourceSystemUri": string, "entityUri": string, "fields": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.ContextGroup`) } ], "alertIdentifier": string, "caseId": integer, "identifier": string, // Union field `_suspicious` can be only one of the following: "suspicious": boolean // End of list of possible types for union field `_suspicious`. // Union field `_internal` can be only one of the following: "internal": boolean // End of list of possible types for union field `_internal`. // Union field `_network_priority` can be only one of the following: "networkPriority": integer // End of list of possible types for union field `_network_priority`. // Union field `_attacker` can be only one of the following: "attacker": boolean // End of list of possible types for union field `_attacker`. // Union field `_pivot` can be only one of the following: "pivot": boolean // End of list of possible types for union field `_pivot`. // Union field `_manually_created` can be only one of the following: "manuallyCreated": boolean // End of list of possible types for union field `_manually_created`. // Union field `_enriched` can be only one of the following: "enriched": boolean // End of list of possible types for union field `_enriched`. // Union field `_artifact` can be only one of the following: "artifact": boolean // End of list of possible types for union field `_artifact`. // Union field `_vulnerable` can be only one of the following: "vulnerable": boolean // End of list of possible types for union field `_vulnerable`. } ``` |

| Fields ||
|---|---|
| `name` | `string` Identifier. The unique name(ID) of the InvolvedEntity. Format: projects/{project}/locations/{location}/instances/{instance}/cases/{case}/caseAlerts/{case_alert}/involvedEntities/{involved_entity} |
| `id` | `string (https://developers.google.com/discovery/v1/type-format format)` Required. Immutable. The id of the entity. |
| `type` | `string` Required. Immutable. The type of the entity. Could be: HOSTNAME, USB, PROCESS, ADDRESS, ... |
| `threatSource` | `string` Optional. Threat source of the entity. |
| `operatingSystem` | `string` Optional. Operating system related to the entity. |
| `networkTitle` | `string` Optional. Network name related to the entity. |
| `environment` | `string` Output only. Immutable. The environment the entity belongs to. Derived from the case and alert. |
| `additionalProperties` | `string` Optional. Stores additional properties, as a JSON format. |
| `sourceSystemUri` | `string` Optional. Output only. Immutable. Link to the source system. |
| `entityUri` | `string` Optional. Output only. The full url of the entity, calculated using the source_system_uri and the entity data. Optional if the source_system_uri is not defined. |
| `fields[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.ContextGroup`)`` Output only. A list of context group items, which are calculated based on the entity's properties. |
| `alertIdentifier` | `string` Output only. The alert identifier of the alert that the involved entity is associated with. |
| `caseId` | `integer` Output only. The id of the case that the involved entity is associated with. |
| `identifier` | `string` Output only. The identifier name of the involved entity. |
| Union field `_suspicious`. `_suspicious` can be only one of the following: ||
| `suspicious` | `boolean` Required. Describes if the entity is suspicious or not. |
| Union field `_internal`. `_internal` can be only one of the following: ||
| `internal` | `boolean` Required. Indicates whether this entity is internal. This setting is configured in the application's settings, and any entity type can be designated as internal. |
| Union field `_network_priority`. `_network_priority` can be only one of the following: ||
| `networkPriority` | `integer` Optional. Network priority of a related network. |
| Union field `_attacker`. `_attacker` can be only one of the following: ||
| `attacker` | `boolean` Optional. Describes if the entity represents an attacker or not. |
| Union field `_pivot`. `_pivot` can be only one of the following: ||
| `pivot` | `boolean` Optional. Describes if the entity is a pivot or not. A pivot entity is an entity which is common to two or more cases. In the case graph, it is connected to other entities by a dotted line. |
| Union field `_manually_created`. `_manually_created` can be only one of the following: ||
| `manuallyCreated` | `boolean` Output only. Immutable. Describes if the entity was created by the system (as part of the ingestion flow), or manually by the user. |
| Union field `_enriched`. `_enriched` can be only one of the following: ||
| `enriched` | `boolean` Output only. Indicates whether the entity has been enriched. An entity is enriched when an action adds information from an external system. |
| Union field `_artifact`. `_artifact` can be only one of the following: ||
| `artifact` | `boolean` Output only. Describes if the entity is an artifact or not. |
| Union field `_vulnerable`. `_vulnerable` can be only one of the following: ||
| `vulnerable` | `boolean` Output only. Describes if the entity is vulnerable or not. |

### ContextGroup

| JSON representation |
|---|
| ``` { "displayName": string, "items": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.ContextGroupItem`) } ], // Union field `_highlighted` can be only one of the following: "highlighted": boolean // End of list of possible types for union field `_highlighted`. // Union field `_hidden` can be only one of the following: "hidden": boolean // End of list of possible types for union field `_hidden`. } ``` |

| Fields ||
|---|---|
| `displayName` | `string` Output only. The name of the context group. Default context group is called "Default". |
| `items[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/get_involved_entity#Output.Schema.ContextGroupItem`)`` Output only. A list of items in the group. |
| Union field `_highlighted`. `_highlighted` can be only one of the following: ||
| `highlighted` | `boolean` Output only. Is the context group highlighted. |
| Union field `_hidden`. `_hidden` can be only one of the following: ||
| `hidden` | `boolean` Output only. Is the context group hidden. |

### ContextGroupItem

| JSON representation |
|---|
| ``` { "name": string, "originalName": string, "value": string } ``` |

| Fields ||
|---|---|
| `name` | `string` Output only. The name of the property |
| `originalName` | `string` Output only. The original name of the property. |
| `value` | `string` Output only. The property's value. |

### Tool Annotations

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