Use UDM Search to investigate an entity

Supported in:

During an investigation, you can write a UDM Search query to display details about one or more entities (for example, an IP address, user, or asset) in addition to the events and alerts that match the search query terms.

On systems that use data RBAC, you can only see data that matches your scopes. For more information, see data RBAC impact on Search.

When a search query includes a condition that identifies a specific entity (for example, principal.ip="10.0.31.20"), the search results include details about the entity (if present in your enterprise) in addition to UDM events that match the entire search query.

The search results pane includes the following tabs:

  • Overview—Details about one or more specific entities.
  • Events—Search results that match the entire search query and search time range.
  • Alerts—Alerts generated by events that match the entire search query.

UDM Search query conditions can include both UDM fields (principal.hostname="alice") and grouped fields (hostname="alice").

The UDM Search query can include multiple conditions, each specifying a different entity identifier. Example queries include the following:

  • principal.hostname="alicehost" and user="alice"
  • principal.hostname="alicehost" and (user="kai" or user="alice")
  • principal.hostname="alicehost" and target.hostname="altostrat.com"
  • principal.hostname="alicehost" and hash="40a80612aaa8a8a36aa82a1278aaa02a"
  • hostname="alicehost" and domain=/altostrat.com/ nocase
  • user="alice" and domain=/altostrat.com/ nocase

The following table includes example UDM Search queries for one or more entities and the type of information displayed:

Information type Example UDM Search queries
Asset
  • hostname="laptop-kai"
  • principal.hostname="laptop-kai"
  • principal.ip="10.0.0.76" //(private IP address)
  • principal.mac="c5:0c:9c:aa:bb:c4"
  • principal.hostname="laptop-kai" and metadata.event_type = "NETWORK_CONNECTION"
  • hostname="laptop-kai" or hostname="desktop-kai"
Domain
  • domain="example.com"
  • target.hostname="example.com"
File
  • hash="44a88612faa8a8f36ae82a1278aaa02a"
  • principal.process.file.md5="a00000a75f2a35130aa7a7aaa09aaa7a"
IP
  • ip="8.8.8.8"
  • target.ip="203.0.113.204" //(public IP address)
User
  • user="alice"
  • target.user.email_address="smitha@example.com"
  • principal.user.userid="alice" or target.user.userid = "smitha"
  • email="john@altostrat.com" or email="alice@example.com"
  • principal.user.userid="smitha"

Overview tab

The Overview tab displays entity information in one of the following predefined information types. The information presented varies depending on the information type.

Asset details

When the UDM Search query includes a condition that returns a specific asset, for example principal.hostname="laptop-will" or principal.ip="10.0.0.76", the Overview tab displays the Asset view with information in the following panels:

  • Search summary—Displays the following information:
    • Details about the entity, including the IP address and MAC address associated with the asset during the search time range. The IP address and MAC address can also be used to identify an entity and can by clicked to display additional information in the entity viewer. It also displays the first time the asset was seen in your enterprise and when it was last (most recently) seen. You can click either timestamp (first or last) to run a new search using that time.
    • Details about alerts, including a graph showing the number of alerts that involved the entity within the search time range. The panel also lists a subset of rules with the highest number of alerts.
    • Click Open Alerts & IOCs to see all alerts generated during the same search time range.
    • Click View In Alerts Tab to switch to the Alerts tab on this page and start a new search against the selected entity.
    • Click one of the bars on the chart to switch to the Alerts tab on this page and start a new search against the selected entity, using the time range of the clicked bar.
    • Click the View more link to open the Entity fields view and display all of the entity fields associated with the asset. To copy an entity field to the clipboard, click the checkbox next to the entity field, click View actions, and click Copy entity. Click the checkbox at the top to select all of the entities.
  • Relevant IOCs—Displays IOCs associated with the asset. IOCs assigned a higher severity are displayed first. Clicking the IOC name opens the entity viewer to the right.
  • Associated entities—Displays other entities that this asset is related to, such as users who signed in to the asset. The panel displays the type of entity, when it was first seen in the environment, and when it was last (most recently) seen. It also displays any namespaces associated with an asset. Click an entity to open the Entity context panel. Click Show all time to display the associated entities over the entire available time period as opposed to the range specified in the UDM search.
  • Entity context—Displays details about the entity you selected in the Associated entities panel. This panel displays different information depending on the type of entity you selected in the Associated entities panel (for example, user or domain).
  • Go to legacy view—Navigate to the legacy Asset investigation view. For more information, see Investigate an asset.

Domain details

When the UDM Search query includes a condition that specifies a specific domain, for example target.hostname="example.com", the Overview tab displays the Domain details with information in the following panels:

  • Search summary—Displays the following information:
    • Details about the domain, including the WHOIS information associated with the registered domain, the first time it was seen in your enterprise, and the last (most recent) time it was seen. Click VT Context to view information about the domain from VirusTotal.
    • Details about alerts, including a graph showing the number of alerts that involved the entity within the search time range. The panel also lists a subset of rules with the highest number of alerts.
    • Click Open Alerts & IOCs to see all alerts generated during the same search time range.
    • Click View In Alerts Tab to switch to the Alerts tab on this page and start a new search against the selected entity.
    • Click one of the bars on the chart to switch to the Alerts tab on this page and start a new search against the selected entity, using the time range of the clicked bar.
    • Click the View more link to open the Entity fields view and display all of the entity fields associated with the domain. To copy an entity field to the clipboard, click the checkbox next to the entity field, click View actions, and click Copy entity. Click the checkbox at the top to select all of the entities.
  • Resolved IPs—Displays all resolved IP addresses that have been seen in your enterprise for the fully qualified domain name (FQDN). For example, if you search for target.hostname="test.altostrat.com", the search results might display two resolved IP addresses (198.51.100.81 and 203.0.113.81).
  • Sub-domains and sibling domains—Displays all associated subdomains that have been seen in your enterprise for a given FQDN. Many adversaries use the same domain and subdomain for their attacks. For example, if you search for target.hostname="sandbox.altostrat.com", this panel displays two subdomains, test.sandbox.altostrat.com and staging.sandbox.altostrat.com.
  • Prevalence of assets—Shows the number of assets in your enterprise that have connected to the domain for the entire time period of the data stored in your Google Security Operations account. Each bar of the graph represents the number of unique assets in your enterprise that have connected to the domain on a UTC day. Hovering over a bar displays the related entities on the UTC day represented by the bar. Click the entity name to see the entity summary and overview in the entity context panel displayed to the right. Click View events to see the events related to the selected entity in the search events tab.
  • Associated entities—Displays other entities that this domain is related to, such as assets that have contacted this domain. The list includes the type of entity, when it was first seen in your enterprise, and when it was last (most recently) seen. Click an entity to open the Entity context panel.
  • Entity context—Displays details about the entity you selected in the Associated entities panel. This panel displays different information depending on the type of entity you selected in the Associated entities panel (for example, IP address or domain).
  • Go to legacy view—Navigate to the legacy Domain investigation view. For more information, see Investigate a domain.

File details

When the UDM Search query includes a condition that returns a single file, for example principal.process.file.md5="a00000a75f2a35130aa7a7aaa09aaa7a", the Overview tab displays the File details with information in the following panels:

  • Search summary—Displays the following information:
    • Details about the file, including hash values, file size, the first time it was seen in your enterprise, and the last (most recent) time it was seen. Click VT Context to view information about the file from VirusTotal.
    • Details about alerts, including a chart showing the number of alerts that involved the entity within the search time range. The panel also lists a subset of rules with the highest number of alerts.
    • Click Open Alerts & IOCs to see all alerts generated during the same search time range.
    • Click View In Alerts Tab to switch to the Alerts tab on this page and start a new search against the selected entity.
    • Click one of the bars on the chart to switch to the Alerts tab on this page and start a new search against the selected entity, using the time range of the clicked bar.
    • Click the View more link to open the Entity fields view and display all of the entity fields associated with the file. To copy an entity field to the clipboard, click the checkbox next to the entity field, click View actions, and click Copy entity. Click the checkbox at the top to select all of the entities.
  • Relevant IOCs—Displays IOCs associated with the file. IOCs assigned a higher severity are displayed first. Clicking the IOC name opens the entity viewer to the right.
  • Prevalence of assets—Shows the number of assets in your enterprise associated with the file for the entire time period of the data stored in your Google Security Operations account.
  • Associated entities—Displays other entities that this file is related to, such as an asset where this file was executed or users who accessed the file. The list includes the type of entity, when it was first seen in your enterprise, and when it was last (most recently) seen. Click an entity to open the Entity context panel.
  • VirusTotal properties & metadata—Displays information about the file from the VirusTotal database. Click View more to open a VirusTotal dialog and display additional information about the file.
  • Associated entities—Displays different information depending on the type of entity you selected in the Associated entities panel (for example, user or asset).
  • Entity context—Displays details about the entity you selected in the Associated entities panel. This panel displays different information depending on the type of entity you selected in the Associated entities panel (for example, user or asset).
  • Go to legacy view—Navigate to the legacy File investigation view. For more information, see Investigate a file.

IP details

When the UDM Search query includes a condition that returns a specific external IP address, for example target.ip="203.0.113.254", the Overview tab displays the IP details with information in the following panels:

  • Search summary—Displays the following information:
    • Details about the IP address, including the first time it was seen in your enterprise and the last (most recent) time it was seen. Click VT Context to view information available about this IP address from VirusTotal.
    • Details about alerts, including a graph showing the number of alerts that involved the entity within the search time range. The panel also lists a subset of rules with the highest number of alerts.
    • Click Open Alerts & IOCs to see all alerts generated during the same search time range.
    • Click View In Alerts Tab to switch to the Alerts tab on this page and start a new search against the selected entity.
    • Click one of the bars on the chart to switch to the Alerts tab on this page and start a new search against the selected entity, using the time range of the clicked bar.
    • Click the View more link to open the Entity fields view and display all of the entity fields associated with the IP address. To copy an entity field to the clipboard, click the checkbox next to the entity field, click View actions, and click Copy entity. Click the checkbox at the top to select all of the entities.
  • Relevant IOCs—Displays IOCs associated with the IP address. IOCs assigned a higher severity are displayed first. Clicking the IOC name opens the entity viewer to the right.
  • Prevalence of assets—Shows the number of assets in your enterprise that have connected to the IP address over the time period specified in the UDM search.
  • Associated entities—Displays other entities that this IP address is related to, such as domains the IP address is registered to. The list includes the type of entity, when it was first seen in your enterprise, and when it was last (most recently) seen. Click an entity to open the Entity context panel.
  • Entity context—Displays details about the entity you selected in the Associated entities panel. This panel displays different information depending on the type of entity you selected in the Associated entities panel (for example, domain or asset). If the link is displayed, click VT Context to view information about the entity from VirusTotal.
  • Go to legacy view—Navigate to the legacy IP Address investigation view. For more information, see Investigate an IP address.

User details

When the UDM Search query includes a condition that returns a specific user, for example principal.user.userid="alice", the Overview tab displays the User details with information in the following panels:

  • Search summary—Displays the following information:
    • Details about the entity, including the full name, first time seen in your enterprise and the last (most recent) time seen, title, and email address.
    • Details about alerts, including a graph showing the number of alerts that involved the entity within the search time range. The panel also lists a subset of rules with the highest number of alerts.
    • Click Open Alerts & IOCs to see all alerts generated during the same search time range.
    • Click View In Alerts Tab to switch to the Alerts tab on this page and start a new search against the selected entity.
    • Click one of the bars on the chart to switch to the Alerts tab on this page and start a new search against the selected entity, using the time range of the clicked bar.
    • Click the View more link to open the Entity fields view and display all of the entity fields associated with the user. To copy an entity field to the clipboard, click the checkbox next to the entity field, click View actions, and click Copy entity. Click the checkbox at the top to select all of the entities.
  • Associated entities—Displays entities that this user is related to, such as domains the user contacted or assets the user accessed. The list includes the type of entity, when it was first seen in your enterprise, and when it was last (most recently) seen. Click an entity to open the Entity context panel.
  • Entity context—Displays details about the entity you select in the Associated entities panel. The information in this panel is different depending on the type of entity (for example, asset or domain).
  • Go to legacy view—Navigate to the legacy User investigation view. For more information, see Investigate a user.

Events tab

The Events tab displays the events connected to your UDM search over the given time range. These events are listed in the Events table. Clicking an event's timestamp opens a dialog displaying the assets and files associated with the event. Clicking on any of these items opens the Entity context panel which provides additional information about the entity including a list of any associated alerts and an alert graph showing the frequency of those alerts over time.

For information on UDM events, see Structure of a UDM Event.

Use the Pivot option to open the Pivot settings. These settings let you analyze events using expressions and functions against the results from the UDM Search. For more information, see Use the Pivot Table to analyse events.

Trend over time chart

The Trend over time chart displays the events over the time period specified in the UDM search. Alerts are shown in red beneath the chart. Clicking one of the bars narrows the focus of the Events tab to that period of time. The events associated with that time slot are displayed in the Events table.

Domain prevalence chart

The Domain prevalence chart displays the prevalence of the domains associated with your search within your enterprise. Hovering over one of the circles on the chart displays the specific domain and lets you narrow your search to events associated with that domain only. The chart is only displayed if your UDM search includes a domain.

Alerts tab

The Alerts tab lets you display detailed information about the alerts connected to your UDM search.

  • Graph—Displays the number of alerts per period over the time specified in the UDM search (period varies depending on length of search). The Filtered alerts checkbox lets you view or hide the alerts processed by the Filters options. The Query alerts checkbox lets you view or hide all of the alerts processed by the UDM search.
  • Filters—Lets you filter alerts based on the options listed. For example, you could click Severity, click the menu option for Medium, and select Show only. The graph and table reload to display only the alerts with medium severity.
  • Alerts table—Displays the alerts associated with the UDM search. Clicking an alert opens the Alert viewer to display additional information. Clicking View details opens the Alerts and IOCs view (see View Alerts and IOCs). If you click a specific filter bar in the graph, only the alerts associated with that bar are displayed. Similarly, if you add filters, the table reloads and displays only the alerts tied to your selections.