# Configure alert suppression

Supported in:

This document describes the mechanisms available in Google Security Operations to
suppress noisy alerts and prioritize critical threats. Alert suppression
automatically filters duplicative and low-value alerts based on predefined
criteria. This suppression gives your SOC team the ability to focus on
high-priority security incidents.

You can use alert suppression to manage volume generated by various triggers,
such as duplicate alerts from
the same underlying activity, false positives resulting from misconfigured
systems, broad rule logic that triggers on known, benign activity, or planned
maintenance windows.

Google SecOps provides the following methods to manage alert
volume:

- **Throttling**: Suppresses repetitive detections of the same activity for a
  defined time window (for example, 1 hour) after the initial alert triggers.

- **Exclusions**: An exclusion prevents specific detections by filtering matches
  before they trigger an alert. Events that meet the rule logic, but don't meet
  the exclusion criteria trigger detections normally.

- **SOAR playbooks**: Provides time-bound alert suppression based on specific
  entity lookups, such as IP addresses or hostnames.

- **SOAR alert grouping**: Automatically clusters similar alerts into a single
  case based on your criteria to streamline investigations.

## Suppress alerts through throttling

Throttling suppresses detections for a specified duration after an initial rule
match. When you use the `suppression_window` and `suppression_key` options in
the rule logic, the system generates a detection only for the first unique
combination of the suppression key. Google SecOps suppresses all
subsequent matches for that same combination until the defined window expires.

> [!NOTE]
> **Note:** For multi-event and windowed single event (WSE) rules, you don't need to specify a suppression_key. The match variables defined in the rule are used for suppression criteria.

This method effectively reduces duplicate detections caused by the same
underlying activity.

### Use cases

- **PowerShell execution**: Suppress repetitive alerts for the same user and
  host for one hour after the initial event.

- **Network scanning**: Suppress repetitive alerts from a malicious port scanner
  for six hours after the first detection.

### Monitor for noisy rules

To identify noisy rules, do the following:

1. [Sign in to Google SecOps](https://docs.cloud.google.com/chronicle/docs/log-in-to-ui).

2. Click **Menu** , select **Detection** \> **Rules and Detections**.

3. On the **Rules Editor** tab, select the rule, and click **Test**.

4. Adjust the time range selector to analyze the last seven days of data. If a
   rule generates over 100 detections daily, it's likely too broad.

5. Click
   **Menu** and click **View rule detections**. The
   detection details page appears.

6. In the **Procedural Filtering** panel, identify
   contributing UDM fields.

7. Modify the `match` section or `$suppression_key` to reduce the volume of
   detections.

#### Example: Identify unique logins by location

To identify unique logins by location while preventing alert
fatigue, you can suppress detections from the same state. Look for the UDM field
`event.principal.location.state` to see the detection count per state.

If a specific state shows an excessively high count, add that field to your
`suppression` or `match` key. This ensures the system fires only a single
detection for each unique login location.

### Configure detections throttling

Throttling suppresses detections for a specified duration after an initial
alert triggers. To limit duplicate detections, add a `suppression_window` to
the rule's `options` section of your rule. The following guidelines apply:

- **Single event rules** : Define the `$suppression_key` variable in the `outcome`
  section to act as the deduplication key.

- **Multi-event rules** : Use the variables in the `match` section as the
  deduplication key.

- **Window duration** : Make sure the `suppression_window` is greater than or
  equal to the `match` window size. If you set it to the same duration, the rule
  behaves as if no suppression is applied.

- **Limit**: There's no maximum limit for the suppression window duration.

- **Compatibility**: Throttling applies to single and multi-event rules, and
  both custom and curated rules.

#### Example: Monitor Windows file share activity

The following rule monitors windows file share activity. It creates one
detection for every unique user and hostname within a 60-minute (`1hr`) window,
then suppresses repetitive matches for the same combination for 24 hours (`24h`).


    rule rule_noisy_winshares {

      meta:
       author = "Google Cloud Security"

      events:
        $e.metadata.event_type = "NETWORK_CONNECTION"
        $e.target.resource.name = /(C|ADMIN|IPC)\$/ nocase
        $user = $e.principal.user.userid
        $hostname = $e.target.hostname

      match:
        $hostname, $user over 1h

      outcome:
        $sharename = array_distinct($e.target.resource.name)

      condition:
        $e

      options:
        suppression_window = 24h
    }

This configuration lets analysts investigate the initial activity without
processing duplicate alerts for the same user and host during the suppression
window.

## Suppress alerts using rule exclusions

An exclusion prevents specific detections by filtering matches before they
trigger an alert. If a match satisfies the exclusion logic, the system
suppresses the detection. Events that meet the rule logic, but don't meet the
exclusion criteria, continue to trigger detections normally. Once applied,
exclusions remain active until you manually disable them.

> [!NOTE]
> **Note:** Exclusions are only available for curated rules. For custom rules, add suppression logic directly to the rule text, or use [data tables](https://docs.cloud.google.com/chronicle/docs/investigation/data-tables#filter-udm) to maintain reusable exclusion lists across multiple rules.

> [!CAUTION]
> **Caution:** Don't apply a rule exclusion directly to a composite rule. You must apply the exclusion to the foundational underlying rules that feed into the composite rule. This is because rule exclusions are evaluated against UDM fields (like `principal.user.userid`), but composite rules trigger based on other detections rather than UDM fields. If you apply a rule exclusion directly to a composite rule, the exclusion will fail to match, and the event won't get excluded.
>
> To find the foundational rule:
>
> 1. Navigate to **Content Hub** in the Google SecOps console.
> 2. Click the **Curated Detections** tab (or search for the specific rule pack).
> 3. Locate the composite rule and click **View \& Manage**.
> 4. Select **Rule Definition** to view the underlying YARA-L source code.
> 5. Review the `events:` section of the YARA-L logic to identify the foundational rule names.

You can view, manage, and audit the
complete list of exclusions and the associated metadata on the **Exclusions**
tab on the **Rules and Detections** page. You can also use the
**Test Exclusion** feature to assess how specific filters impact your
detection volume before applying them.

To create exclusions using the API, see [Manage rule exclusion using the API](https://docs.cloud.google.com/chronicle/docs/investigation/rule-exclusion-api).

### Use cases

- Suppress legitimate PowerShell execution by authorized IT tools.

- Exclude internal vulnerability scanners performing high-volume port scans.

### Create rule exclusions

To create exclusions for a noisy rule, follow these steps:

1. [Sign in to Google SecOps](https://docs.cloud.google.com/chronicle/docs/log-in-to-ui).

2. Go to **Menu** \> **Detection** \>
   **Rules and Detections**.

3. On the **Rules Dashboard** tab, look for rules with high detection counts.

4. Click the **Rule Name** to open the **Detections** page.

5. Click **Rule Options** \> **Exclude**.

6. Specify these details to add the exclusion filter:

   - Exclusion name

   - Rules or rules sets that it applies to

   - The exclusion criteria to suppress detections when the specified conditions
     are met. To add multiple conditions, follow these guidelines:

     1. To create a logical OR relationship, enter multiple values in a single
        row using the **Enter** key.

        For example, `principal.ip IS 192.158.1.38 OR principal.ip IS 192.186.0.2`
     2. Click **+ Conditional Statement** to add a new statement that has a
        logical `AND` relationship with the previous statement.

        For example, `(principal.ip IS 192.158.1.38 OR principal.ip IS 192.186.0.2) AND (principal.user.userid CONTAINS sensitive)`
7. Optional: Click **Test Exclusion** to view how the filter measures the
   reduced detections over the last 30 days. Adjust your criteria based on the
   results.

8. Click **Create** to activate the exclusion.

### Manage rule exclusions

To manage the exclusions, follow these steps:

1. [Sign in to Google SecOps](https://docs.cloud.google.com/chronicle/docs/log-in-to-ui).

2. Go to **Menu** \> **Detection** \>
   **Rules and Detections**.

3. Go to the **Exclusions** tab to see the list of exclusions. You can do the
   following:

   - To enable or disable an exclusion, flip the **Enabled** toggle.

   - To filter the exclusions, click
     **Filter**.

   - To edit an exclusion, click
     **Menu** \> **Edit**.

   - To archive an exclusion, click
     **Menu** \> **Archive**.

   - To restore an exclusion, click
     **Menu** \> **Unarchive**.

To create and manage rule exclusions using API, see
[Manage rule exclusion through API](https://docs.cloud.google.com/chronicle/docs/investigation/rule-exclusion-api).

### Limitations

When you configure exclusions, note the following limitations:

- **Composite rules** : Don't apply a rule exclusion directly to a composite rule. You must apply the exclusion to the foundational underlying rules that feed into the composite rule. This is because rule exclusions are evaluated against UDM fields (like `principal.user.userid`), but composite rules trigger based on other detections rather than UDM fields. If you apply a rule exclusion directly to a composite rule, the exclusion will fail to match, and the event won't get excluded.

  To find the foundational rule:
  1. Navigate to **Content Hub** in the Google SecOps console.
  2. Click the **Curated Detections** tab (or search for the specific rule pack).
  3. Locate the composite rule and click **View \& Manage**.
  4. Select **Rule Definition** to view the underlying YARA-L source code.
  5. Review the `events:` section of the YARA-L logic to identify the foundational rule names.
- **Query syntax and field depth** : API exclusion queries must use flat Conjunctive Normal Form (CNF) boolean syntax and UDM field paths with up to 6 dot-separated segments. For more information, see [Query syntax and field rules](https://docs.cloud.google.com/chronicle/docs/investigation/rule-exclusion-api#query-syntax-and-field-rules).

Additionally, note these functional differences between the console and the API:

- **Rule scope** : Rule exclusions apply only to curated rules and curated rule
  sets in both the console and the API. Custom rules aren't supported. To
  suppress alerts from custom rules, add exclusion logic to the YARA-L rule
  text, or use [data tables](https://docs.cloud.google.com/chronicle/docs/investigation/data-tables) to
  maintain exclusion lists across multiple rules. For more information, see
  [Filter UDM event and entity data using a data table](https://docs.cloud.google.com/chronicle/docs/investigation/data-tables#filter-udm)
  and
  [Left anti-join examples in rules](https://docs.cloud.google.com/chronicle/docs/investigation/outer-joins#rule-anti-join-examples).

- **Outcome variables**: To create exclusions that use logic based on outcome
  variables, you must use the API.

## Suppress alerts through SOAR playbooks

[SOAR playbooks](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-alerts/whats-on-the-alert-playbook-tab)
help identify and suppress duplicate alerts based
on specific lookup criteria. The playbook suppresses alerts until a predefined
expiration time, after which it automatically removes the alerts from the table.
Analysts use this method to suppress alerts for specific entities, such as
IP addresses or hostnames, for a set duration.

Unlike other methods, this mechanism tracks historical data and provides an
explicit audit trail of suppression actions within the case details.

### Use case

Suppress subsequent alerts for incoming connection requests from a suspicious
IP address after the initial alert, while maintaining a suppression audit trail.

## Group alerts in SOAR

Alert grouping automatically clusters similar alerts generated within a 24-hour
window based on your defined criteria. The system consolidates grouped alerts
into a single case for investigation.

For more information, see
[Alert grouping mechanism](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-alerts/alert-grouping-mechanism-admin).

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