Derived Detections (Beta)

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


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 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
  • 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

Derived Detections can specify override values for certain metadata fields while always inheriting the core logic of the Base Detection. 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.
A Base Detection can be a rule your team has created, or a Panther-managed rule.

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.

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).
  • 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
    • DedupPeriodMinutes
    • InlineFilters
    • DisplayName
    • OnlyUseBaseRiskScore
    • OutputIds
    • Reference
    • Runbook
    • SummaryAttributes
    • Threshold
    • Tags
    • Reports
    • DynamicSeverities
    • AlertTitle
    • AlertContext
    • GroupBy
    • Tests

How to create a Derived Detection

Panther Console
CLI workflow

Creating a Derived Detection in the Panther Console

  1. 1.
    In the left-hand navigation bar of the Panther Console, click Build > Detections.
  2. 2.
    Locate the detection you would like to become the Base Detection for a new Derived Detection, and click its name.
  3. 3.
    In the upper-right corner, click ....
  4. 4.
    Click Derive:
    In the Panther Console, the three dots menu on a detection's page is open, and the Derive option is circled.
  5. 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. 6.
    Click Continue.
  7. 7.
    Scroll down to the Filter and Set Alert Fields sections, and set desired overrides to Inline Filters and alert fields:
    The edit detection page in the Panther Console is shown. A Filter section is visible, along with a Set Alert Fields section. Within the latter are sub-sections for Required Fields and Optional Fields.
  8. 8.
    In the upper-right corner, click Deploy.
    • The detection will have a DERIVED label:
      The word "DERIVED" is shown in teal.

Creating a Derived Detection in the CLI workflow

  1. 1.
    In the directory where you use the Panther Analysis Tool (PAT), create a new YAML file for your Derived Detection.
  2. 2.
    In this YAML file, add the following fields, which are required for Derived Detections:
    • BaseDetection: Provide the rule ID of any rule currently present in your Panther instance or in the local directory you will upload using PAT.
      • The BaseDetection key is the link between this Derived Detection and its Base Detection, and is what indicates that inheritance should be applied.
    • RuleID: Provide a value that is different than the ID supplied earlier for the BaseDetection key.
    • AnalysisType: Indicate whether this is a rule, scheduled_rule, or policy.
      • Currently, only rules are supported for inheritance.
  3. 3.
    Add the metadata fields you would like to override, and their new values.
  4. 4.
    Upload your detection using the panther_analysis_tool upload command.

CLI workflow example

Below is an example of a Python Base Detection (a standard detection in the panther-analysis repository), and below it, its Derived Detection.
# Base Detection
AnalysisType: rule
Description: An Auth0 User enabled MFA Policy for your organization's tenant.
DisplayName: "Auth0 MFA Policy Enabled"
Enabled: true
Runbook: Assess if this was done by the user for a valid business reason and was expected. This alert indicates a setting change that aligns with best security practices, follow-up may be unnecessary.
Severity: Medium
DedupPeriodMinutes: 60
- Auth0.Events
RuleID: "Auth0.MFA.Policy.Enabled"
Threshold: 1
- ExpectedResult: true
client_id: 1HXWWGKk1Zj3JF8GvMrnCSirccDs4qvr
client_name: ""
date: "2023-05-16 17:26:16.782000000"
description: Set the Multi-factor Authentication policies
jti: 0107c849078d8d889af711840197ba7c
- create:actions
- create:actions_log_sessions
# shortened for brevity
strategy: jwt
name: User Name
user_id: google-oauth2|105261262156475850461
- all-applications
method: put
path: /api/v2/guardian/policies
query: {}
userAgent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/ Safari/537.36
- all-applications
statusCode: 200
log_id: "90020230515215719063964000000000000001223372037488829643"
type: sapi
user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/ Safari/537.36
user_id: google-oauth2|105261262156475850461
log_id: "90020230515215719063964000000000000001223372037488829643"
- google-oauth2|105261262156475850461
p_event_time: "2023-05-16 17:26:16.782"
p_log_type: Auth0.Events
p_parse_time: "2023-05-16 17:28:28.572"
p_row_id: 2660c447622fa4c3dbb08f9918979102
p_schema_version: 0
p_source_id: b9031579-b2c5-45c2-b15c-632b995a4e36
p_source_label: Org Auth0 Tenant Label
Name: MFA Policy Enabled First
# Derived Detection
# Required fields
AnalysisType: rule
RuleID: "Auth0.MFA.Policy.Enabled.Custom.Severity"
BaseDetection: "Auth0.MFA.Policy.Enabled"
# Fields being overwritten (i.e., overriding the default values inherited from the Base Detection)
DisplayName: "Auth0 MFA Policy Enabled - Severity Critical"
Enabled: true
Severity: Critical
Description: An Auth0 User enabled MFA Policy for your organization's tenant - severity overridden to critical.

How to view all Derived Detections

To view all Derived Detections in your Panther instance:
  1. 1.
    In the left-hand navigation bar of your Panther Console, click Build > Detections.
  2. 2.
    Click Filters.
    On the Detections list page, an arrow is drawn from the Filters button to a dropdown field called Detection Types. A value called Derived Rule has been selected.
  3. 3.
    In the Detection Types dropdown field, select Derived Rule.
  4. 4.
    Click Apply Filters.