UDM Search

The UDM search function enables you to find Unified Data Model (UDM) events and alerts within your Chronicle instance. UDM search includes a variety of search options, enabling you to navigate through your UDM data. You can search both for individual UDM events and groups of UDM events tied to shared search terms.

For more information about UDM, see Format log data as UDM and Unified Data Model field list.

Access UDM search

To access Chronicle UDM Search, select UDM Search from the application menu on the Chronicle landing page. You can also access UDM search by entering a valid UDM field from any search field in Chronicle and pressing CTRL+Enter.

For a list of all valid UDM fields, see Unified Data Model field list.

Figure 1. UDM Search

Figure 2. UDM Search window which opens with CTRL+Enter

Enter a UDM search

Complete the following steps to enter a UDM search in the UDM Search field. When you finish entering a UDM search, click RUN SEARCH. The Chronicle user interface only allows you to enter a valid UDM search expression. You can also adjust the range of data to search by opening the date range window.

Note: If your search is too broad, Chronicle returns a warning message indicating that it cannot display all of the search results. Reduce the scope of the search and run it again. When a search is too broad, Chronicle is returning the most recent results up to the search limit (1 million events and 1 thousand alerts). There might be significantly more events and alerts that match, but are not being displayed at the moment. Do not analyze these results. Instead, apply additional filters and re-run the original search until you are below the limit.

Figure 3. Run search

UDM queries are based on UDM fields, which are all listed in the Unified Data Model field list. You can also view UDM fields within the context of searches by using Filters or Raw Log Search.

1. To search for events, enter a UDM field name in the search field. The user interface includes automatic completion and displays valid UDM fields based on what you have entered.

2. Once you have entered a valid UDM field, select a valid operator. The user interface displays the available valid operators based on the UDM field you entered. The following operators are supported:

   • <, >
   • <=, >=
   • =, !=
   • nocase -- supported for strings

3. Once you have entered a valid UDM field and operator, enter the corresponding log data you are searching for. The following data types are supported:

   • Enumerated values: the user interface displays a list of valid enumerated values for a given UDM field.

     For example (use double quotes and all caps): metadata.event_type = "NETWORK_CONNECTION"

   • Additional values: you can use 'field[key] = value' to search additional and labels fields for events.

     For example: additional.fields["key"]="value"

   • Bools: you can use true or false (all characters are case-insensitive, and the keyword is not enclosed in quotes).

     For example: network.dns.response = true

   • Integers

     For example: target.port = 443

   • Floats: For UDM fields of the float type, enter a floating point value, such as 3.1. You can also enter an integer, such as 3, which is the equivalent of entering 3.0.

     For example: security_result.about.asset.vulnerabilities.cvss_base_score = 3.1 or security_result.about.asset.vulnerabilities.cvss_base_score = 3

   • Regular expressions: (regular expression must be within slash (/) characters)

     For example: principal.ip = /10.*/

     For more information on regular expressions, see the regular expressions page.

   • Strings

     For example (must use double quotes): metadata.product_name = "Google Cloud VPC Flow Logs"

4. You can use the nocase operator to search for any combination of upper and lowercase versions of a given string:

   • principal.hostname != "http-server" nocase
   • principal.hostname = "JDoe" nocase
   • principal.hostname = /dns-server-[0-9]+/ nocase

5. Backslashes and double-quotes in strings need to be escaped using a backslash character. For example:

   • principal.process.file.full_path = "C:\\Program Files (x86)\\Google\\Application\\chrome.exe"
   • target.process.command_line = "cmd.exe /c \"c:\\program files\\a.exe\""

6. You can use boolean expressions to further narrow possible range of data displayed. The following examples illustrate some types of supported boolean expressions (AND, OR, and NOT boolean operators can be used):

   • A AND B
   • A OR B
   • (A OR B) AND (B OR C) AND (C OR NOT D)

   The following examples illustrate how the actual syntax might appear:

   Login events to the finance server:

   metadata.event_type = "USER_LOGIN" and target.hostname = "finance-svr"

   Example of using a regular expression to search for the execution of the psexec.exe tool on Windows.

   target.process.command_line = /\bpsexec(.exe)?\b/ nocase

   Example of using the more than operator (>) to search for connections where more than 10 MB of data was sent.

   metadata.event_type = "NETWORK_CONNECTION" and network.sent_bytes > 10000000

   Example using multiple conditions to search for Winword launching cmd.exe or powershell.exe.

       metadata.event_type = "PROCESS_LAUNCH" and
       principal.process.file.full_path = /winword/ and
       (target.process.file.full_path = /cmd.exe/ or
       target.process.file.full_path = /powershell.exe/)

7. You can also use UDM Search to search for specific key-value pairs in the Additional and Label fields.

   The Additional and Label fields are used as a customizable 'catch all' for event data that does not fit into a standard UDM field. Additional fields may contain multiple key-value pairs. Label fields may only contain a single key-value pair. However, each instance of the field contains only a single key and single value. The key needs to go inside the brackets and the value must be on the right hand side.

   The following examples show how to search for events containing specified key-value pairs:

       additional.fields["pod_name"] = "kube-scheduler"
       metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"

   The following example shows how to use the AND operator with key-value pair searches:

       additional.fields["pod_name"] = "kube-scheduler" AND additional.fields["pod_name1"] = "kube-scheduler1"

   You can use the following syntax to search for all events that contain the specified key (regardless of what the value is)

       additional.fields["pod_name"] != ""

   You can also use regular expressions and the nocase option:

       additional.fields["pod_name"] = /br/
       additional.fields["pod_name"] = bar nocase

8. You can also use block and single-line comments.

   The following example shows how to use a block comment:

       additional.fields["pod_name"] = "kube-scheduler"
       /*
       Block comments can span
       multiple lines.
       */
       AND additional.fields["pod_name1"] = "kube-scheduler1"

   The following example shows how to use a single-line comment:

       additional.fields["pod_name"] != "" // my single-line comment

9. Click RUN SEARCH to run your UDM search and display the results.

10. Events are displayed on the UDM Search page in the Events timeline table. You can narrow the results further by adding additional UDM fields manually or by using the interface.

View alerts in UDM Search

To view alerts, click on the Alerts tab to the right of the Events tab in the upper right hand corner of the UDM Search page.

How alerts are surfaced

Chronicle evaluates the events returned in UDM search against events that exist for alerts in the customer environment. When a search query event matches an event present in an alert, it is displayed in the alert timeline and the resulting alert table.

Definition of events and alerts

An event is generated from a raw log source that is ingested into Chronicle and processed by Chronicle's ingestion and normalization process. Multiple events can be generated from a single raw log source record. An event represents a set of security-relevant data points that are generated from that raw log.

In a UDM search, an alert is defined as a YARA-L rule detection with alerting enabled. See running a rule against live data to learn more.

Other sources of data can be ingested into Chronicle as alerts, such as Crowdstrike Falcon Alerts. These alerts will not be surfaced within UDM search unless they are processed by the Chronicle Detection Engine as a YARA-L rule.

Figure 4. Alerts timeline

Events that are associated with one or more alerts are marked with an Alert chip in the Event Timeline. If there are multiple alerts associated with the timeline, the chip displays the numbers of associated alerts.

The timeline displays the most recent 1,000 alerts retrieved from search results. When the 1,000 limit is reached, no more alerts are retrieved. To make sure you see all the results relevant to your search, refine your search with filters.

How to investigate an alert

To learn more about an alert, click the alert. This will open Alert viewer to the right hand side of that alert, which shows details about the alert including detection window and risk score.

Figure 5. Alert viewer

To see more details about an alert, click View details. The Alert details page opens to more information about that alert.

Figure 6. Alert details

Note: Limitations. Alerts that are generated from multi-event rules are subject to the limitations of sampled events that are present for multi-event rules (see multiple event rules). This means that multi-event rules which generate alerts may not always be surfaced if events exist outside of the sampled-events which match the search event criteria. Filtering between the Events Table and the Alerts Table is independent, except for time-based filtering, which applies to both tables.

Use reference lists in UDM searches

The process for applying reference lists in Rules can also be used in search. Up to seven lists may be included in a single search query. All types of reference lists (string, regular expression, CIDR) are supported.

You can create lists of any variable you want to track. For example, you could create a list of suspicious IP addresses:

// Field value exists in reference list
principal.ip IN %suspicious_ips

And you can use multiple lists by using AND or OR:

// multiple lists can be used with AND or OR
principal.ip IN %suspicious_ips AND
principal.hostname IN %suspicious_hostnames

Refine the search results

You can use the UDM search user interface to filter and refine results as an alternative to modifying the UDM search and re-running the search.

Timelines chart

The timelines chart provides a graphical representation of the number of events and alerts occurring each day that are being surfaced by the current UDM search. Events and alerts are displayed on the same timeline chart, which is available in both the Events and Alerts tab.

The width of each bar depends on the time interval searched. For example, each bar will represent 10 minutes when the search spans 24 hours of data. This chart is updated dynamically as you modify the existing UDM search.

Note: The maximum time window (start time to end time) you can search is 90 days.

Figure 8. Events timeline chart

Time range adjustment

You can adjust the time range for the chart by moving the white slider controls left and right to adjust the time range and focus on the period of interest. As you adjust the time range, the UDM Fields and Values and Events tables are updated to reflect the current selection. You can also click on a single bar on the graph to list just those events in that time period.

Once you have adjusted the time range, the Filtered Events and Query Events checkboxes will appear, enabling you to further limit the types of events displayed.

Figure 9. Events timelines chart with time range controls

Modify the UDM Search with Quick Filters

Using Quick Filters, you can further narrow your UDM search. You can either scroll through the list of UDM fields or search for specific UDM fields or values using the Search field. The UDM fields listed here are associated with the existing lists of events generated by your UDM search. Each UDM field includes the number of events within your current UDM search that also include this piece of data. The list of UDM fields display the total unique number of values within a field. This feature enables you to hunt for particular types of log data that might be of further interest.

The UDM fields are listed in the following order:

1. Fields with the highest event counts to the lowest event counts.
2. Fields with only 1 value are always last.
3. Fields with the exact same event count total are ordered alphabetically from A through Z.

Note: For each UDM Field, you can view the top 30 and bottom 30 values.

Figure 10. Quick Filters

Modify a Quick Filter

If you select a UDM field value in the Quick Filters list and click the menu icon, you are given the option to either Show only events which also include that UDM field value or to Filter out that UDM field value. If the UDM field stores integer values (example: target.port) you will also see options to filter by <,>,<=,>=. Filter options will shorten the list of displayed events.

You can also pin fields (using the push pin icon) in Quick Filter to save them as a favorite. They will appear at the top of the Quick Filters list.

Figure 11. Example: Select Show Only

These additional UDM filters are also added to the filter events field above. The filter events field helps you to keep track of the additional UDM fields you have added to the UDM search. You can also quickly remove these additional UDM fields as needed.

Figure 12. Filter events

If you click the Filter events menu icon or Add Filter to the left, a window opens enabling you to select additional UDM fields.

Figure 13. Filter events window

When you click APPLY to Search and Run, the UDM fields are added to the Filter events field (see Figure 8) and the displayed events are filtered based on those additional filters. You can also click Apply to Search and Run to add these to the main UDM Search field at the top of the page. The search is automatically run again using the same date and time parameters. Google recommends narrowing your search down as much as possible before clicking APPLY to Search and Run. This helps to improve accuracy and reduces search times.

View events in the Events table

All of these filters and controls will update the list of events displayed in the Events table. Click on any of the listed events to open the Log Viewer where you can examine the raw log and the UDM record for that event. If you click on the timestamp for an event, you can also navigate to the associated Asset, IP address, Domain, Hash, or User view. You can also use the Search field at the top of the table to find a specific event.

Note: The Events table only displays the 10,000 most recent events based on any filters that have been applied.

Figure 14. Events table

View alerts in the Alerts table

You can view alerts by clicking the Alerts tab on the right-hand side of the Events tab. You can use Quick Filters to sort alerts by:

• Case
• Name
• Priority
• Severity
• Status
• Verdict

This allows you to focus in on the alerts that are most important to you.

Alerts are displayed on the same time frame as the events are in the Events tab. This allows you to easily see the connection between events and alerts.

If you want to learn more about a specific alert, click the alert, and an individual alert detail page opens up that contains more in-depth information about that alert.

View events in the Event Viewer

If you hover over an event in the Events table, the open event viewer icon appears on the right side of the highlighted event. Click it to open the Event Viewer.

Figure 15. Event Viewer

The Raw Log window displays the original raw log in any of the following formats:

• Raw
• JSON
• XML
• CSV
• Hex/ASCII

The UDM window displays the structured UDM record. You can hover over any of the UDM fields and a popup displays the UDM definition. By selecting the checkbox for the UDM fields, you get additional options:

• You can copy the UDM record. Select one or more UDM fields and then select the Copy UDM option from the View Actions drop down menu. The UDM fields and UDM values are copied to the system clipboard.

• You can add the UDM fields as columns in the Events table by selecting the Add Columns option from the View Actions drop down menu.

Use the Columns option for UDM Search

Use the Columns option to adjust which columns of information are displayed in the Events table. The Columns pop-up menu is displayed. The options available vary depending on the types of events returned by the UDM Search.

You can optionally save the set of columns you have selected here by clicking Save. Give the set of selected columns a name and click Save again. You can load a set of saved columns by clicking Load and selecting the set of saved columns from the list.

You can also download the displayed events by clicking the three dot menu and selecting Download as CSV. This will download all of the search results up to one million events. The user interface will indicate the number of events it will download.

Figure 16. UDM Search columns

Run a search in Quick Searches

1. Click Quick Searches to open the Quick Searches window. This window displays your saved searches and search history.

2. Click any of the searches listed to load it into the UDM search field.

3. Click Run search when you are ready.

The searches listed are saved to your Chronicle account. If you need to modify any of your saved searches (for example, rename an existing search), delete saved searches, or delete searches from your search history, open the Search Manager by clicking See All Searches.

Use templates in Quick Searches

1. Open Quick Searches by clicking Quick Searches to the right of UDM Search.
2. Three panels appear: Saved, Templates, and History. Templates contains pre-made templates. Each comes with a brief description of the task the search will perform.
3. When you click on one of the templates, it can either be loaded directly into the editor (if no input is needed) or opened in a new panel (if input is needed).
4. If you chose one that does require input (for example, User Logins by product/vendor), enter the required values into the open fields. All fields must be completed if they are required to conduct the search.
5. After you have entered your information, click Load Search. This will load the template to the editor.

To exit Quick Searches, click Cancel and you will be taken back to the Quick Searches panel.

The searches listed are saved to your Chronicle account. If you need to modify any of your saved searches (for example, rename an existing search), delete saved searches, or delete searches from your search history, open the Search Manager by clicking See All Searches.

Figure 17. Quick Searches window

Saved searches and search history overview

Use the Search Manager to retrieve saved searches and view your search history by clicking Search Manager. Saved searches and search history are both stored with your Chronicle account. Saved searches and search history are only viewable and accessible by the individual user unless you use the Shared Search feature to share your search with your organization.

Figure 18. Search Manager

Use templates in Search Manager

Note: Search templates are read-only. You can only input values, load templates, and run the templates as a search. You cannot edit or duplicate search templates.

1. Open Search Manager by clicking on the Search Manager tab next to Quick Searches.
2. Three tabs will appear: Saved, Templates, and History. Click on Templates.
3. Choose the template you want to use.
4. If you selected a template that requires additional input, enter the information needed in the open fields and then click Load Search. If you selected a template that does not require you to enter any information, click Load Search.

Save a search

To save a search:

1. From the UDM Search page, click SAVE to save your UDM search for later. This opens the Search Manager. Google recommends giving your saved search a meaningful name.

2. Click Save Edits when you have finished.

3. To view saved searches, click Search Manager and then click the Saved Searches tab.

Retrieve a saved search

To retrieve and run a saved search:

1. Click Saved Searches.

2. Select a saved search from the list. These saved searches are saved to your Chronicle account. You can delete a search by clicking delete.

3. You can change the name of the search. Click Save Edits when you have finished.

4. Click Load Search. The search is loaded into the main UDM search field.

5. Click RUN SEARCH to see the events associated with this search.

Retrieve a search from your search history

To retrieve and run a search from your search history:

1. Click Search History.

2. Select a search from your search history. Your search history is saved to your Chronicle account. You can delete a search by clicking delete.

3. Click Load Search. The search is loaded into the main UDM search field.

4. Click RUN SEARCH to see the events associated with this search.

Clear, disable, or enable search history

To clear, disable, or enable search history:

1. Click

2. Select Clear Search History to clear the search history.

3. Click Disable to disable search history. You'll have the option to either:

   • Opt-Out Only—Disable search history.

   • Opt-Out and Clear—Disable search history and delete the saved search history.

4. If you have previously disabled search history, you can enable it again by clicking Enable Search History.

5. Click Close to exit the Search Manager window.

Share a search

Shared searches allow you to share searches with the rest of your team. In the Saved Searches tab, you can share, duplicate, or delete searches. You can also filter your searches by clicking the filter icon next to the search bar and sort searches by All, Shared, or Edited by Me.

If you edit a shared search, you will need to save it as your own Saved Search. Your edits will not update the original Shared Search.

Note: You cannot share with just one person. If you share your search, it will be shared with your whole organization.

1. Click Saved Searches
2. Click on the search you want to share
3. Click on the right hand side of the search. A dialog box with the option to share your search appears.
4. Click Share with everyone
5. A pop-up will appear that says Sharing your search will be visible to people in your organization. Are you sure you want to share? Click Yes Share.

If you want the search to only be visible to you, click and then click Make private. If you stop sharing, only you can use this search.