crowdstrike.falcon.ngsiem_parser module – Manage NG-SIEM parsers

Note

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

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.ngsiem_parser.

New in crowdstrike.falcon 4.13.0

Synopsis

  • Create, update, clone, and delete custom NG-SIEM parsers in the CrowdStrike Falcon platform.

  • Parsers transform raw log data into normalized events for Next-Gen SIEM.

  • Custom parsers are managed through LogScale YAML templates. Provide the full template via parser_yaml for create and update operations.

  • Supports idempotent operations that only make changes when the meaningful parser content differs from what is already stored.

  • Use crowdstrike.falcon.ngsiem_parser_info to discover existing parsers and retrieve their definitions.

Requirements

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

  • CrowdStrike FalconPy >= 1.6.3

  • NGSIEM Parsers [READ, WRITE] API scope

  • crowdstrike-falconpy >= 1.5.0

  • python >= 3.8

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.

clone_from

string

The ID of a source parser to clone into a new parser named name.

Mutually exclusive with parser_yaml and extension_of.

Only applies when the target parser (name) does not already exist.

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.

extension_of

string

The unversioned base parser ID to create an extension of, named name.

Note: The base parser ID must be unversioned (no :x.y.z suffix).

Mutually exclusive with parser_yaml and clone_from.

Only applies when the target parser (name) does not already exist.

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 parser.

Required when creating a new parser and when using clone_from or extension_of.

Used to look up an existing parser when parser_id is not provided.

parser_id

string

The version-suffixed ID of an existing parser (e.g. abc123:1.0.0).

Preferred for identifying an existing parser during update or delete.

When provided with state=absent, the parser is deleted by ID.

parser_yaml

string

The full LogScale parser YAML template.

Required when creating or updating a parser via state=present unless clone_from or extension_of is used.

For idempotency, the module compares the script, tagFields, and testCases of this template against the stored parser and only updates when they differ.

repository

string

The name of the repository the parser belongs to.

Default: "parsers-repository"

state

string

The desired state of the parser.

present ensures the parser exists with the specified content.

absent ensures the parser does not exist.

Choices:

  • "present" ← (default)

  • "absent"

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: For state=present with parser_yaml, the module fetches the current parser template and compares script, tagFields, and testCases semantically (ignoring whitespace and the auto-incremented version). Perfect round-trip idempotency is not guaranteed because the server normalizes stored scripts; a re-run may report a change if the server reformats content.

  • Versioning: Custom parsers auto-increment their version on each update or clone. The returned parser ID is version-suffixed and will differ from the input ID after an update.

  • Parser Lookup: When parser_id is not provided, the module searches by exact name. Prefer parser_id for precise targeting.

  • State Management: For state=absent, if the parser is not found, the module exits successfully without making any changes (idempotent). A stale index entry that 404s on delete is treated as already absent.

  • Check mode: In check mode the module reports the intended change without mutating the parser.

Examples

- name: Create a custom parser from a YAML template
  crowdstrike.falcon.ngsiem_parser:
    name: my-custom-parser
    parser_yaml: "{{ lookup('file', 'my-parser.yaml') }}"

- name: Update a parser (idempotent - only changes when content differs)
  crowdstrike.falcon.ngsiem_parser:
    name: my-custom-parser
    parser_yaml: "{{ lookup('file', 'my-parser-v2.yaml') }}"

- name: Clone an existing parser into a new one
  crowdstrike.falcon.ngsiem_parser:
    name: my-cloned-parser
    clone_from: "10f55deaa2893f60b87af305f44f80bf:1.0.0"

- name: Create an extension of a base parser (base ID must be unversioned)
  crowdstrike.falcon.ngsiem_parser:
    name: my-parser-extension
    extension_of: "10f55deaa2893f60b87af305f44f80bf"

- name: Delete a parser by name
  crowdstrike.falcon.ngsiem_parser:
    name: my-custom-parser
    state: absent

- name: Delete a parser by ID
  crowdstrike.falcon.ngsiem_parser:
    parser_id: "10f55deaa2893f60b87af305f44f80bf:1.1.0"
    state: absent

Return Values

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

Key

Description

parser

dictionary

Information about the parser that was created, updated, or cloned.

Returned: when state=present and a parser exists

fields_to_tag

list / elements=string

The list of fields to tag on parsed events.

Returned: success

id

string

The version-suffixed unique identifier of the parser.

Returned: success

Sample: "10f55deaa2893f60b87af305f44f80bf:1.1.0"

name

string

The name of the parser.

Returned: success

Sample: "my-custom-parser"

script

string

The LogScale/CQL parsing script.

Returned: success

test_cases

list / elements=string

The list of test cases associated with the parser.

Returned: success

Authors

  • Carlos Matos (@carlosmmatos)