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 theputcommand), 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
putcommand.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
shshell.Windows hosts are supported with
ansible_shell_type=powershell. Tasks run asNT AUTHORITY\SYSTEMin Windows PowerShell 5.1. Use theansible.windowsmodules 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_idis a host name
Parameters
Parameter |
Comments |
|---|---|
The CrowdStrike API client ID to use. Configuration:
|
|
The CrowdStrike API secret that corresponds to the client ID. Configuration:
|
|
The CrowdStrike cloud region to use. Choices:
Configuration:
|
|
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: Configuration:
|
|
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 ( Configuration:
|
|
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: Configuration:
|
|
The CrowdStrike member CID for MSSP authentication. Configuration:
|
|
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: Configuration:
|
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\SYSTEMin 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
becomeonly withsudoto another user, or not at all. RTR gives no terminal, so a become password prompt cannot be answered.becomeis not supported on Windows hosts.One RTR command can run for at most 10 minutes. Use
asyncfor 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 withno_log. Do not send secrets in small files or inrawcommands 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.
fetchreads the whole file into memory on the controller.The plugin locks each host for the
cdandputsteps 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 }}/"