crowdstrike.falcon.correlation_rule module – Manage NG-SIEM correlation rules

Note

This module is part of the crowdstrike.falcon collection (version 4.11.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install crowdstrike.falcon. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: crowdstrike.falcon.correlation_rule.

New in crowdstrike.falcon 4.12.0

Synopsis

  • Create, update, and delete NG-SIEM correlation rules in the CrowdStrike Falcon platform.

  • Supports idempotent operations that only make changes when necessary.

  • Can optionally publish a rule version after create or update.

  • The customer ID (CID) is automatically resolved from the authenticated API session.

Requirements

The below requirements are needed on the host that executes this module.

  • Correlation Rules [READ, WRITE] API scope

  • CrowdStrike FalconPy >= 1.5.0

  • Sensor Download [READ] API scope (for CID auto-detection)

  • crowdstrike-falconpy >= 1.3.0

  • python >= 3.6

Parameters

Parameter

Comments

auth

dictionary

The registered result of the crowdstrike.falcon.auth module, or a dictionary containing the access_token and cloud keys.

If provided, the client_id, client_secret, member_cid, and cloud options are ignored.

Useful when needing to make multiple API calls to avoid rate limiting issues.

access_token

string

The OAuth2 access token to use for authentication.

cloud

string

The CrowdStrike cloud region to use.

This can differ from the module’s cloud argument due to autodiscovery.

client_id

aliases: falcon_client_id

string

The CrowdStrike API client ID to use.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_ID environment variable can also be used.

client_secret

aliases: falcon_client_secret

string

The CrowdStrike API secret that corresponds to the client ID.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_SECRET environment variable can also be used.

cloud

string

The CrowdStrike cloud region to use.

All clouds are automatically discovered if not specified, except for the us-gov-1 cloud.

The FALCON_CLOUD environment variable can also be used.

Choices:

  • "us-1" ← (default)

  • "us-2"

  • "us-gov-1"

  • "eu-1"

comment

string

A comment associated with the rule change.

description

string

A description for the correlation rule.

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

member_cid

string

The CrowdStrike member CID for MSSP authentication.

See the Falcon documentation for more information about API clients.

The FALCON_MEMBER_CID environment variable can also be used.

name

string

The name of the correlation rule.

Required when creating a new rule and rule_id is not provided.

Used to look up an existing rule when rule_id is not specified.

notifications

list / elements=dictionary

List of notification configurations for the rule.

operation

dictionary

Scheduling configuration for the rule.

Required when creating a new rule.

schedule

dictionary

Schedule definition dict containing a definition key with a cron expression.

Example: {'definition': '*/5 * * * *'} for every 5 minutes.

start_on

string

ISO 8601 datetime string for when the rule becomes active.

stop_on

string

ISO 8601 datetime string for when the rule stops being active.

publish

boolean

Whether to publish the rule version after a create or update operation.

When true, the module will retrieve the latest rule version and publish it.

Choices:

  • false ← (default)

  • true

rule_id

string

The ID of an existing correlation rule.

Preferred for identifying existing rules during update or delete operations.

If provided with state=present, the module will update the existing rule.

If provided with state=absent, the module will delete the rule by ID.

dictionary

Search criteria for the correlation rule.

Required when creating a new rule.

filter

string

CQL filter string for the search query.

lookback

string

Lookback period for the search (e.g., 5m, 1h, 24h).

outcome

string

The outcome type when the rule triggers.

Valid values: detection, incident, case, event.

Note: The incident outcome is deprecated and will be retired on June 8, 2026. Rules using incident will be automatically switched to detection. Use detection instead.

trigger_mode

string

Trigger mode for the rule.

severity

integer

The severity level of the rule.

Valid values: 10 (informational), 30 (low), 50 (medium), 70 (high), 90 (critical).

Choices:

  • 10

  • 30

  • 50

  • 70

  • 90

state

string

The desired state of the correlation rule.

present ensures the rule exists with the specified configuration.

absent ensures the rule does not exist.

Choices:

  • "present" ← (default)

  • "absent"

status

string

The operational status of the rule.

active enables the rule.

inactive disables the rule without deleting it.

Choices:

  • "active"

  • "inactive"

tactic

string

The MITRE ATT&CK tactic associated with the rule.

technique

string

The MITRE ATT&CK technique associated with the rule.

trigger_on_create

boolean

Whether the rule triggers on creation.

Only applicable when creating a new rule.

Choices:

  • false ← (default)

  • true

user_agent

string

Custom User-Agent string to use for requests to the API.

The user agent string is prepended to the default user agent string (crowdstrike-ansible/<version>).

See RFC 7231 for more information.

The FALCON_USER_AGENT environment variable can also be used.

Notes

Note

  • Idempotency: This module is idempotent and will only make changes when the current state differs from the desired state.

  • Rule Lookup: When rule_id is not provided, the module searches by name. If multiple rules share the same name, the first match is used. Prefer rule_id for precise targeting.

  • Publishing: Setting publish=true will publish the latest rule version after any create or update. Publishing is skipped when no changes are made.

  • State Management: For state=absent, if the rule is not found, the module exits successfully without making any changes (idempotent).

Examples

- name: Create a correlation rule
  crowdstrike.falcon.correlation_rule:
    name: "Detect suspicious logins"
    description: "Alert on multiple failed logins followed by success"
    severity: 50
    status: active
    search:
      filter: "#event_simpleName=UserLogon"
      lookback: "10m"
      outcome: "detection"
    operation:
      schedule:
        definition: "*/5 * * * *"

- name: Create a rule with MITRE ATT&CK mapping
  crowdstrike.falcon.correlation_rule:
    name: "Brute Force Detection"
    description: "Detects brute force login attempts"
    severity: 70
    status: active
    tactic: "Credential Access"
    technique: "Brute Force"
    search:
      filter: "#event_simpleName=UserLogon"
      lookback: "10m"
      outcome: "detection"
    operation:
      schedule:
        definition: "*/5 * * * *"

- name: Update an existing rule by name
  crowdstrike.falcon.correlation_rule:
    name: "Detect suspicious logins"
    description: "Updated description for suspicious login detection"
    severity: 70

- name: Update a rule by ID
  crowdstrike.falcon.correlation_rule:
    rule_id: "a1b2c3d4e5f6789012345678901234ab"
    status: inactive
    comment: "Disabling temporarily for maintenance"

- name: Delete a rule by name
  crowdstrike.falcon.correlation_rule:
    name: "Detect suspicious logins"
    state: absent

- name: Delete a rule by ID
  crowdstrike.falcon.correlation_rule:
    rule_id: "a1b2c3d4e5f6789012345678901234ab"
    state: absent

- name: Create and publish a rule
  crowdstrike.falcon.correlation_rule:
    name: "Lateral Movement Detection"
    description: "Detects potential lateral movement activity"
    severity: 70
    status: active
    tactic: "Lateral Movement"
    search:
      filter: "#event_simpleName=NetworkConnectIP4"
      lookback: "15m"
      outcome: "detection"
    operation:
      schedule:
        definition: "*/10 * * * *"
    publish: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

correlation_rule

dictionary

Information about the correlation rule that was created or updated.

Returned: when state=present

created_on

string

The timestamp when the rule was created.

Returned: success

Sample: "2024-01-15T10:30:00.000000Z"

customer_id

string

The customer ID associated with the rule.

Returned: success

Sample: "0123456789abcdef0123456789abcdef"

description

string

The description of the correlation rule.

Returned: success

Sample: "Alert on multiple failed logins followed by success"

id

string

The unique identifier of the correlation rule.

Returned: success

Sample: "a1b2c3d4e5f6789012345678901234ab"

last_updated_on

string

The timestamp when the rule was last updated.

Returned: success

Sample: "2024-02-01T14:22:30.000000Z"

name

string

The name of the correlation rule.

Returned: success

Sample: "Detect suspicious logins"

notifications

list / elements=string

The list of notification configurations for the rule.

Returned: when configured

operation

dictionary

The scheduling configuration for the rule.

Returned: when configured

dictionary

The search criteria for the rule.

Returned: success

severity

integer

The severity level of the rule.

Returned: success

Sample: 50

status

string

The operational status of the rule.

Returned: success

Sample: "active"

tactic

string

The MITRE ATT&CK tactic associated with the rule.

Returned: success

Sample: "Credential Access"

technique

string

The MITRE ATT&CK technique associated with the rule.

Returned: success

Sample: "Brute Force"

Authors

  • Carlos Matos (@carlosmmatos)