crowdstrike.falcon.host_contain (4.3.2) — module

Install collection

Install with ansible-galaxy collection install crowdstrike.falcon:==4.3.2

Add to requirements.yml

  collections:
    - name: crowdstrike.falcon
      version: 4.3.2

Description

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 successfull and failed hosts agent IDs (AIDs) for the action performed.

Requirements

• Hosts [B(WRITE)] API scope
• crowdstrike-falconpy >= 1.3.0
• python >= 3.6

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Contain a single host
  crowdstrike.falcon.host_contain:
    hosts: "12345678901234567890"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
auth:
    description:
    - The registered result of the M(crowdstrike.falcon.auth) module, or a dictionary
      containing the I(access_token) and I(cloud) keys.
    - If provided, the I(client_id), I(client_secret), I(member_cid), and I(cloud) options
      are ignored.
    - Useful when needing to make multiple API calls to avoid rate limiting issues.
    suboptions:
      access_token:
        description:
        - The OAuth2 access token to use for authentication.
        type: str
      cloud:
        description:
        - The CrowdStrike cloud region to use.
        - This can differ from the module's I(cloud) argument due to autodiscovery.
        type: str
    type: dict

cloud:
    choices:
    - us-1
    - us-2
    - us-gov-1
    - eu-1
    default: us-1
    description:
    - 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.
    type: str

hosts:
    description:
    - A list of host agent IDs (AIDs) to perform the action on.
    elements: str
    required: true
    type: list

client_id:
    aliases:
    - falcon_client_id
    description:
    - 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)
      for more information about API clients.
    - The C(FALCON_CLIENT_ID) environment variable can also be used.
    type: str

contained:
    default: true
    description:
    - Whether to contain or lift containment on the hosts.
    type: bool

member_cid:
    description:
    - 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)
      for more information about API clients.
    - The C(FALCON_MEMBER_CID) environment variable can also be used.
    type: str

user_agent:
    description:
    - Custom User-Agent string to use for requests to the API.
    - The user agent string is prepended to the default user agent string (C(crowdstrike-ansible/<version>)).
    - See L(RFC 7231,https://tools.ietf.org/html/rfc7231#section-5.5.3) for more information.
    - The C(FALCON_USER_AGENT) environment variable can also be used.
    type: str

ext_headers:
    description:
    - Extended headers that are prepended to the default headers dictionary.
    type: dict

client_secret:
    aliases:
    - falcon_client_secret
    description:
    - 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)
      for more information about API clients.
    - The C(FALCON_CLIENT_SECRET) environment variable can also be used.
    type: str

Outputs

failed_hosts:
  contains:
    code:
      description:
      - The error code returned by the API.
      returned: when a host agent ID fails
      type: int
    id:
      description:
      - The host agent ID that failed to be contained or lifted from containment.
      returned: when a host agent ID fails
      type: str
    message:
      description:
      - The error message returned by the API.
      returned: when a host agent ID fails
      type: str
  description:
  - A list of dictionaries containing host IDs that failed to be contained or lifted
    from containment.
  elements: dict
  returned: always
  type: list
hosts:
  description:
  - A list of host agent IDs (AIDs) that were successfully contained or lifted from
    containment.
  elements: str
  returned: always
  type: list