crowdstrike.falcon.ngsiem_data_connection module – Manage NG-SIEM data connections

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

New in crowdstrike.falcon 4.13.0

Synopsis 

Create, update, delete, and pause/resume NG-SIEM data connections in the CrowdStrike Falcon platform.
Data connections feed third-party log sources into Next-Gen SIEM. They come in two shapes - PULL connections (e.g. AWS S3, Azure Event Hubs) where Falcon pulls from your source using credentials in a config block, and PUSH connections (e.g. HEC / HTTP Event Connector) where you push logs to an ingest_url using an ingest token.
Supports idempotent operations that only make changes when necessary.
Use crowdstrike.falcon.ngsiem_data_connector_info to discover valid connector_id and parser values.

Requirements 

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

CrowdStrike FalconPy >= 1.5.0
NGSIEM Data Connections [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.
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"`
config dictionary	A free-form configuration dict for the connection. Used by PULL connectors to supply authentication and parameters (e.g. `config.auth`, `config.params`). Note: This field is write-only. It is applied on create but is never returned by the API, so changes to it alone cannot be detected for idempotency.
config_id string	The ID of a saved connector config to associate with the connection.
connection_id string	The ID of an existing data connection. Preferred for identifying existing connections during update, delete, or pause/resume operations. Either connection_id or name is required.
connector_id string	The ID of the connector this connection is based on. Required when creating a new connection. Use crowdstrike.falcon.ngsiem_data_connector_info to discover available connectors.
connector_type string	The type of the connector.
description string	A description for the data connection. Note: This field is write-only. It is applied on create but is never returned by the API, so changes to it alone cannot be detected for idempotency.
enable_host_enrichment boolean	Whether to enable host enrichment for the connection. Note: This field is write-only. It is applied on create but is never returned by the API, so changes to it alone cannot be detected for idempotency. Choices: `false` `true`
enable_user_enrichment boolean	Whether to enable user enrichment for the connection. Note: This field is write-only. It is applied on create but is never returned by the API, so changes to it alone cannot be detected for idempotency. Choices: `false` `true`
enabled boolean	Whether the connection should be running (resumed) or paused. `true` resumes a paused connection; `false` pauses a running connection. Only applied when the connection already exists. Pausing is only valid when the connection is in an `Active`, `Error`, or `Idle` state; the module reads the current status first and no-ops otherwise. Choices: `false` `true`
ext_headers dictionary	Extended headers that are prepended to the default headers dictionary.
log_sources list / elements=string	A list of log sources for the connection.
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 data connection. Required when creating a new connection and connection_id is not provided. Used to look up an existing connection when connection_id is not specified.
parser string	The parser to apply to the connection’s data. Required when creating a new connection. The value must be valid for the chosen connector (e.g. `microsoft-edge`). The API is the source of truth and will reject invalid parsers.
state string	The desired state of the data connection. `present` ensures the connection exists with the specified configuration. `absent` ensures the connection 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.
vendor_name string	The vendor name associated with the connection.
vendor_product_name string	The vendor product name associated with the connection.
wait_for_ingest_token boolean	Whether to wait for the ingest token to become available when creating a PUSH connection. The token is minted on the first successful request, but immediately after create the connection is still provisioning and the token endpoint returns “not ready”. When `true`, the module polls until the token is available or wait_timeout is reached. The token is a one-time secret - it can only be retrieved once, so enabling this is the only reliable way to capture it during creation. Only applies to the create of a PUSH connection. Choices: `false` `true` ← (default)
wait_timeout integer	Maximum number of seconds to wait for the ingest token when wait_for_ingest_token is `true`. If the token is still not available after this timeout, the connection is left created and the module returns without the token (with a warning) rather than failing. Default: `120`

Notes 

Note

Idempotency: This module is idempotent and will only make changes when the current state differs from the desired state.
Drift detection: Idempotency is determined by comparing name and parser against the existing connection. Vendor fields are not compared because some connectors (e.g. the built-in HEC connector) override vendor_product_name with their own value on create. Changes to description, config, or the enrichment flags cannot be detected either (the API never returns them); they are only applied on create.
Connection Lookup: When connection_id is not provided, the module searches by name. Prefer connection_id for precise targeting.
Ingest token: For PUSH connections, an ingest token is minted and returned once on create as the ingest_token value alongside ingest_url. The token cannot be retrieved again, so it is a sensitive value - handle and store it securely. Because the connection is still provisioning immediately after create, the module waits for the token by default (see wait_for_ingest_token and wait_timeout). Token rotation is not supported in this module.
State Management: For state=absent, if the connection is not found, the module exits successfully without making any changes (idempotent).

Examples 

- name: Create a PUSH (HEC) data connection
  crowdstrike.falcon.ngsiem_data_connection:
    name: "Edge browser logs"
    connector_id: "a1bfd0c4380f436790cb41afc2b95f38"
    parser: "microsoft-edge"
    vendor_name: "Microsoft"
    vendor_product_name: "Edge"
  register: hec_connection

- name: Show the ingest URL (the token is sensitive and only returned once on create)
  ansible.builtin.debug:
    var: hec_connection.data_connection.ingest_url

- name: Create a PULL (S3) data connection with auth config
  crowdstrike.falcon.ngsiem_data_connection:
    name: "AWS S3 CloudTrail"
    connector_id: "0123456789abcdef0123456789abcdef"
    parser: "aws-cloudtrail"
    vendor_name: "AWS"
    vendor_product_name: "CloudTrail"
    config:
      auth:
        access_key_id: "{{ aws_access_key_id }}"
        secret_access_key: "{{ aws_secret_access_key }}"
      params:
        bucket: "my-cloudtrail-bucket"
        region: "us-east-1"

- name: Update a connection's name by ID
  crowdstrike.falcon.ngsiem_data_connection:
    connection_id: "abcdef1234567890abcdef1234567890"
    name: "Edge browser logs (renamed)"

- name: Pause a connection
  crowdstrike.falcon.ngsiem_data_connection:
    connection_id: "abcdef1234567890abcdef1234567890"
    enabled: false

- name: Resume a connection
  crowdstrike.falcon.ngsiem_data_connection:
    connection_id: "abcdef1234567890abcdef1234567890"
    enabled: true

- name: Delete a connection by name
  crowdstrike.falcon.ngsiem_data_connection:
    name: "Edge browser logs"
    state: absent

- name: Delete a connection by ID
  crowdstrike.falcon.ngsiem_data_connection:
    connection_id: "abcdef1234567890abcdef1234567890"
    state: absent

Return Values 

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

Key	Description
data_connection dictionary	Information about the data connection that was created or updated. Only fields returned by the API are included. Returned: when state=present
id string	The unique identifier of the data connection. Returned: success Sample: `"abcdef1234567890abcdef1234567890"`
ingest_url string	The URL to push logs to (PUSH connections only, after provisioning). Returned: when available Sample: `"https://ingest.us-2.crowdstrike.com/services/collector/..."`
last_ingested_volume_one_day integer	The volume ingested in the last day. Returned: success
name string	The name of the data connection. Returned: success Sample: `"Edge browser logs"`
parser_name string	The parser applied to the connection’s data. Returned: success Sample: `"microsoft-edge"`
source_type string	The source type of the connection. Returned: success
status string	The current status of the connection. Returned: success Sample: `"Active"`
vendor_name string	The vendor name associated with the connection. Returned: success Sample: `"Microsoft"`
vendor_product_name string	The vendor product name associated with the connection. Returned: success Sample: `"Edge"`
ingest_token string	The ingest token for a PUSH connection. Minted and returned only once, on create of a PUSH connection. It cannot be retrieved again. This is a sensitive value; handle and store it securely. Returned: on create of a PUSH connection

Authors

Carlos Matos (@carlosmmatos)

crowdstrike.falcon.ngsiem_data_connection module – Manage NG-SIEM data connections

Synopsis

Requirements

Parameters

Notes

Examples

Return Values