crowdstrike.falcon.host_hide module – Hide/Unhide hosts from the Falcon console

Note

This module 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 module, see Requirements for details.

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

New in crowdstrike.falcon 4.0.0

Synopsis

  • Manages the visibility of hosts in the Falcon console.

  • To prevent unnecessary detections from an inactive or a duplicate host, you can opt to hide the host from the console. This action does not uninstall or deactivate the sensor. Detection reporting resumes after a host is unhidden.

  • The module will return a list of successful and failed hosts agent IDs (AIDs) for the action performed.

Requirements

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

  • Hosts [WRITE] API scope

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

hidden

boolean

Whether to hide or unhide the hosts.

Choices:

  • false

  • true ← (default)

hosts

list / elements=string / required

A list of host agent IDs (AIDs) to perform the action on.

Use the crowdstrike.falcon.host_ids lookup plugin to get a list of host IDs matching specific criteria.

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

  • While you can use this module to hide or unhide hosts, it is recommended to use the Host Retention Policies in the Falcon console to create policies to manage automatically hiding and deleting hosts in the console instead of using this module.

  • This module handles the 100 hosts per request limit by the Falcon API. This means that if more than 100 hosts are passed to the module, it will process them in batches of 100 automatically.

  • For large numbers of hosts, this module may take some time to complete.

  • Failure Handling: This module will not fail if some hosts could not be hidden or unhidden. Instead, it will populate the ‘failed_hosts’ list with the relevant host IDs and error details. This is designed to allow the user greater flexibility in handling failures, especially when this module is used in a loop. If strict failure handling is needed, users should explicitly check the ‘failed_hosts’ list after execution. See the examples for more details.

Examples

- name: Hide a host from the Falcon console
  crowdstrike.falcon.host_hide:
    hosts: "12345678901234567890"

- name: Unhide hosts from the Falcon console
  crowdstrike.falcon.host_hide:
    hosts:
      - "12345678901234567890"
      - "09876543210987654321"
    hidden: false

- name: Hide all stale hosts that have not checked in for 30 days (using host_ids lookup)
  crowdstrike.falcon.host_hide:
    hosts: "{{ lookup('crowdstrike.falcon.host_ids', stale_filter) }}"
  vars:
    stale_filter: 'last_seen:<="now-15d"'

- name: Individually hide hosts with a list from the Falcon console
  crowdstrike.falcon.host_hide:
    auth: "{{ falcon.auth }}"  # Use auth saved from crowdstrike.falcon.auth module
    hosts: "{{ item }}"
  loop: "{{ host_ids }}"
  register: hide_result

- name: Fail if any hosts could not be hidden
  fail:
    msg: "Hosts could not be hidden: {{ hide_result.failed_hosts }}"
  when: hide_result.failed_hosts | length > 0

Return Values

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

Key

Description

failed_hosts

list / elements=dictionary

A list of dictionaries containing host IDs that failed to be hidden or unhidden.

Returned: always

code

integer

The error code returned by the API.

Returned: when a host agent ID fails

id

string

The host agent ID that failed to be hidden or unhidden.

Returned: when a host agent ID fails

message

string

The error message returned by the API.

Returned: when a host agent ID fails

hosts

list / elements=string

A list of host agent IDs (AIDs) that were successfully hidden or unhidden.

Returned: always

Authors

  • Carlos Matos (@carlosmmatos)