crowdstrike.falcon.host_contain module – Network contain hosts in Falcon

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

New in crowdstrike.falcon 4.1.0

Synopsis

  • Manages the network containment state of Falcon hosts.

  • To restrict a host that may be compromised from making network connections, contain it within the network. Lift containment to restore its regular communication capabilities.

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

contained

boolean

Whether to contain or lift containment on the hosts.

Choices:

  • false

  • true ← (default)

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

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

  • Failure Handling: This module will not fail if some hosts could not be contained or lifted from containment. 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: Contain a single host
  crowdstrike.falcon.host_contain:
    hosts: "12345678901234567890"

- name: Lift containment on a list of hosts
  crowdstrike.falcon.host_contain:
    hosts:
      - "12345678901234567890"
      - "09876543210987654321"
    contained: no

- name: Contain all Linux hosts in RFM (using host_ids lookup)
  crowdstrike.falcon.host_contain:
    hosts: "{{ lookup('crowdstrike.falcon.host_ids', contain_filter) }}"
    contained: yes
  vars:
    linux_rfm_filter: >
      platform_name:'Linux' +
      reduced_functionality_mode:'yes'

- name: Individually contain hosts within a list
  crowdstrike.falcon.host_contain:
    auth: "{{ falcon.auth }}"  # Use auth saved from crowdstrike.falcon.auth module
    hosts: "{{ item }}"
  loop: "{{ host_ids }}"
  register: contain_results

- name: Fail if any hosts could not be contained
  fail:
    msg: "Hosts could not be contained: {{ contain_results.failed_hosts }}"
  when: contain_results.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 contained or lifted from containment.

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 contained or lifted from containment.

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 contained or lifted from containment.

Returned: always

Authors

  • Carlos Matos (@carlosmmatos)