crowdstrike.falcon.rtr connection – run tasks on Falcon hosts through Real Time Response

Note

This connection plugin is part of the crowdstrike.falcon collection (version 4.15.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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

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

New in crowdstrike.falcon 4.15.0

Synopsis

  • This connection plugin runs Ansible tasks on a host through CrowdStrike Falcon Real Time Response (RTR). The controller talks only to the Falcon API; the host needs no SSH access and no open inbound port.

  • RTR keeps working when Falcon network containment isolates the host, so Ansible can collect data from or fix a contained host.

  • Modules run the normal way. On Linux and macOS, the plugin uploads each module file (small files as base64 in one RTR runscript, larger files as an RTR put-file and the put command), then runs it with the Python of the host.

  • The RTR response policy of the host must turn on Real Time Response, custom scripts and the put command.

  • Read-only access to the RTR API is equivalent to Domain Admin level access. Give the API client only to trusted users.

  • Linux and macOS hosts use the sh shell.

  • Windows hosts are supported with ansible_shell_type=powershell. Tasks run as NT AUTHORITY\SYSTEM in Windows PowerShell 5.1. Use the ansible.windows modules on Windows hosts.

  • The plugin compares the platform that RTR reports for the host with the shell type, and fails when they do not match.

Requirements

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

  • crowdstrike-falconpy >= 1.5.0

  • Real time response [READ] and [WRITE] API scopes

  • Real time response (admin) [WRITE] API scope

  • Hosts [READ] API scope when device_id is a host name

Parameters

Parameter

Comments

client_id

string

The CrowdStrike API client ID to use.

Configuration:

client_secret

string

The CrowdStrike API secret that corresponds to the client ID.

Configuration:

cloud

string

The CrowdStrike cloud region to use.

Choices:

  • "us-1" ← (default)

  • "us-2"

  • "us-3"

  • "eu-1"

  • "us-gov-1"

  • "us-gov-2"

Configuration:

  • Environment variable: FALCON_CLOUD

  • Variable: ansible_falcon_cloud

command_timeout

integer

The number of seconds that one RTR command can run on the host, from 1 to 600.

The plugin stops waiting for the result 60 seconds after this time.

Default: 600

Configuration:

  • INI entry:

    [rtr_connection]
    command_timeout = 600
    
  • Variable: ansible_rtr_command_timeout

device_id

string

The host to connect to.

A value of 32 hexadecimal characters is used as the device ID (AID). Any other value is a host name, which the plugin resolves with the Hosts API. The name must match one host exactly (case does not matter).

When not set, the plugin uses the address of the host (ansible_host or the inventory host name).

Configuration:

  • Variable: ansible_host

  • Variable: ansible_rtr_device_id

inline_max_bytes

integer

Files up to this size in bytes are uploaded as base64 in one RTR command. Larger files use an RTR put-file.

The value must be 0 or more. A value above 22000 is used as 22000, because the RTR API limits the size of a script.

Default: 16384

Configuration:

  • Variable: ansible_rtr_inline_max_bytes

member_cid

string

The CrowdStrike member CID for MSSP authentication.

Configuration:

poll_interval

float

The number of seconds between two status checks of a running RTR command.

The value must be more than 0 and at most 60.

Default: 0.5

Configuration:

  • Variable: ansible_rtr_poll_interval

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) 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. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Notes

Note

  • On Linux and macOS, the host needs Python 3 for modules. Tasks run as root.

  • Pipelining is not supported on Linux and macOS. A module file is too large for one RTR command, so the plugin always uploads it first.

  • On Windows, tasks run as NT AUTHORITY\SYSTEM in Windows PowerShell 5.1. Each task sends its module as an RTR put-file and runs it with the PowerShell of the host; the plugin always pipelines on Windows, as the Windows connection plugins of Ansible do.

  • On Linux and macOS, use become only with sudo to another user, or not at all. RTR gives no terminal, so a become password prompt cannot be answered.

  • become is not supported on Windows hosts.

  • One RTR command can run for at most 10 minutes. Use async for longer tasks.

  • Under network containment, the host can reach only the Falcon cloud. Tasks that need other network access (package mirrors, for example) fail.

  • RTR records the text of each command in its audit log, and the sensor records the same text as a process command line in the Falcon event data. This text holds the commands that Ansible runs, and the base64 content of each file that the plugin uploads inline (up to inline_max_bytes), also for tasks with no_log. Do not send secrets in small files or in raw commands through this plugin.

  • Module files (with the module arguments) go up as RTR put-files. The plugin deletes each put-file after the transfer. Other RTR administrators can see it while it exists.

  • fetch reads the whole file into memory on the controller.

  • The plugin locks each host for the cd and put steps of an upload, for the forks of one controller only. Two controllers that use the same API client on the same host at the same time can collide during uploads.

  • The RTR session ends on the Falcon side after 10 minutes without commands.

See Also

See also

crowdstrike.falcon.host_contain

Network contain hosts in Falcon.

crowdstrike.falcon.falcon_hosts inventory plugin

CrowdStrike Falcon Hosts inventory source.

Examples

# Static inventory (inventory.yml) with the device ID of each host:
#
# all:
#   hosts:
#     web01:
#       ansible_connection: crowdstrike.falcon.rtr
#       ansible_rtr_device_id: 0123456789abcdef0123456789abcdef
#
# The credentials come from FALCON_CLIENT_ID, FALCON_CLIENT_SECRET and
# FALCON_CLOUD, or from the ansible_falcon_* variables.

# A Windows host needs the powershell shell type:
#
# all:
#   hosts:
#     win01:
#       ansible_connection: crowdstrike.falcon.rtr
#       ansible_rtr_device_id: fedcba9876543210fedcba9876543210
#       ansible_shell_type: powershell

# Dynamic inventory (falcon_hosts.yml) that reaches each host over RTR:
#
# plugin: crowdstrike.falcon.falcon_hosts
# filter: "platform_name:['Linux','Mac','Windows']"
# hostnames:
#   - device_id
# compose:
#   ansible_connection: "'crowdstrike.falcon.rtr'"
#   ansible_shell_type: "'powershell' if platform_name == 'Windows' else 'sh'"

# Contain a host, then collect data from it over RTR.
- name: Contain the host
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Contain the host in Falcon
      crowdstrike.falcon.host_contain:
        hosts:
          - "{{ hostvars['web01'].ansible_rtr_device_id }}"
        contained: true

- name: Collect data from the contained host
  hosts: web01
  gather_facts: false
  tasks:
    - name: List the open connections
      ansible.builtin.command: ss -tanp
      register: connections
      changed_when: false

    - name: Fetch the authentication log
      ansible.builtin.fetch:
        src: /var/log/auth.log
        dest: "evidence/{{ inventory_hostname }}/"

# Collect data from a Windows host over RTR.
- name: Collect data from the Windows host
  hosts: win01
  gather_facts: false
  tasks:
    - name: List the open connections
      ansible.windows.win_command: netstat -ano
      register: win_connections
      changed_when: false

    - name: Fetch the hosts file
      ansible.builtin.fetch:
        src: C:\Windows\System32\drivers\etc\hosts
        dest: "evidence/{{ inventory_hostname }}/"

Authors

  • Carlos Matos (@carlosmmatos)