Derived Detections (Beta)

Create one or more Derived Detections from a single Base Detection in Panther

Overview

Detection derivation is in open beta starting with Panther version 1.93, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

You can create one or more Derived Detections from a single Base Detection in Panther. Derived Detections inherit the Base Detection's core logic, which is immutable, as well as its metadata and alert field values, which can be overwritten.

Detection derivation is available for rules created as Simple Detections or Python Detections.

Use cases for Derived Detections

Derivation can be particularly useful when:

• You maintain multiple copies of the same rule, each with different metadata

• In the CLI workflow, you use and customize Panther-managed rules, and want to avoid having to resolve merge conflicts when Panther releases updates

  • See a full example on Using Derived Detections to Avoid Merge Conflicts

• You'd like the ability to, while responding to an incident, deploy multiple variations of one detection to gather telemetry that can inform your next decision

• One member of your team (e.g., a Head of Threat Research) would like to create a set of Base Detections that others (e.g., SOC Analysts) can modify

Base Detections and Derived Detections

A Base Detection is any custom or Panther-managed rule from which a Derived Detection has been created.

A Derived Detection is created from a Base Detection and:

• Inherits the Base Detection's metadata/alert field values, but can overwrite certain fields

  • See Limitations of detection derivation for a full list of fields that can be overwritten today.

  • An override made in a Derived Detection completely replaces the field's value it inherited from the Base Detection. For example, if both a Base Detection and Derived Detection define an Inline Filter (in the InlineFilters key in the CLI workflow or Filter to only include events field in the Console), only the Derived Detection's Inline Filter will be applied.

  • Overrides can only be made in one direction, i.e., overrides made on a Derived Detection do not affect Base Detection values. For example, if a Base Detection has Enabled: False and its Derived Detection has Enabled: True, only the Derived Detection will be enabled.

• Inherits the core detection logic of the Base Detection

  • The core detection logic is defined in the Base Detection's rule() function (for Python detections) or Detection field (for Simple Detections).

  • A Derived Detection cannot specify its own detection logic—if in the CLI workflow a Derived Detection includes a Detection key, for example, its contents will be ignored.

What happens when a Base Detection is updated

When the core logic of a Base Detection is updated, the change is propagated to all associated Derived Detections.

When the metadata of a Base Detection is updated, if an associated Derived Detection has already overwritten the value(s) of the updated field(s), there is no change. If an associated Derived Detection has not overwritten the value(s) of the updated field(s), the metadata update is propagated to the Derived Detection.

Disable Base Detections to avoid duplicate alerts

In most cases, Base and Derived Detections are run over the same set of incoming logs (although it is possible to use Inline Filters to target different events). In this scenario, because the detections share core logic, if they are both enabled, they will generate duplicate alerts.

To avoid this, disable the Base Detection. When a disabled Base Detection is updated, its changes will still propagate to its Derived Detections as described above.

Automatically disabling Base Detections in the CLI workflow

In the CLI workflow, there are two ways that you can automatically disable Base Detections:

• Option 1 (Recommended): Add the following setting to your .panther_settings.yml file:

  auto_disable_base: true
  # ... other settings ...

• Option 2: Use --auto-disable-base with the Panther Analysis Tool upload command.

  • When following this option, note that --auto-disable-base must be used with every subsequent upload invocation. If it is omitted, Base Detections will be re-enabled.

If one or more of your Base Detections has already been uploaded to your Panther instance in an enabled state and you then use one of the above methods to automatically disable Base Detections, ensure you are not including --filter enabled: true on your PAT upload command. If you do, Base Detections will be disabled before upload (when the enabled: true filter is applied), meaning the newly disabled Base Detections won't be re-uploaded to your Panther instance (leaving them as-is, or enabled).

Limitations of detection derivation

• Derivation is not available for Scheduled Rules or Policies.

• Only one level of derivation is possible, i.e. a Derived Detection cannot be derived from.

• In the Console workflow, tests are inherited when the Derived Detection is created, but not thereafter when the Base Detection's tests are updated.

• If, in a Python Base Detection, the value of a metadata field is set using a Python function, that value will take precedence over an equivalent static override value supplied in a Derived Detection. For example, if a Python severity() function is present in the Base Detection, its value will take precedence over the Derived Detection's override value supplied in the Severity YAML key (in the CLI workflow) or the Severity field (in the Console).

  • See a full list of the Python functions that set metadata values (called "Alert functions"), as well as which fields in YAML/the Console they override, in the Alert functions in Python detections table.

  • It is possible to overwrite values set by certain Python alert functions by using dynamic alert keys in your Derived Detection. For example, you can override the value of your Python Base Detection's severity() function in your Derived Detection by using the DynamicSeverities field.

    • DynamicSeverities overrides severity()

    • AlertTitle overrides title()

    • AlertContext overrides alert_context()

    • GroupBy overrides dedup()

• If you are creating a Derived Detection in the Console workflow and the Base Detection is a Python detection, you cannot set any alert fields dynamically—they may only be set statically.

  • It is possible to dynamically set alert fields in the Console workflow if the Base Detection is a Simple detection.

  • It is possible to dynamically set alert fields in the CLI workflow (using AlertTitle, DynamicSeverities, AlertContext, and GroupBy) regardless of whether the Base Detection is a Python or YAML detection.

• Currently, only the below fields can be overwritten. These are YAML field names, applicable to the CLI workflow—for those with equivalent fields in the Console, those Console fields may also be overwritten.

  • Enabled

  • Severity

  • Description

  • CreateAlert

  • DedupPeriodMinutes

  • InlineFilters

  • DisplayName

  • OnlyUseBaseRiskScore

  • OutputIds

  • Reference

  • Runbook

  • SummaryAttributes

  • Threshold

  • Tags

  • Reports

  • DynamicSeverities

  • AlertTitle

  • AlertContext

  • GroupBy

  • Tests

How to create a Derived Detection

Panther Console

Creating a Derived Detection in the Panther Console

1. In the left-hand navigation bar of the Panther Console, click Detections.

2. Locate the detection you would like to become the Base Detection for a new Derived Detection, and click its name.

3. In the upper-right corner, click ....

4. Click Derive:

5. On the Basic Info page, optionally edit the Name and ID fields for the Derived Detection.

   • Ensure the name is distinguishable from the Base Detection's name.

6. Click Continue.

7. Scroll down to the Filter and Set Alert Fields sections, and set desired overrides to Inline Filters and alert fields:

8. In the upper-right corner, click Deploy.

   • The detection will have a DERIVED label:

CLI workflow

How to view all Derived Detections

To view all Derived Detections in your Panther instance:

1. In the left-hand navigation bar of your Panther Console, click Detections.

2. Click Filters icon.

3. In the Detection Types dropdown field, select Derived Rule.

4. Click Apply Filters.