# Investigate alerts

Supported in:

Alerts are security events identified by your security infrastructure or
Google Security Operations detection rules. You can use them to identify, analyze,
and respond to potential threats.

Alerts generated by detection rules require human or agentic review. They include
state data that you can manage in cases for investigation and incident workflow
management.

Google SecOps provides the tools to help you investigate
alerts and add context to cases:

- **Enrichment**: Adds context to a Unified Data Model (UDM) indicator or event by
  identifying related entities, populating additional details, and incorporating
  global enrichment data.

  Google SecOps offers two types of enrichment. First, it automatically enriches
  events with threat intelligence and other contextual data. Second, you can use
  playbooks to add contextual information to cases.
- **Triage and Investigation Agent (TIN)**: Uses Gemini to analyze alerts to determine
  whether they are true or false positives, and provide a summary of the reasoning and findings.

## Investigate an alert

Alerts are located either within associated Cases or as independent entries on
the **Alerts \& IOCs** page. Google SecOps detection rules identify event, entity,
or metric data as a threat. Alerts are tied to this identified data.

Alert detail views give you context about the alert and related entities. This
context lets you or your agentic systems determine if an alert is beningn or
indicates malicious activity.

When you click an alert, you are directed to a page that contains alert details
organized into the following three tabs:

- **Overview**: provides a summary of important details about the alert,
  including alert status and detection window.

  The **Detection Summary** section on the tab identifies the specific rule that
  triggered the alert. Reviewing other alerts from the same rule can help
  identify patterns or potential misconfigurations.
- **Graph** : visualizes alerts that are generated from a YARA-L rule. It
  provides a graph of the alert's relationship to other entities. When an
  alert is triggered, entities associated with the alert are displayed on the
  graph and on the left side of the screen, each with its own card. The alert
  graph uses the following entities in a UDM event:
  `principal`, `target`, `src`, `observer`, `intermediary`, and `about`
  .

- **Alert history**: lists all the changes that have happened to this alert,
  including when the status of an alert has changed or a note has been added.

Below the graph that visualizes the relationships between the entities and the
alert are the following three subtabs that provide more context about the alert:

- **Events**: contains details about the events related to the alert.
- **Entities**: contains details about each entity associated with the alert.
- **Alert Context** : provides [additional context](https://docs.cloud.google.com/chronicle/docs/investigation/investigate-alert.md.txt#alert-context) about the alert.

> [!NOTE]
> **Note:** **SIEM Search** provides enhanced capabilities that let you conduct more thorough investigations of the events and alerts within your Google Security Operations instance than is possible using the **Alerts \& IOCs** page alone. For more information, see [Understand search](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search.md.txt).

## Investigate entity context

To understand entities and their importance, you can investigate a few product
areas. First, perform a UDM search for the entity to find additional events.
Using the entity's most reliable indicator, search **Risk Analytics** to review its
overall risk score, detections, and alerts. Finally, check whether the entity is
on a watchlist to determine if it requires more attention.

### View context events for entities

**Entity Context in Search** lets you search for context events related to
specific entities. For example, build a search query using `graph.entity.hostname`
to locate all context events associated with a specific hostname.

For more information, see [Conduct a search for entity context
data](https://docs.cloud.google.com/chronicle/docs/investigation/entity-context-in-search) and [Investigate
an entity using SIEM
Search](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search-investigate-entity).

### Risk Analytics lookup for entities

Risk Analytics helps you identify and prioritize risky entities. The risk score
calculation for each entity is based on the risk score of its findings, and then
gets adjusted using a mix of user-defined parameters and system-defined parameters.

When assigning a risk score, Risk Analytics selects the most reliable entity
based on the predefined alias precedence. The highest-ranked alias is used to
associate detections with an entity and calculate its risk score.

For more information, see [Entity precedence for assigning risk score](https://docs.cloud.google.com/chronicle/docs/detection/risk-analytics-overview.md.txt#entity_precedence_for_assigning_risk_score) and
[Example risk score calculation](https://docs.cloud.google.com/chronicle/docs/detection/risk-analytics-overview.md.txt#example_risk_score_calculation).

### Watchlists

Watchlists let you curate entities to monitor, boost, or suppress their risk
scores in the system. This helps you prioritize investigations even when
automated risk is low.

For more information, see [Watchlist Quickstart guide](https://docs.cloud.google.com/chronicle/docs/detection/watchlist-getting-started.md.txt).

## View alert history

The **Alert history** tab lets you see a full history of all of the actions
that have taken place for this alert. This includes:

- When the alert first appeared
- Any notes people on your team have left about this alert
- If the severity has changed
- If priority has been changed
- If the alert has been closed

## View similar alerts

Use rules and entities to identify related alerts:

- To view alerts generated by the same rule, click **View Other Alerts From This Rule** in the **Detection Summary** section of the **Overview** tab in the **Alert** view.
- To view alerts associated with an entity, click the entity to open the **Entity context** panel. Alerts that share entities can be grouped into the same case.

## Change the alert status

1. Click **Update Alert** in the upper right hand corner.
2. In the window that appears, update the severity and priority levels accordingly.
3. Click **Save**.

## Close the alert

1. Click **Close Alert**.
2. In the window that appears, you have the option to leave a note to add more context about why you closed the alert.
3. Enter your information and press **Save**.

> [!NOTE]
> **Note:** You cannot change the alert status for managed alerts.

### Close the alert by closing the case

Close an alert by closing its associated case after completing the investigation.
Alerts are linked to cases and are resolved as part of the case workflow. Close
the case from the case details page or cases queue. In the **Close Case** dialog,
select a valid reason and a root cause for closing the case.

## Alerts from Google Security Operations SOAR

Alerts from Google Security Operations SOAR include additional information about the
Google Security Operations SOAR case. These alerts also provides a link to open the case
in Google Security Operations SOAR. For more information, see the [Google Security Operations SOAR cases
overview](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-cases/cases-overview).

![Alert for Google Security Operations SOAR case](https://docs.cloud.google.com/chronicle/images/alert-with-case.png)

**Alert for Google Security Operations SOAR case**

> [!NOTE]
> **Note:** You cannot update a Google Security Operations SOAR alert from the alert options menu. You need to navigate to Google Security Operations SOAR to perform this action by clicking the case name in the **Case Details** panel.

## Prerequisites for alert graph

To populate the alert graph, you need to [create a YARA-L
rule](https://docs.cloud.google.com/chronicle/docs/detection/manage-all-rules) that generates alerts. The
quality of the alert graph is tied to the context that is built into the YARA-L
rule. The [outcome section](https://docs.cloud.google.com/chronicle/docs/yara-l/outcome-syntax.md.txt) of a rule
provides context to the detections triggered by the rule.

We recommend adding the following [UDM
nouns](https://docs.cloud.google.com/chronicle/docs/reference/udm-field-list#udm_event_data_model) to the
outcome section, because they are used in the alert graph:
`principal`, `target`, `src`, `observer`, `intermediary`, and `about`
. For these
UDM nouns, the following fields are used in the alert graph:

- `artifact.ip`
- `asset.asset_id`
- `asset.hostname`
- `asset.ip`
- `asset.mac`
- `asset.product_object_id`
- `asset_id`
- `domain.name`
- `file.md5`
- `file.sha1`
- `file.sha256`
- `hostname`
- `ip`
- `mac`
- `process.file.md5`
- `process.file.sha1`
- `process.file.sha256`
- `resource.name`
- `url`
- `user.email_addresses`
- `user.employee_id`
- `user.product_object_id`
- `user.userid`
- `user.windows_sid`

The values in the preceding list of UDM fields also link to **SIEM Search** from the **Alert Context** subtab. For more information, see [View context about the alert](https://docs.cloud.google.com/chronicle/docs/investigation/investigate-alert.md.txt#alert-context).

In the following YARA-L rule, an alert is generated when a significant number of Google Cloud service APIs have been disabled within a short timeframe (1 hour).

    rule gcp_multiple_service_apis_disabled {

      meta:
        author = "Google Cloud Security"
        description = "Detect when multiple Google Cloud Service APIs are disabled in a short period of time."
        severity = "High"
        priority = "High"

      events:
        $gcp.metadata.event_type = "USER_RESOURCE_UPDATE_CONTENT"
        $gcp.metadata.log_type = "GCP_CLOUDAUDIT"
        $gcp.metadata.product_event_type = "google.api.serviceusage.v1.ServiceUsage.DisableService"
        $gcp.security_result.action = "ALLOW"
        $gcp.target.application = "serviceusage.googleapis.com"
        $gcp.principal.user.userid = $userid

      match:
        $userid over 1h

      outcome:
        $risk_score = max(75)
        $network_http_user_agent = array_distinct($gcp.network.http.user_agent)
        $principal_ip = array_distinct($gcp.principal.ip)
        $principal_user_id = array_distinct($gcp.principal.user.userid)
        $principal_user_display_name = array_distinct($gcp.principal.user.user_display_name)
        $target_resource_name = array_distinct($gcp.target.resource.name)
        $dc_target_resource_name = count_distinct($gcp.target.resource.name)

      condition:
        $gcp and $dc_target_resource_name > 5
    }

After an alert is generated, you can navigate to the **Graph** tab in the **Alert** view to
obtain more context about the alert and to further investigate it.

## Navigate to the Alert graph

You can access the **Graph** tab from the **Alerts \& IOCs** page or the **SIEM
Search** page.

### Access the Alert graph from Alerts \& IOCs

The **Alerts \& IOCs** page lets you filter and
view all the alerts and IOCs that are affecting your enterprise. To
learn more about this page and how to view IOC matches, visit [View Alerts and
IOCs](https://docs.cloud.google.com/chronicle/docs/investigation/alerts-iocs).

To view more information about an alert from the **Alerts \& IOCs** page,
complete the following steps:

1. From the navigation bar, click **Detection** \> **Alerts \& IOCs**.
2. Find the alert you want to investigate in the alerts table.
3. In that alert's row, click the alert name in the **Name** column to open the **Alert** view, and then click the **Graph** tab.

### Access the Alert graph from SIEM Search

To view the alert graph from the **SIEM Search** page, complete the following
steps:

1. In the navigation bar, click **Investigation** \> **SIEM Search**.
2. Load a search with **Search Manager** or create a new search. For more information about running a UDM search, see [Understand
   search](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search).
3. Click the **Alerts \& Detections** tab.
4. Click the alert you want to investigate in the **Detections** table. The **Alert Viewer** opens.
5. Click **View details** to open the **Alert** view.
6. Click the **Graph** tab to view the alert graph.

## View details about an alert

In the **Alert** view, the **Overview** tab displays the following information with
regards to the alert:

- **Alert Details**: Alert status, creation date, severity, priority, and risk score.
- **Detection Summary**: Detection rule that generated the alert. You can view other alerts from the same detection rule.
- **Events**: Events associated with this alert.
- **Inputs**: Details the data sources that generated the alert. The contents
  vary depending on the following alert types.

  - **Standard detection**: Displays the events and associated entities that
    triggered the rule.

  - **Composite detection**: Displays the events, entities, and the underlying
    detections that served as inputs to the rule.

  An alert is a [composite detection](https://docs.cloud.google.com/chronicle/docs/detection/composite-detections.md.txt) when:
  - The **Inputs** column shows **Detection** as a source.

  - The **Detection Type** column displays an **Alert** or **Detection** label
    with a number next to it (for example, `Alert (3)`).

  This indicates that a detection, or a chain of detections, triggered the alert,
  rather than raw events or entities alone.

  You can view and analyze these underlying detections in the **Detections**
  table by using the following features:
  - Expand the rows to view nested detections, associated event data, and
    related entity information.

  - Customize your view by using the column manager to select and arrange
    columns in the table.

In addition to viewing important information, you can adjust the alert status.

## View entity relationships

The **Graph** tab shows you how different alerts and entities are connected. This
feature gives you a visual, interactive graph that you can use to expand
relationship information about existing entities to expose unknown
relationships. You can also expand your search by increasing the time range and
expanding past point-in-time alerts for richer alert paths.

You can also expand your search by clicking the **+** icon in the upper right
hand side of any node. Doing this displays all the nodes related to that entity.

### Graph icons

Different entities are represented by different icons.

|---|---|---|
| **Icon** | **Entity the icon represents** | **Explanation** |
|   | User | A user is a person or other entity that requests access to and uses information from your network. Examples: janedoe, cloudysanfrancisco@gmail.com |
| database | Resource | Resources are a generic term for entities that have their own unique resource name. Examples: BigQuery table, database, and project. |
|   | IP Address |   |
| description | File |   |
|   | Domain name |   |
|   | URL |   |
| device_unknown | Unknown entity type | An entity type not recognized by Google SecOps's software. |
| memory | Asset | An asset is anything that produces value for your organization. This can include hostnames, MAC addresses, and internal IP addresses. Examples: 10.120.89.92 (internal IP address), 00:53:00:4a:56:07 (MAC address) |

If two or more alerts come from the same rule, they are grouped together in a
group icon. Indicators that represent the same entity are consolidated into one
icon.

To learn more about investigating entities and resources represented by these icons, review the following documents:

- [Investigate an entity using SIEM
  Search](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search-investigate-entity)
- [Resource-oriented design](https://docs.cloud.google.com/apis/design/resources)

### Navigate the alert graph

When you click the **Graph** tab, the graph shows all results 12 hours before and
after the alert. If there are no entities for the alert, only the original alert
appears on the graph.

The main alert is highlighted in a red circle. Alerts are connected to entities
with a solid line and other alerts with a dotted line. If you hold the pointer
over an edge (the line connecting two nodes), it shows you the outcome variable
or match variable that connects it to a node on the graph.

On the left-hand side, there are cards for each node that include details about
associated rules, detection windows, severity and priority status, and more.

Directly above the graph is a button labeled **Graph Options** . When you click
**Graph Options** , two options appear: **Non-Alerting Detections** and **Risk
Score**. Both are toggled on by default and can be toggled on or off based on
your preference.

To move the nodes, drag the nodes around the graph. When you release the
node, it is pinned where you left it until you click **Reset layout**.

### Add and remove nodes

If you click a node, a table appears at the bottom of the screen. You can do the
following actions on each node:

**Alert**

- See related entities, alerts, and events
- See outcomes and matches from the alert
- Remove any subgraph
- Add or remove related entities and alerts from the graph by checking boxes in the **On Graph** column

**Entity**

- See all related alerts
- Remove any subgraph
- Add or remove related alerts from the graph by checking or unchecking boxes in the **On Graph** column

**Group**

- See all the entities or alerts that make up that group
- Ungroup individual nodes by clicking **On Graph** on the table at the bottom of the page.

To add or remove the risk score from the nodes, select or clear the **Risk
Score** checkbox in **Graph Options**.

### Expand the alert graph

To see more related nodes, click the **+** icon at the bottom of the alert. The
entities and alerts related to the icon you selected pop up. Each new alert has
a card on the side with more details.

### Reset the graph

If you want to clear the graph, you can adjust the time range in the right hand
window. The maximum range is 90 days. Resetting the time range also resets the
graph to its original state. Updating the time range clears the graph of any
additional nodes and resets the graph to its original state.

To move the nodes back to the default position, click **Reset layout**.

## View context about the alert

The **Alert Context** subtab contains a list of values that provide additional context about the alert.

The alert context has a **Type** column that tells you which part of the rule
generated the alert that you selected, outcome or match. The next column is
called **Variable** . These variable names are based on the names of the match
and outcome variables defined in the rule. Finally, the far right column is
**UDM Field** . Variables that have a UDM field listed are also linked in the
**Values** column.

In addition to the UDM fields listed in the [Before you begin](https://docs.cloud.google.com/chronicle/docs/investigation/investigate-alert.md.txt#prerequisitesAlertGraph)
section, the following UDM fields are also linked to the **SIEM Search** page:

- `file.full_path`
- `process.command_line`
- `process.file.full_path`
- `process.parent_process.product_specific_process_id`
- `process.pid`
- `process.product_specific_process_id`
- `resource.product_object_id`

The specific UDM nouns that are associated with these fields are
`principal`, `target`, `src`, `observer`, `intermediary`, and `about`
. If
you click a value, a [UDM
search](https://docs.cloud.google.com/chronicle/docs/investigation/udm-search) is triggered, passing the
value along with the time range of the past day.

In the example YARA-L rule featured in the [Before you begin](https://docs.cloud.google.com/chronicle/docs/investigation/investigate-alert.md.txt#prerequisitesAlertGraph) section, the following UDM fields will be linked to the **SIEM Search** page:

- `principal.ip`
- `principal.user.userid`
- `principal.user.user_display_name`
- `target.resource.name`

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)