# Construct composite detection rules

Supported in:

This document provides a technical guide on how to build a composite rule within the Google Security Operations platform, a process that involves connecting multiple YARA-L 2.0 rules to identify complex attack patterns. Composite detections are structured as multi-event rules, maintaining the same fundamental syntax as standard single-event rules. For
more information, see [Composite detections overview](https://docs.cloud.google.com/chronicle/docs/detection/composite-detections).

## Understand the rule structure

Composite detection rules are always multi-event rules and follow the same
structure and syntax as a single-event rule.

A composite rule has the following essential components:

- `events` section: Defines your inputs; the specific detections or events that
  the rule analyzes.

- `match` section: Specifies how the inputs should be connected over a defined
  time window.

- `condition` section: Contains the final logic that determines whether the
  joined events meet the criteria to trigger an alert.

## Define the inputs in the `events` section

The first step in building a composite detection rule is to define the rule's inputs in the `events` section. Inputs for composite rules come from [collections](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/Collection), which store the detections generated by other queries.
Google SecOps provides the following two methods to access data
from collections.

### Reference detection content with variables or meta labels

To access data from a detection without referencing the original UDM events,
you can use `outcome` variables, `match` variables, or `meta` labels. We recommend this
approach because it provides greater flexibility and better compatibility across
different rule types.

For example, multiple rules can store a string (such as a URL, filename, or
registry key) in a common `outcome` variable if you're looking for that string
across different contexts. To access this string from a composite rule, start
with `detection` and locate the relevant information using elements from the
[Collection resource](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/Collection).

**Example:** Suppose a detection rule produces the following information:

- Outcome variable: `dest_domain = "cymbal.com"`

- UDM field: `target.hostname = "cymbal.com"`

In the composite rule, you can access this data using the following paths:

- `detection.detection.variables["dest_domain"].string_val` to access the `dest_domain` outcome variable.

- `detection.collection_elements.references.event.target.hostname` to access the `target.hostname` UDM field.

- `detection.time_window.start_time.seconds` to access the detection's start timestamp.

The Collection API and the `SecurityResult` API provide access to both:

- Detection metadata and outcome values (`detection.detection`)
- Underlying UDM events from referenced rules (`collection_elements`)

### Reference detection content with rule ID or name

You can reference a rule by either its name or ID. We recommend this approach
when your detection logic depends on specific rules and you want to reduce the data analyzed to only those rule results. Referencing relevant rules
by name or ID improves performance and prevents timeouts by reducing the data
analyzed. For example, you can directly query fields like `target.url` or
`principal.ip` from a known previous detection.

- **Reference a rule by rule ID (recommended):** Use the
  `detection.detection.rule_id` field to reference a rule by ID. You can find the
  rule ID in the rule's URL in Google SecOps. User-generated rules
  have IDs in the format `ru_UUID`, while curated detections have IDs in the
  format `ur_UUID`. For example:

  `detection.detection.rule_id = "ru_e0d3f371-6832-4d20-b0ad-1f4e234acb2b"`
- **Reference a rule by a rule name:** use the `detection.detection.rule_name`
  field to reference a rule by name. You can specify the exact rule name or use a
  regular expression to match it. For example:

  - `detection.detection.rule_name = "My Rule Name"`
  - `detection.detection.rule_name = "/PartOfName/"`

> [!NOTE]
> **Note:** We recommend referencing rule IDs because IDs are unique and don't change. Rule names can be modified, which can potentially break your composite detection.

## Join inputs in `match` section

To connect related detections, events, or entities in a composite rule, define
the `match` section using variables defined in the `events` section. These
variables can include rule labels, outcome variables, match variables, detection
fields, or collection elements.

For information about the syntax, see
[Match section syntax](https://docs.cloud.google.com/chronicle/docs/yara-l/match-syntax).

### Composite rules: time intervals and hop windows

Composite rules match detections and events against a time interval rather than
a single point in time. They match a composite hop window if the input
detection time window overlaps with that hop window (for example, the activity
was active during that block of time).

A single detection can trigger multiple alerts if the detection spans the
boundary between adjacent hop windows (due to pipeline delays, these historical
matches appear later). Specifically, a composite rule hop window triggers a
match if the input detection time window (`WindowStart` to `WindowEnd`) overlaps
with the hop window.

For example:

1. A composite rule has 60-minute hop windows: Hop 1 (18:58 - 19:58) and Hop 2 (19:58 - 20:58).
2. An upstream producer detection has a window of 19:57:54 - 20:56:54 (59-minute duration).
3. Since the producer window started at 19:57:54 (6 seconds before Hop 1 ended) and ended at 20:56:54 (during Hop 2), it overlaps with both hop windows.
4. This triggers two composite detections (one for Hop 1 and one for Hop 2), helping to prevent false negatives. If the producer rule didn't match on overlap, the partially overlapping detection wouldn't be considered for either Hop 1 or Hop 2 and the correlation between the detection and other events would be missed.

> [!NOTE]
> **Note:** If you want to prevent this type of boundary duplication, configure a suppression window (for example, `12h` or `24h`) in the composite rule to enforce rate-limiting (for example, one alert per campaign per day).

For more information and examples on how to specify hop windows, see
[Hop windows](https://docs.cloud.google.com/chronicle/docs/yara-l/windowing-logic#hop-windows).

## Define `condition` section

Define the `condition` section to evaluate the results of the `match` section.
If the condition is `true`, an alert is generated. For information about the
syntax, see [Condition section syntax](https://docs.cloud.google.com/chronicle/docs/yara-l/condition-syntax).

## Apply advanced techniques to composite rules

This section explains how to apply advanced techniques while building composite
rules.

### Combine events and detections

Composite rules can combine multiple data sources, including UDM events,
entity graph data, and detection fields. The following guidelines apply:

- **Use distinct variables per source** : Assign unique event variables to each
  data source (for example, `$e` for events, `$d` for detections), where the data
  source includes events, entities, and detections.

- **Join sources on shared context**: Connect data sources using common values,
  such as user IDs, IP addresses, or domain names in your rule's conditions.

- **Define a match window** : Always include a `match` clause with a time
  window no longer than 48 hours.

#### Example: combining events and detections

```
rule CheckCuratedDetection_with_EDR_and_EG {
  meta:
    author = "noone@cymbal.com"
  events:
    $d.detection.detection.rule_name = /SCC: Custom Modules: Configurable Bad Domain/
    $d.detection.collection_elements.references.event.network.dns.questions.name = $domain
    $d.detection.collection_elements.references.event.principal.asset.hostname = $hostname

    $e.metadata.log_type = "LIMACHARLIE_EDR"
    $e.metadata.product_event_type = "NETWORK_CONNECTIONS"
    $domain = re.capture($e.principal.process.command_line, "\\s([a-zA-Z0-9.-]+\\.[a-zA-Z0-9.-]+)$")
    $hostname = re.capture($e.principal.hostname, "([^.]*)")

    $prevalence.graph.metadata.entity_type = "DOMAIN_NAME"
    $prevalence.graph.metadata.source_type = "DERIVED_CONTEXT"
    $prevalence.graph.entity.hostname = $domain
    $prevalence.graph.entity.domain.prevalence.day_count = 10
    $prevalence.graph.entity.domain.prevalence.rolling_max <= 5
    $prevalence.graph.entity.domain.prevalence.rolling_max > 0

  match:
    $hostname over 1h

  outcome:
    $risk_score = 80
    $CL_target = array($domain)

  condition:
    $e and $d and $prevalence
}
```

### Create sequential composite detections

Sequential composite detections identify patterns of related events where the
sequence of detections is important, such as a brute-force login attempt
detection, followed by a successful login. These patterns can combine multiple
base detections, raw UDM events, or both.

To create a sequential composite detection, you must enforce that order within
your rule. To enforce the expected sequence, use one of the following methods:

- **Sliding windows:** Define the sequence of detections using sliding windows
  in your `match` conditions.

- **Timestamp comparisons:** Compare the timestamps of detections within your
  rule logic to verify that they happen in the selected order.

#### Example: sequential composite detections

```
events:
    $d1.detection.detection.rule_name = "fileEvent_rule"
    $userid = $d1.detection.detection.variables["user"].string_val
    $hostname = $d1.detection.detection.variables["hostname"].string_val

    $d2.detection.detection.rule_name = "processExecution_rule"
    $userid = $d2.detection.detection.variables["user"].string_val
    $hostname = $d2.detection.detection.variables["hostname"].string_val

    $d3.detection.detection.rule_name = "networkEvent_rule"
    $userid = $d3.detection.detection.variables["user"].string_val
    $hostname = $d3.detection.detection.variables["hostname"].string_val

$d3.detection.collection_elements.references.event.metadata.event_timestamp.seconds > $d2.detection.collection_elements.references.event.metadata.event_timestamp.seconds

  match:
    $userid over 24h after $d1
```

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