MCP Tools Reference: chronicle.googleapis.com

Tool: get_reference_list

Get details and contents of a reference list in Chronicle SIEM.

Retrieves the metadata and optionally the full contents of a reference list. This is useful for reviewing list contents, verifying data integrity, and understanding what data is available for detection rules.

Workflow Integration: - Use to verify reference list contents before creating or modifying detection rules. - Essential for auditing data quality and consistency in security reference data. - Helps understand available data when troubleshooting detection rule issues. - Supports data governance by providing visibility into managed security datasets.

Use Cases: - Review threat intelligence lists before implementing new detection rules. - Verify that allowlists or blocklists contain the expected entries. - Audit reference list contents for compliance or security reviews. - Troubleshoot detection rule issues by examining referenced list data. - Generate reports on security reference data for operational documentation.

Args: name (str): The ID of the reference list to retrieve (the last part of the resource name). project_id (str): Google Cloud project ID (required). customer_id (str): Chronicle customer ID (required). region (str): Chronicle region (e.g., "us", "europe") (required). view (str, optional): Specifies the view of the reference list to return. Valid values: "REFERENCE_LIST_VIEW_BASIC", "REFERENCE_LIST_VIEW_FULL". Defaults to "REFERENCE_LIST_VIEW_FULL" if unspecified. "REFERENCE_LIST_VIEW_BASIC" includes metadata only. "REFERENCE_LIST_VIEW_FULL" includes metadata and all entries.

Returns: str: Formatted reference list details including metadata and entries (if view is FULL). Returns error message if retrieval fails.

Example Usage: # Get full details of an admin accounts list get_reference_list( name="admin_accounts", project_id="my-project", customer_id="my-customer", region="us", view="REFERENCE_LIST_VIEW_FULL" )

# Get metadata only for a large reference list
        get_reference_list(
            name="threat_ip_addresses",
            project_id="my-project",
            customer_id="my-customer",
            region="us",
            view="REFERENCE_LIST_VIEW_BASIC"
        )

Next Steps (using MCP-enabled tools): - Update the list using update_reference_list if changes are needed. - Reference the list data in detection rules to enhance security monitoring. - Compare with external threat intelligence sources to identify updates needed. - Document the list contents and update procedures for operational teams. - Set up regular reviews to maintain data quality and relevance.

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

Input Schema

Request message for GetReferenceList.

GetReferenceListRequest

JSON representation 
{
  "projectId": string,
  "customerId": string,
  "region": string,
  "name": string,
  "view": string
}
Fields
projectId

string

Project ID of the customer.
customerId

string

Customer ID of the customer.
region

string

Region of the customer.
name

string

Name of the reference list to get.
view

string

View of the reference list to return.

Output Schema

A reference list. Reference lists are user-defined lists of values which users can use in multiple Rules.

ReferenceList

JSON representation 
{
  "name": string,
  "displayName": string,
  "revisionCreateTime": string,
  "description": string,
  "entries": [
    {
      object (ReferenceListEntry)
    }
  ],
  "rules": [
    string
  ],
  "syntaxType": enum (ReferenceListSyntaxType),
  "ruleAssociationsCount": integer,
  "scopeInfo": {
    object (ScopeInfo)
  }
}
Fields
name

string

Identifier. The resource name of the reference list. Format: projects/{project}/locations/{location}/instances/{instance}/referenceLists/{reference_list}
displayName

string

Output only. The unique display name of the reference list.
revisionCreateTime

string (Timestamp format)

Output only. The timestamp when the reference list was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
description

string

Required. A user-provided description of the reference list.
entries[]

object (ReferenceListEntry)

Required. The entries of the reference list. When listed, they are returned in the order that was specified at creation or update. The combined size of the values of the reference list may not exceed 6MB. This is returned only when the view is REFERENCE_LIST_VIEW_FULL.
rules[]

string

Output only. The resource names for the associated self-authored Rules that use this reference list. This is returned only when the view is REFERENCE_LIST_VIEW_FULL.
syntaxType

enum (ReferenceListSyntaxType)

Required. The syntax type indicating how list entries should be validated.
ruleAssociationsCount

integer

Output only. The count of self-authored rules using the reference list.
scopeInfo

object (ScopeInfo)

The scope info of the reference list. During reference list creation, if this field is not set, the reference list without scopes (an unscoped list) will be created for an unscoped user. For a scoped user, this field must be set. During reference list update, if scope_info is requested to be updated, this field must be set.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

ReferenceListEntry

JSON representation 
{
  "value": string
}
Fields
value

string

Required. The value of the entry. Maximum length is 512 characters.

ScopeInfo

JSON representation 
{
  "referenceListScope": {
    object (ReferenceListScope)
  }
}
Fields
referenceListScope

object (ReferenceListScope)

Required. The list of scope names of the reference list, if the list is empty the reference list is treated as unscoped.

ReferenceListScope

JSON representation 
{
  "scopeNames": [
    string
  ]
}
Fields
scopeNames[]

string

Optional. The list of scope names of the reference list. The scope names should be full resource names and should be of the format: projects/{project}/locations/{location}/instances/{instance}/dataAccessScopes/{scope_name}.

Tool Annotations

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