crowdstrike.falcon.correlation_rule_info module – Get information about 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_info.

New in crowdstrike.falcon 4.12.0

Synopsis

• Returns detailed information for one or more NG-SIEM correlation rules.

• Some of the details returned include rule name, description, severity, status, tactic, technique, search criteria, and creation and modification timestamps.

• Can retrieve specific rules by ID or search for rules using FQL filters.

• Optionally includes the latest published version info for each rule.

Requirements

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

• Correlation Rules [READ] API scope

• CrowdStrike FalconPy >= 1.5.0

• 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"
ext_headers dictionary	Extended headers that are prepended to the default headers dictionary.
filter string	FQL (Falcon Query Language) filter expression to limit results. Supported fields: customer_id, user_id, user_uuid, status, name, created_on, last_updated_on. Examples: name:'*brute*', status:'enabled', created_on:>='2024-01-01'. Cannot be used together with rule_ids.
include_latest_version boolean	Whether to include the latest published version information for each rule. When enabled, adds a latest_version field to each rule with the latest published version details. This requires an additional API call per batch of rules. Choices: false ← (default) true
limit integer	Maximum number of correlation rules to return. Must be between 1 and 500. Default: 100
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.
offset integer	Starting index for pagination. Use with limit to paginate through large result sets. Default: 0
rule_ids list / elements=string	A list of correlation rule IDs to get information about. If not provided, rules will be returned based on filter and pagination settings. Cannot be used together with filter.
sort string	Property to sort results by. Prefix with - for descending order. Examples: name, -created_on, last_updated_on.
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.

Examples

- name: Get all correlation rules
  crowdstrike.falcon.correlation_rule_info:

- name: Get specific correlation rules by ID
  crowdstrike.falcon.correlation_rule_info:
    rule_ids:
      - "12345678901234567890abcdef123456"
      - "abcdef123456789012345678901234"

- name: Search rules by name pattern
  crowdstrike.falcon.correlation_rule_info:
    filter: "name:'*brute*'"
    limit: 50

- name: Filter rules by status
  crowdstrike.falcon.correlation_rule_info:
    filter: "status:'enabled'"
    sort: "-last_updated_on"

- name: Get rules with latest version info
  crowdstrike.falcon.correlation_rule_info:
    filter: "status:'enabled'"
    include_latest_version: true

- name: Paginate through all correlation rules
  crowdstrike.falcon.correlation_rule_info:
    limit: 100
    offset: "{{ page * 100 }}"
  loop: "{{ range(0, total_rules // 100 + 1) | list }}"
  loop_control:
    loop_var: page

Return Values

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

Key	Description
correlation_rules list / elements=dictionary	A list of correlation rules that match the search criteria. Returned: success
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 that owns the rule. Returned: success Sample: "abc123def456789"
description string	The description of the correlation rule. Returned: success Sample: "Detects repeated failed login attempts"
id string	The unique identifier of the correlation rule. Returned: success Sample: "12345678901234567890abcdef123456"
last_updated_on string	The timestamp when the rule was last updated. Returned: success Sample: "2024-02-01T14:22:30.000000Z"
latest_version dictionary	Latest published version info for the rule (only when include_latest_version=true). Returned: when include_latest_version=true
name string	The name of the correlation rule. Returned: success Sample: "Brute Force Login Detection"
notifications list / elements=dictionary	The notification settings for the rule. Returned: success
operation dictionary	The operation configuration for the rule. Returned: success
search dictionary	The search criteria/query for the rule. Returned: success
severity integer	The severity level of the rule. Returned: success Sample: 3
status string	The current status of the rule (e.g., enabled, disabled). Returned: success Sample: "enabled"
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"
meta dictionary	Metadata about the query results. Returned: success
pagination dictionary	Pagination information. Returned: success
limit integer	The limit used for this query. Returned: success Sample: 100
offset integer	The starting index used for this query. Returned: success Sample: 0
total integer	Total number of correlation rules matching the query. Returned: success Sample: 42
query_time float	Time taken to execute the query in seconds. Returned: success Sample: 0.123

Authors

• Carlos Matos (@carlosmmatos)

Collection links

• Issue Tracker
• Repository (Sources)