crowdstrike.falcon.host_ids lookup – fetch host IDs (AIDs)

Note

This lookup plugin is part of the crowdstrike.falcon collection (version 4.7.2).

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

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

New in crowdstrike.falcon 4.4.0

Synopsis

  • This lookup returns a list of host IDs (AIDs) which match the search criteria.

  • You can use optional FQL filters in your requests to find host IDs based on specific attributes, such as platform, hostname, or IP.

  • Can be used for other modules that require a list of host IDs as input.

Requirements

The below requirements are needed on the local controller node that executes this lookup.

  • Hosts [READ] API scope

  • crowdstrike-falconpy >= 1.3.0

  • python >= 3.6

Terms

Parameter

Comments

Terms

string

The filter expression that should be used to limit the results using FQL (Falcon Query Language) syntax.

See the Falcon documentation for more information about the available filters.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('crowdstrike.falcon.host_ids', key1=value1, key2=value2, ...) and query('crowdstrike.falcon.host_ids', key1=value1, key2=value2, ...)

Parameter

Comments

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.

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.

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

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('crowdstrike.falcon.host_ids', term1, term2, key1=value1, key2=value2) and query('crowdstrike.falcon.host_ids', term1, term2, key1=value1, key2=value2)

  • This plugin will automatically handle pagination for you, so you do not need to worry about it.

  • You can avoid escaping double quotes by using a multiline string or setting a variable. See examples.

Examples

- name: Print all hosts IDs
  ansible.builtin.debug:
    msg: "{{ lookup('crowdstrike.falcon.host_ids', '') }}"

- name: Print all Windows hosts IDs (escaped double quotes)
  ansible.builtin.debug:
    msg: "{{ lookup('crowdstrike.falcon.host_ids', 'platform_name:\"Windows\"') }}"

- name: Print all Linux hosts IDs in reduced functionality mode (multiline string)
  ansible.builtin.debug:
    msg: >
      {{
        lookup('crowdstrike.falcon.host_ids',
          'platform_name:"Linux"
          + reduced_functionality_mode:"yes"')
      }}

Return Value

Key

Description

Return value

list / elements=string

A list of host IDs (AIDs) that match the search criteria.

Returned: success

Authors

  • Carlos Matos (@carlosmmatos)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.