- HTTP request
- Path parameters
- Request body
- Response body
- Authorization scopes
- IAM Permissions
- UdmEventListOptions
- EventCountTimelineOptions
- UdmFieldAggregationsOptions
- DetectionOptions
- DetectionListOptions
- FunctionParameter
- GroupByField
- SelectedField
- FunctionType
- OrderBy
- UdmPrevalenceOptions
- UdmSearchAggregationBucketFunction
- FederationMetadata
- InstanceSelection
- FederationGroupSelection
- UdmEventList
- ColumnNames
- SearchDataTableInfo
- SearchDataTableColumnInfo
- ResultRow
- EventRecord
- Annotation
- EntityContextRecord
- JoinRecord
- EventCountTimeline
- EventCountTimelineBucket
- EntityChangedCountTimelineBucket
- EntityChangedInfo
- FieldAndValue
- KValueType
- JoinsResultCountTimelineBucket
- TableType
- UdmFieldAggregations
- UdmFieldAggregation
- UdmValueCount
- UdmFieldValue
- UdmFieldAggregationType
- GroupAggregationByField
- Detections
- FunctionResponse
- FunctionResponseRow
- UdmPrevalenceResponse
- UdmPrevalenceBucket
- UdmPrevalence
- Stats
- ColumnData
- ColumnType
- ColumnValue
- List
- ColumnMetadata
- ColumnSort
- SearchDataSource
- AIOverview
- Try it!
Full name: projects.locations.instances.legacy.legacyFetchUdmSearchView
Legacy endpoint for fetching events, filters, and histograms matching UDM search.
HTTP request
Path parameters
Parameters | |
---|---|
instance |
Required. The name of the parent resource, which is the SecOps instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance} |
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "baselineQuery": string, "snapshotQuery": string, "baselineTimeRange": { object ( |
Fields | |
---|---|
baselineQuery |
Required. Boolean query to search for events. You can refer to https://cloud.google.com/chronicle/docs/investigation/udm-search for the query syntax. Example: 'ip=/172.*/ AND metadata.event_type!="NETWORK_CONNECTION" AND ( target.ip = "3.225.179.73" OR target.ip = "23.47.48.70")' |
snapshotQuery |
Query applied to the baseline query's events. In other words, this query is applied to the Snapshot produced from the baseline query. The |
baselineTimeRange |
Required. Required, the time range to search for [inclusive start time, exclusive end time). |
snapshotTimeRange |
The time range to filter for [inclusive start time, exclusive end time). This time range must be completely within |
eventList |
Parameters for the Events that will be streamed back. |
timeline |
Parameters for the EventCountTimeline that will be streamed back. |
fieldAggregations |
Parameters for the Aggregated UDM fields that will be streamed back. |
caseInsensitive |
If true, the search should be performed in a case-insensitive manner. |
generateAiOverview |
Optional. If true, generate AI overview for the search results. |
returnOperationIdOnly |
Optional. If this field is set to true, the response will only contain the operation resource name. The actual search results (events) will be streamed back when the client invokes the |
detectionOptions |
Fetch alerts/detections relevant to the search result. |
statsFunctionParameter |
The request to apply statistical function on filtered data. |
draftDataAccessScope |
Data access scope used to filter events. This is intended to be used by admins to preview in-development scopes. Should only be called by users with global access. If the caller does not have global access, the request will fail. |
prevalence |
Parameters to get prevalence counts on Events returned by UDM Search |
enablePocFastPath |
If true, search will limit maxBaselineResults to 30K events and remove time-order guarantee (i.e., results may not be the most-recent events in baseline query time range). In this mode, replayed search queries are not guaranteed to yield the same results each time. This option is for poc use-cases only. |
federationMetadata |
Optional. Federation metadata for the request. If this field is populated, it implied this is a federated search. |
Response body
Depending on the parameters in ListUdmEventsV3Request, stream back some combination of UDM Events, EventCountTimeline, and UdmFieldAggregations.
If successful, the response body contains data with the following structure:
JSON representation |
---|
{ "operation": string, "progress": number, "tooManyEvents": boolean, "tooLargeResponse": boolean, "complete": boolean, "validBaselineQuery": boolean, "baselineEventsCount": integer, "validSnapshotQuery": boolean, "queryValidationErrors": [ { object ( |
Fields | |
---|---|
operation |
The name of the operation resource representing the UDM Search operation. This can be passed to The metadata type of the operation is Format: projects/{project}/locations/{location}/instances/{instance}/operations/{operation} |
progress |
Progress of the query represented as a double between 0 and 1. |
tooManyEvents |
If true, there are too many events to return and some have been omitted. |
tooLargeResponse |
If true, the response to be returned to the UI is too large and some events have been omitted. |
complete |
Streaming for this response is done. There will be no additional updates. |
validBaselineQuery |
Indicates whether the request baselineQuery is a valid structured query or not. If not, |
baselineEventsCount |
The number of events in the baseline query. |
validSnapshotQuery |
Indicates whether the request baseline and snapshot queries are valid. If not, |
queryValidationErrors[] |
Parse error for the baselineQuery and/or the snapshotQuery. |
runtimeErrors[] |
Runtime errors. |
filteredEventsCount |
The number of events in the snapshot that match the snapshotQuery. This is <= |
statsFunctionParameterValidationErrorMessage |
If the request's statsFunctionParameter` is invalid, this field will contain the detailed error message. |
prevalence |
Prevalence results on Events returned by UDM Search |
stats |
Stats results when the query is for statistics |
dataSources[] |
Datasource of the query and results in case of a statistics query |
aiOverview |
AI generated overview for the search results. Only populated if the AI features are enabled for the customer and generateAiOverview is set to true in the request. |
selectedFields[] |
Fields and variables that have been selected in the query. |
unselectedFields[] |
Fields and variables that have been unselected / excluded in the query. |
events |
List of UDM events. NOTE: After complete is set to true, the |
timeline |
Timeline of event counts broken into buckets. |
fieldAggregations |
List of UDM fields with aggregated values. |
udmEntityFieldAggregations |
List of Entity fields with aggregated values. |
entityContextTypeFieldAggregations |
List of Entity fields aggregated by context type. |
groupedFieldAggregations |
List of grouped fields with aggregated values. |
datatableAggregations |
List of datatable fields with aggregated column values. |
detections |
List of relevant detections, if detectionList.max_returned_detections was set. |
statsFunctionResponse |
Result for statistical function. |
activityTimeline |
Timeline of event counts broken into hourly/daily buckets to identify activity. |
Authorization scopes
Requires the following OAuth scope:
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview.
IAM Permissions
Requires the following IAM permission on the instance
resource:
chronicle.legacies.legacyFetchUdmSearchView
For more information, see the IAM documentation.
UdmEventListOptions
JSON representation |
---|
{ "maxReturnedEvents": integer } |
Fields | |
---|---|
maxReturnedEvents |
|
EventCountTimelineOptions
This type has no fields.
UdmFieldAggregationsOptions
JSON representation |
---|
{ "maxValuesPerField": integer } |
Fields | |
---|---|
maxValuesPerField |
|
DetectionOptions
JSON representation |
---|
{ "snapshotQuery": string, "detectionList": { object ( |
Fields | |
---|---|
snapshotQuery |
|
detectionList |
|
fieldAggregations |
|
fetchNonAlertingDetections |
|
DetectionListOptions
JSON representation |
---|
{ "maxReturnedDetections": integer } |
Fields | |
---|---|
maxReturnedDetections |
|
FunctionParameter
JSON representation |
---|
{ "groupedFields": [ { object ( |
Fields | |
---|---|
groupedFields[] |
|
selectedFields[] |
|
orders[] |
|
maxReturnedRows |
|
GroupByField
JSON representation |
---|
{ "udmFieldPath": string, "toLowerCase": boolean, // Union field |
Fields | |
---|---|
udmFieldPath |
|
toLowerCase |
|
Union field
|
|
resolutionInNanoSeconds |
|
cidrPrefixLengthInBits |
|
topNLevelDomain |
|
getRegisteredDomain |
|
SelectedField
JSON representation |
---|
{
"udmFieldPath": string,
"functionType": enum ( |
Fields | |
---|---|
udmFieldPath |
|
functionType |
|
percentile |
|
FunctionType
Enums | |
---|---|
FUNCTION_TYPE_UNSPECIFIED |
|
FUNCTION_TYPE_SUM |
|
FUNCTION_TYPE_COUNT |
|
FUNCTION_TYPE_COUNT_DISTINCT |
|
FUNCTION_TYPE_AVERAGE |
|
FUNCTION_TYPE_STDDEV |
|
FUNCTION_TYPE_MIN |
|
FUNCTION_TYPE_MAX |
OrderBy
JSON representation |
---|
{ "fieldIndex": integer, "isDescendingOrder": boolean } |
Fields | |
---|---|
fieldIndex |
|
isDescendingOrder |
|
UdmPrevalenceOptions
JSON representation |
---|
{
"getPrevalence": boolean,
"bucketSize": {
object ( |
Fields | |
---|---|
getPrevalence |
|
bucketSize |
|
UdmSearchAggregationBucketFunction
JSON representation |
---|
{ "resolutionInSeconds": integer } |
Fields | |
---|---|
resolutionInSeconds |
|
FederationMetadata
Federation metadata definition. UI will use this to provide information about the instance and instance groups on which federated search is to be performed.
JSON representation |
---|
{ "instances": [ { object ( |
Fields | |
---|---|
instances[] |
Optional. List of instances on which federated search request is being made. |
federationGroups[] |
Optional. List of instance groups on which federated search request is being made. |
InstanceSelection
Chronicle instance on which federated search request is being made.
JSON representation |
---|
{ "instance": string } |
Fields | |
---|---|
instance |
Required. Chronicle instance name on which federated search request is being made. Format: projects/{project}/locations/{location}/instances/{instance} |
FederationGroupSelection
Chronicle federation group on which federated search request is being made.
JSON representation |
---|
{ "federationGroup": string } |
Fields | |
---|---|
federationGroup |
Optional. Resource name of the Federation Group. Format: projects/{project}/locations/{location}/instances/{instance}/federationGroups/{federationGroup} |
UdmEventList
JSON representation |
---|
{ "events": [ { object ( |
Fields | |
---|---|
events[] |
|
columnNames |
|
progress |
|
tooManyEvents |
|
complete |
|
datatableInfo[] |
|
rows[] |
|
ColumnNames
JSON representation |
---|
{ "names": [ string ] } |
Fields | |
---|---|
names[] |
|
SearchDataTableInfo
JSON representation |
---|
{
"dataTable": string,
"columnInfo": [
{
object ( |
Fields | |
---|---|
dataTable |
|
columnInfo[] |
|
SearchDataTableColumnInfo
JSON representation |
---|
{ "originalColumn": string, "isDefault": boolean } |
Fields | |
---|---|
originalColumn |
|
isDefault |
|
ResultRow
JSON representation |
---|
{ "outcomes": [ { object ( |
Fields | |
---|---|
outcomes[] |
|
Union field
|
|
event |
|
entity |
|
join |
|
EventRecord
JSON representation |
---|
{ "event": { object ( |
Fields | |
---|---|
event |
|
eventLogToken |
|
alertNumber |
|
alertViewId |
A base64-encoded string. |
annotations[] |
|
detections[] |
|
table |
|
tenantId |
Optional. |
Annotation
Enums | |
---|---|
ANNOTATION_UNSPECIFIED |
|
ANNOTATION_ALERT |
EntityContextRecord
JSON representation |
---|
{ "entity": { object ( |
Fields | |
---|---|
entity |
|
eventLogToken |
|
timed |
|
connectedComponentLabel |
Optional. A base64-encoded string. |
detections[] |
|
table |
|
tenantId |
Optional. |
JoinRecord
JSON representation |
---|
{ "events": [ { object ( |
Fields | |
---|---|
events[] |
|
entities[] |
|
EventCountTimeline
JSON representation |
---|
{
"buckets": [
{
object ( |
Fields | |
---|---|
buckets[] |
|
sizeOfBucketMs |
|
EventCountTimelineBucket
JSON representation |
---|
{ "baselineEventCount": integer, "eventCount": integer, "baselineAlertCount": integer, "alertCount": integer, "baselineTimedEntityCount": integer, "filteredTimedEntityCount": integer, "entityChangedCount": { object ( |
Fields | |
---|---|
baselineEventCount |
|
eventCount |
|
baselineAlertCount |
|
alertCount |
|
baselineTimedEntityCount |
|
filteredTimedEntityCount |
|
entityChangedCount |
|
joinsResultCount[] |
|
EntityChangedCountTimelineBucket
JSON representation |
---|
{
"totalChangedEntitiesCount": integer,
"entityChangedInfo": [
{
object ( |
Fields | |
---|---|
totalChangedEntitiesCount |
|
entityChangedInfo[] |
|
EntityChangedInfo
JSON representation |
---|
{
"artifacts": {
object ( |
Fields | |
---|---|
artifacts |
|
entityCount |
|
FieldAndValue
JSON representation |
---|
{ "value": string, "entityNamespace": string, // Union field |
Fields | |
---|---|
value |
|
entityNamespace |
|
Union field
|
|
fieldPath |
|
kvalueType |
|
KValueType
Enums | |
---|---|
UNKNOWN |
|
COLLECTOR_ID |
|
EVENT_SHARD |
|
ASSET_IP_ADDRESS |
|
MAC |
|
HOSTNAME |
|
PRODUCT_SPECIFIC_ID |
|
NAMESPACE |
|
DOMAIN_NAME |
|
RESOLVED_IP_ADDRESS |
|
STEMMED_DOMAIN_NAME |
|
PROCESS_ID |
|
FULL_COMMAND_LINE |
|
FILE_NAME |
|
FILE_PATH |
|
HASH_MD5 |
|
HASH_SHA256 |
|
HASH_SHA1 |
|
RAW_PID |
|
PARENT_PROCESS_ID |
|
EMAIL |
|
USERNAME |
|
WINDOWS_SID |
|
EMPLOYEE_ID |
|
PRODUCT_OBJECT_ID |
|
USER_DISPLAY_NAME |
|
CLOUD_RESOURCE_NAME |
|
REGISTRY_KEY |
|
REGISTRY_VALUE_DATA |
|
REGISTRY_VALUE_NAME |
|
CIDR_BLOCK |
JoinsResultCountTimelineBucket
JSON representation |
---|
{
"tableType": enum ( |
Fields | |
---|---|
tableType |
|
table |
|
baselineCount |
|
filteredCount |
|
TableType
Enums | |
---|---|
TABLE_TYPE_UNSPECIFIED |
|
TABLE_TYPE_EVENT |
|
TABLE_TYPE_ENTITY |
UdmFieldAggregations
JSON representation |
---|
{ "fields": [ { object ( |
Fields | |
---|---|
fields[] |
|
groupByFields[] |
|
complete |
|
UdmFieldAggregation
JSON representation |
---|
{ "fieldName": string, "baselineEventCount": integer, "eventCount": integer, "tooManyValues": boolean, "valueCount": integer, "allValues": [ { object ( |
Fields | |
---|---|
fieldName |
|
baselineEventCount |
|
eventCount |
|
tooManyValues |
|
valueCount |
|
allValues[] |
|
topValues[] |
|
bottomValues[] |
|
aggregationType |
|
UdmValueCount
JSON representation |
---|
{
"value": {
object ( |
Fields | |
---|---|
value |
|
baselineEventCount |
|
eventCount |
|
UdmFieldValue
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
stringValue |
|
int32Value |
|
uint32Value |
|
int64Value |
|
uint64Value |
|
floatValue |
|
doubleValue |
|
enumValue |
|
boolValue |
|
bytesValue |
A base64-encoded string. |
isNull |
|
timestampValue |
Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
UdmFieldAggregationType
Enums | |
---|---|
UNSPECIFIED_FIELD_AGGREGATION_TYPE |
|
UDM_FIELD_AGGREGATION_TYPE |
|
ENTITY_FIELD_AGGREGATION_TYPE |
|
DATA_TABLE_FIELD_AGGREGATION_TYPE |
GroupAggregationByField
JSON representation |
---|
{ "fieldName": string, "fieldValue": { object ( |
Fields | |
---|---|
fieldName |
|
fieldValue |
|
fields[] |
|
baselineEventCount |
|
eventCount |
|
valueCount |
|
Detections
JSON representation |
---|
{ "detections": [ { object ( |
Fields | |
---|---|
detections[] |
|
complete |
|
tooManyDetections |
|
validSnapshotQuery |
|
baselineAlertsCount |
|
filteredAlertsCount |
|
detectionFieldAggregations |
|
FunctionResponse
JSON representation |
---|
{
"rows": [
{
object ( |
Fields | |
---|---|
rows[] |
|
tooManyRows |
|
FunctionResponseRow
JSON representation |
---|
{
"values": [
{
object ( |
Fields | |
---|---|
values[] |
|
UdmPrevalenceResponse
JSON representation |
---|
{
"buckets": [
{
object ( |
Fields | |
---|---|
buckets[] |
|
partialPrevalence |
|
UdmPrevalenceBucket
JSON representation |
---|
{
"prevalence": [
{
object ( |
Fields | |
---|---|
prevalence[] |
|
UdmPrevalence
JSON representation |
---|
{
"artifacts": [
{
object ( |
Fields | |
---|---|
artifacts[] |
|
prevalence |
|
Stats
Stats results when the query is for statistics
JSON representation |
---|
{ "results": [ { object ( |
Fields | |
---|---|
results[] |
Result rows that are queried. |
dataQueryExpression |
Expression that represent the subset of the requested query used to filter data. The expression will be used to enable features such as drill-down from stats results to UDM events. In that case, the new query will be composed by this expression and the expression related to a stats result. |
tooManyResults |
If true, there are too many results to return and some have been omitted. |
totalResults |
The total number of results returned. |
sortOrder[] |
Indicates the columns used for sorting and the order in which they are sorted. If no ORDER section is specified in the query, this will be empty. |
hasJoin |
Indicates to the frontend that the result is a join-stats result. |
ColumnData
Represents a single column in the set of columns returned as the stats query result.
JSON representation |
---|
{ "column": string, "values": [ { object ( |
Fields | |
---|---|
column |
Used to store column names. |
values[] |
To store store column data. |
filterable |
To identify if the column can be used for filtering/drill-downs. |
filterExpression |
Expression used to compose a query for filtering/drill-downs related to the data in this column. |
columnMetadata |
Metadata for the column. |
ColumnType
Singular vs list of values in a column.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
value |
Single value in a column. |
list |
List of values in a column e.g. IPs |
ColumnValue
Value of the column based on data type
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
nullVal |
True if the value is NULL. |
boolVal |
Boolean value. |
bytesVal |
Bytes value. A base64-encoded string. |
doubleVal |
Double value. |
int64Val |
Integer value (signed). |
uint64Val |
Un-signed integer value. |
stringVal |
String value. Enum values are returned as strings. |
timestampVal |
Timestamp values. Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: |
dateVal |
Date values. |
protoVal |
For any proto values that are not any of the above. An object containing fields of an arbitrary type. An additional field |
List
Store list of values in a column.
JSON representation |
---|
{
"values": [
{
object ( |
Fields | |
---|---|
values[] |
List of values in one cell of the column. |
ColumnMetadata
Metadata for a column.
JSON representation |
---|
{ "column": string, "fieldPath": string, "functionNameUsed": string, "functionModule": string, "longitude": boolean, "latitude": boolean } |
Fields | |
---|---|
column |
Name of the column. |
fieldPath |
Field path of the column. eg: "udm.principal.hostname" |
functionNameUsed |
Function name of the column. eg: "ARRAY_IGNORE_NULLS_LIMIT", this corresponds to array function. |
functionModule |
Module name of the column. |
longitude |
Whether the column is a longitude field. |
latitude |
Whether the column is a latitude field. |
ColumnSort
Contains the column name and which direction the column is sorted (ascending or descenging).
JSON representation |
---|
{ "name": string, "descending": boolean } |
Fields | |
---|---|
name |
Name of the column. |
descending |
Whether the column is sorted in descending order (ascending by default); |
SearchDataSource
Data source for stats results in LegacyFetchUdmSearchViewResponse Equivalent to dashboard API
Enums | |
---|---|
SEARCH_DATA_SOURCE_UNSPECIFIED |
Unspecified data source. |
SEARCH_UDM |
Events |
SEARCH_ENTITY |
Entities |
SEARCH_RULE_DETECTIONS |
To be used for detections data source. |
SEARCH_RULESETS |
To be used for ruleset with detections datasource. |
AIOverview
AI generated overview for the search results.
JSON representation |
---|
{
"aiSummary": string,
"suggestions": [
{
object ( |
Fields | |
---|---|
aiSummary |
AI summary for the search results. Markdown formatted. |
suggestions[] |
Suggested actions to continue the investigation in chat. |
complete |
Whether AI overview generation is complete. |