falcon_hosts

Query asset details from the CrowdStrike Falcon Hosts API. The inventory file is a YAML configuration and must end with C(falcon_hosts.{yml|yaml}). “Example: C(my_inventory.falcon_hosts.yml)”

Added in version 4.3.0

Parameters

Parameter	Type	Required	Default	Description
client_id	str	No		The CrowdStrike API client ID to use. See the L(Falcon documentation,https://falcon.crowdstrike.com/documentation/46/crowdstrike-oauth2-based-apis#understanding-api-clients) The C(FALCON_CLIENT_ID) environment variable can also be used. This option can be set using a Jinja2 template value.
client_secret	str	No		The CrowdStrike API secret that corresponds to the client ID. See the L(Falcon documentation,https://falcon.crowdstrike.com/documentation/46/crowdstrike-oauth2-based-apis#understanding-api-clients) The C(FALCON_CLIENT_SECRET) environment variable can also be used. This option can be set using a Jinja2 template value.
cloud	str	No	us-1	The CrowdStrike cloud region to use. All clouds are automatically discovered if not specified, except for the C(us-gov-1) cloud. The C(FALCON_CLOUD) environment variable can also be used. This option can be set using a Jinja2 template value. Valid values are C(us-1), C(us-2), C(eu-1), C(us-gov-1).
filter	str	No		The filter expression that should be used to limit the results using FQL See the L(Falcon documentation,https://falcon.crowdstrike.com/documentation/page/c0b16f1b/host-and-host-group-management-apis#qadd6f8f)
hostnames	list	No	[‘hostname’, ‘external_ip’, ‘local_ip’]	A list of templates in order of precedence to compose C(inventory_hostname). Ignores template if resulted in an empty string or None value. You can use any host variable as a template. The default is to use the hostname, external_ip, and local_ip in that order.
member_cid	str	No		The CrowdStrike member CID for MSSP authentication. See the L(Falcon documentation,https://falcon.crowdstrike.com/documentation/46/crowdstrike-oauth2-based-apis#understanding-api-clients) The C(FALCON_MEMBER_CID) environment variable can also be used. This option can be set using a Jinja2 template value.

Examples

# sample file: my_inventory.falcon_hosts.yml

# required for all falcon_hosts inventory plugin configs
plugin: crowdstrike.falcon.falcon_hosts

# authentication credentials (required if not using environment variables)
# client_id: 1234567890abcdef12345678
# client_secret: 1234567890abcdef1234567890abcdef12345
# cloud: us-1

# authentication example using hashicorp vault lookup plugin
# client_id: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=path/to/secret:client_id') }}"
# client_secret: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=path/to/secret:client_secret') }}"
# cloud: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=path/to/secret:cloud') }}"

# return all Windows hosts (authentication via environment variables)
# filter: "platform_name:'Windows'"

# return all Linux hosts in reduced functionality mode
# filter: "platform_name:'Linux' + reduced_functionality_mode:'yes'"

# return stale devices that haven't checked in for 15 days
# filter: "last_seen:<='now-15d'"

# return all Linux hosts running in eBPF User Mode
# filter: "linux_sensor_mode:'User Mode'"

# place hosts into dynamically created groups based on variable values
keyed_groups:
  # places host in a group named tag_<tags> for each tag on a host
  - prefix: tag
    key: tags
  # places host in a group named platform_<platform_name> based on the
  # platform name (Linux, Windows, etc.)
  - prefix: platform
    key: platform_name
  # places host in a group named tag_<tags> for each tag on a host
  - prefix: rfm
    key: reduced_functionality_mode

# place hosts into dynamically created groups based on conditional statements
groups:
  # places hosts in a group named windows_hosts if the platform_name is Windows
  windows_hosts: "platform_name == 'Windows'"
  # place hosts in a group named aws_us_west_2 if the zone_group is in us-west-2
  aws_us_west_2: "'us-west-2' in zone_group and 'Amazon' in system_manufacturer"

# compose inventory_hostname from Jinja2 expressions
# hostnames:
#   - hostname|lower

# compose inventory_hostname from Jinja2 expressions with order of precedence
# hostnames:
#   - external_ip
#   - local_ip
#   - serial_number

# use device_id as the inventory_hostname to prevent deduplication and set ansible_host
# to a reachable attribute
# hostnames:
#   - device_id
# compose:
#   ansible_host: hostname | default(external_ip) | default(local_ip) | default(None)

# compose connection variables for each host
# compose:
#   ansible_host: external_ip
#   ansible_user: "'root'"
#   ansible_ssh_private_key_file: "'/path/to/private_key_file'"

# Use caching for the inventory
# cache: true
# cache_plugin: jsonfile
# cache_connection: /tmp/falcon_inventory
# cache_timeout: 1800
# cache_prefix: falcon_hosts