Using the Hosts service collection

This service collection has code examples posted to the repository.

Table of Contents

Operation ID	Description
GetDeviceDetails PEP 8 get_device_details	Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API. (Maximum: 5000)
GetDeviceDetailsV1 PEP 8 get_device_details_v1	Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API. (Maximum: 500)
GetDeviceDetailsV2 PEP 8 get_device_details_v2	Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API. (Maximum: 100)
PostDeviceDetailsV2 PEP 8 post_device_details_v2	Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API. (Maximum: 5000)
PerformActionV2 PEP 8 perform_action	Take various actions on the hosts in your environment. Contain or lift containment on a host. Delete or restore a host.
entities_perform_action PEP8 perform_group_action	Performs the specified action on the provided prevention policy IDs.
QueryDevicesByFilter PEP 8 query_devices_by_filter	Search for hosts in your environment by platform, hostname, IP, and other criteria.
QueryDevicesByFilterScroll PEP 8 query_devices_by_filter_scroll	Search for hosts in your environment by platform, hostname, IP, and other criteria with continuous pagination capability (based on offset pointer which expires after 2 minutes with no maximum limit)
QueryDeviceLoginHistory PEP 8 query_device_login_history	Retrieve details about recent login sessions for a set of devices.
QueryDeviceLoginHistoryV2 PEP 8 query_device_login_history_v2	Retrieve details about recent login sessions for a set of devices.
QueryGetNetworkAddressHistoryV1 PEP 8 query_network_address_history	Retrieve history of IP and MAC addresses of devices.
GetOnlineState_V1 PEP 8 get_online_state	Get the online status for one or more hosts by specifying each host’s unique ID.
QueryHiddenDevices PEP 8 query_hidden_devices	Retrieve hidden hosts that match the provided filter criteria.
UpdateDeviceTags PEP 8 update_device_tags	Append or remove one or more Falcon Grouping Tags on one or more hosts.

Passing credentials

WARNING

client_id and client_secret are keyword arguments that contain your CrowdStrike API credentials. Please note that all examples below do not hard code these values. (These values are ingested as strings.)

CrowdStrike does not recommend hard coding API credentials or customer identifiers within source code.

GetDeviceDetails

Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API.

Starting in v1.2.0 all methods for this operation redirect to the new PostDeviceDetailsV2 operation. In prior versions, this operation ID represented a GET operation, whereas now it is a POST operation. For backwards-compatibility purposes, IDs provided to this operation as part of a query string payload (parameters) will be converted to the body payload. This migration of IDs will not override a provided body payload, or ids array.

PEP8 method name

get_device_details (or post_device_details_v2)

Endpoint

Method	Route
	/devices/entities/devices/v2

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	dictionary	Full body payload in JSON format.
ids			body	string or list of strings	The host agent IDs used to get details on. Maximum: 5000.
parameters			query (will be converted to body)	dictionary	Full query string parameters payload in JSON format. This operation does not use a query string payload. This keyword is maintained for backwards compatibility purposes only. When provided, this dictionary is converted to be the body payload, but it will not override an existing body payload.

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_device_details(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetDeviceDetails(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("GetDeviceDetails", ids=id_list)

print(response)

Back to Table of Contents

GetDeviceDetailsV1

Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API.

This operation is deprecated and scheduled to be removed from the API in 2023.

PEP8 method name

get_device_details_v1

Endpoint

Method	Route
	/devices/entities/devices/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	The host agent IDs used to get details on. Maximum: 500
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_device_details_v1(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetDeviceDetailsV1(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("GetDeviceDetailsV1", ids=id_list)

print(response)

Back to Table of Contents

GetDeviceDetailsV2

Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API.

PEP8 method name

get_device_details_v2

Endpoint

Method	Route
	/devices/entities/devices/v2

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	The host agent IDs used to get details on. Maximum: 100
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_device_details_v2(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetDeviceDetailsV2(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("GetDeviceDetailsV2", ids=id_list)

print(response)

Back to Table of Contents

PostDeviceDetailsV2

Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the QueryDevicesByFilterScroll operation, the Falcon console or the Streaming API.

Starting in v1.2.0 this operation is redirected to from methods previously providing the GetDeviceDetails operation. The PEP 8 and Operation ID methods for this operation are aliases for the new get_device_details method. Developers may use either operation ID and either syntax as per their preference to access this operation.

PEP8 method name

post_device_details_v2 (or get_device_details)

Endpoint

Method	Route
	/devices/entities/devices/v2

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	dictionary	Full body payload in JSON format.
ids			body	string or list of strings	The host agent IDs used to get details on. Maximum: 5000

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.post_device_details_v2(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.PostDeviceDetailsV2(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("PostDeviceDetailsV2", ids=id_list)

print(response)

Back to Table of Contents

PerformActionV2

Take various actions on the hosts in your environment. Contain or lift containment on a host. Delete or restore a host.

PEP8 method name

perform_action

Endpoint

Method	Route
	/devices/entities/devices-actions/v2

Required Scope

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
action_name			query	string	Specify one of these actions: contain: This action contains the host, which stops any network communications to locations other than the CrowdStrike cloud and IPs specified in your containment policy detection_suppress: Supress detections for the host. detection_unsuppress: Allow detections for the host. lift_containment: This action lifts containment on the host, which returns its network communications to normal hide_host: This action will delete a host. After the host is deleted, no new detections for that host will be reported via UI or APIs unhide_host: This action will restore a host. Detection reporting will resume after the host is restored
body			body	dictionary	The host agent ID (AID) of the host you want to impact. Get an agent ID from a detection, the Falcon console, or the Streaming API. Provide the ID in JSON format with the key ids and the value in square brackets, such as: "ids": ["123456789"]
ids			body	string or list of strings	The host agent ID (AID) of the host you want to impact. If you provide IDs to the method using this keyword, you do not have to provide a body payload. (Service class usage only) A maximum of 100 IDs may be provided to this keyword.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

In order to use this method, either a body payload or the ids keyword must be provided.

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.perform_action(action_name="string", ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.PerformActionV2(action_name="string", ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

PARAMS = {
    "action_name": "string"
}

BODY = {
    "ids": [
        "string"
    ]
}

response = falcon.command("PerformActionV2", parameters=PARAMS, body=BODY)
print(response)

# Could also be accomplished using the following syntax
response = falcon.command("PerformActionV2", action_name="string", body=BODY)

print(response)

Back to Table of Contents

entities_perform_action

Performs the specified action on the provided prevention policy IDs.

PEP8 method name

perform_group_action

Endpoint

Method	Route
	/devices/entities/group-actions/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
action_name			query	string	Action to perform: add_group_member remove_all remove_group_member
action_parameters			query	dictionary	Dictionary containing the name and value for the action parameter.
body			body	dictionary	Full body payload in JSON format. Not required if using the action_parameters or keyword.
disable_hostname_check			query	boolean	Flag to indicate that hostnames should not be checked when using the add_group_member action.
ids			body	string or list of strings	Group ID(s) to perform action against.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy.hosts import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

act_params = {
    "name": "string",
    "value": "string"
}

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.perform_group_action(action_name="string",
                                       action_parameters=act_params,
                                       disable_hostname_check=boolean,
                                       ids=id_list
                                       )

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

act_params = {
    "name": "string",
    "value": "string"
}

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.entities_perform_action(action_name="string",
                                          action_parameters=act_params,
                                          disable_hostname_check=boolean,
                                          ids=id_list
                                          )

print(response)

Uber class example

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

BODY = {
    "action_parameters": [
        {
          "name": "string",
          "value": "string"
        }
    ]
}

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("entities_perform_action",
                          action_name="string",
                          body=BODY,
                          disable_hostname_check=boolean,
                          ids=id_list
                          )

print(response)

Back to Table of Contents

QueryDevicesByFilter

Search for hosts in your environment by platform, hostname, IP, and other criteria.

PEP8 method name

query_devices_by_filter

Endpoint

Method	Route
	/devices/queries/devices/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
offset			query	integer	The offset to start retrieving records from
parameters			query	dictionary	Full query string parameters payload in JSON format.
limit			query	integer	The maximum records to return. [1-5000]
sort			query	string	The property to sort by (e.g. status.desc or hostname.asc)
filter			query	string	The filter expression that should be used to limit the results. Review the following table for a complete list of available filters.

Available filters

For more detail regarding filters and their usage, please review the Falcon Query Language documentation.

Name	Type	Operators	Description
device_id	String		The ID of the device. Ex: 061a51ec742c44624a176f079d742052
agent_load_flags	String		CrowdStrike agent configuration notes
agent_version	String		CrowdStrike agent configuration notes
bios_manufacturer	String		Bios manufacture name. Ex: Phoenix Technologies LTD
bios_version	String		Bios version. Ex: 6.00
config_id_base	String		CrowdStrike agent configuration notes
config_id_build	String		CrowdStrike agent configuration notes
config_id_platform	String		CrowdStrike agent configuration notes
cpu_signature	String		The CPU signature of the device. Ex: GenuineIntel
deployment_type	String		Linux deployment type: Standard DaemonSet
external_ip	IP Address		External IP of the device, as seen by CrowdStrike. Ex: 192.0.2.100
first_seen	Timestamp		Timestamp of device’s first connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ"). Ex: 2016-07-19T11:14:15Z
hostname	String		The name of the machine. Supports prefix and suffix searching with wildcard, so you can search for terms like abc and *abc. Ex: WinPC9251
last_login_timestamp	Timestamp		User logon event timestamp, once a week.
last_seen	Timestamp		Timestamp of device’s most recent connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ"). Ex: 2016-07-19T11:14:15Z
linux_sensor_mode	String		Linux sensor mode: Kernel Mode User Mode
local_ip	IP Address		The device's local IP address. As a device management parameter, this is the IP address of this device at the last time it connected to the CrowdStrike Cloud. Ex: 192.0.2.1
local_ip.raw	IP Address with wildcards (*)		A portion of the device's local IP address, used only for searches that include wildcard characters. Using a wildcard requires specific syntax: when you specify an IP address with this parameter, prefix the IP address with an asterisk (*) and enclose the IP address in single quotes. Search for a device with the IP address 192.0.2.100: local_ip.raw:*'192.0.2.*' local_ip.raw:*'*.0.2.100'
mac_address	String		The MAC address of the device Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domain	String		Active Directory domain name.
major_version	String		Major version of the Operating System
minor_version	String		Minor version of the Operating System
modified_timestamp	Timestamp		The last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_version	String		Operating system version. Ex: Windows 7
ou	String		Active Directory organizational unit name.
platform_id	String		CrowdStrike agent configuration notes
platform_name	String		Operating system platform. Available options: Windows Mac Linux
product_type_desc	String		Name of product type.
reduced_functionality_mode	String		Reduced functionality mode (RFM) status: yes no Unknown (displayed as a blank string) Unknown is used for hosts with an unavailable RFM status: The sensor was deployed less than 24 hours ago and has not yet provided an RFM status. The sensor version does not support RFM.
release_group	String		Name of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_number	String		Serial number of the device. Ex: C42AFKEBM563
site_name	String		Active Directory site name.
status	String		Containment Status of the machine. "Normal" denotes good operations; other values might mean reduced functionality or support. Possible values: normal containment_pending contained lift_containment_pending
system_manufacturer	String		Name of system manufacturer Ex: VMware, Inc.
system_product_name	String		Name of system product Ex: VMware Virtual Platform
tags	String		Falcon grouping tags

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.query_devices_by_filter(offset=integer,
                                          limit=integer,
                                          sort="string",
                                          filter="string"
                                          )

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.QueryDevicesByFilter(offset=integer,
                                       limit=integer,
                                       sort="string",
                                       filter="string"
                                       )

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("QueryDevicesByFilter",
                          offset=integer,
                          limit=integer,
                          sort="string",
                          filter="string"
                          )

print(response)

Back to Table of Contents

QueryDevicesByFilterScroll

Search for hosts in your environment by platform, hostname, IP, and other criteria with continuous pagination capability (based on offset pointer which expires after 2 minutes with no maximum limit)

PEP8 method name

query_devices_by_filter_scroll

Endpoint

Method	Route
	/devices/queries/devices-scroll/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
offset			query	string	The offset to page from, for the next result set
parameters			query	dictionary	Full query string parameters payload in JSON format.
limit			query	integer	The maximum records to return. [1-10000]
sort			query	string	The property to sort by (e.g. status.desc or hostname.asc)
filter			query	string	The filter expression that should be used to limit the results. Review the following table for a complete list of available filters.

Available filters

For more detail regarding filters and their usage, please review the Falcon Query Language documentation.

Name	Type	Operators	Description
device_id	String		The ID of the device. Ex: 061a51ec742c44624a176f079d742052
agent_load_flags	String		CrowdStrike agent configuration notes
agent_version	String		CrowdStrike agent configuration notes
bios_manufacturer	String		Bios manufacture name. Ex: Phoenix Technologies LTD
bios_version	String		Bios version. Ex: 6.00
config_id_base	String		CrowdStrike agent configuration notes
config_id_build	String		CrowdStrike agent configuration notes
config_id_platform	String		CrowdStrike agent configuration notes
cpu_signature	String		The CPU signature of the device. Ex: GenuineIntel
deployment_type	String		Linux deployment type: Standard DaemonSet
external_ip	IP Address		External IP of the device, as seen by CrowdStrike. Ex: 192.0.2.100
first_seen	Timestamp		Timestamp of device’s first connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ"). Ex: 2016-07-19T11:14:15Z
hostname	String		The name of the machine. Supports prefix and suffix searching with wildcard, so you can search for terms like abc and *abc. Ex: WinPC9251
last_login_timestamp	Timestamp		User logon event timestamp, once a week.
last_seen	Timestamp		Timestamp of device’s most recent connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ"). Ex: 2016-07-19T11:14:15Z
linux_sensor_mode	String		Linux sensor mode: Kernel Mode User Mode
local_ip	IP Address		The device's local IP address. As a device management parameter, this is the IP address of this device at the last time it connected to the CrowdStrike Cloud. Ex: 192.0.2.1
local_ip.raw	IP Address with wildcards (*)		A portion of the device's local IP address, used only for searches that include wildcard characters. Using a wildcard requires specific syntax: when you specify an IP address with this parameter, prefix the IP address with an asterisk (*) and enclose the IP address in single quotes. Search for a device with the IP address 192.0.2.100: local_ip.raw:*'192.0.2.*' local_ip.raw:*'*.0.2.100'
mac_address	String		The MAC address of the device Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domain	String		Active Directory domain name.
major_version	String		Major version of the Operating System
minor_version	String		Minor version of the Operating System
modified_timestamp	Timestamp		The last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_version	String		Operating system version. Ex: Windows 7
ou	String		Active Directory organizational unit name.
platform_id	String		CrowdStrike agent configuration notes
platform_name	String		Operating system platform. Available options: Windows Mac Linux
product_type_desc	String		Name of product type.
reduced_functionality_mode	String		Reduced functionality mode (RFM) status: yes no Unknown (displayed as a blank string) Unknown is used for hosts with an unavailable RFM status: The sensor was deployed less than 24 hours ago and has not yet provided an RFM status. The sensor version does not support RFM.
release_group	String		Name of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_number	String		Serial number of the device. Ex: C42AFKEBM563
site_name	String		Active Directory site name.
status	String		Containment Status of the machine. "Normal" denotes good operations; other values might mean reduced functionality or support. Possible values: normal containment_pending contained lift_containment_pending
system_manufacturer	String		Name of system manufacturer Ex: VMware, Inc.
system_product_name	String		Name of system product Ex: VMware Virtual Platform
tags	String		Falcon grouping tags

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.query_devices_by_filter_scroll(offset="string",
                                                 limit=integer,
                                                 sort="string",
                                                 filter="string"
                                                 )

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.QueryDevicesByFilterScroll(offset="string",
                                             limit=integer,
                                             sort="string",
                                             filter="string"
                                             )

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("QueryDevicesByFilterScroll",
                          offset="string",
                          limit=integer,
                          sort="string",
                          filter="string"
                          )

print(response)

Back to Table of Contents

QueryDeviceLoginHistoryV1

Retrieve details about recent login sessions for a set of devices.

PEP8 method name

query_device_login_history_v1 (or query_device_login_history)

Endpoint

Method	Route
	/devices/combined/devices/login-history/v1

Required Scope

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	The host agent ID (AID) of the host you want to query. Get an agent ID from a detection, the Falcon console, or the Streaming API. Provide the ID in JSON format with the key ids and the value in square brackets, such as: "ids": ["123456789"]
ids			body	string or list of strings	The host agent ID (AID) of the host you want to query. If you provide IDs to the method using this keyword, you do not have to provide a body payload.

Usage

In order to use this method, either a body payload or the ids keyword must be provided.

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.query_device_login_history(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.QueryDeviceLoginHistory(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("QueryDeviceLoginHistory", ids=id_list)

print(response)

Back to Table of Contents

QueryDeviceLoginHistoryV2

Retrieve details about recent login sessions for a set of devices.

PEP8 method name

query_device_login_history_v2

Endpoint

Method	Route
	/devices/combined/devices/login-history/v2

Required Scope

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	The host agent ID (AID) of the host you want to query. Get an agent ID from a detection, the Falcon console, or the Streaming API. Provide the ID in JSON format with the key ids and the value in square brackets, such as: "ids": ["123456789"]
ids			body	string or list of strings	The host agent ID (AID) of the host you want to query. If you provide IDs to the method using this keyword, you do not have to provide a body payload.

Usage

In order to use this method, either a body payload or the ids keyword must be provided.

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.query_device_login_history_v2(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.QueryDeviceLoginHistoryV2(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("QueryDeviceLoginHistoryV2", ids=id_list)

print(response)

Back to Table of Contents

QueryGetNetworkAddressHistoryV1

Retrieve history of IP and MAC addresses of devices.

PEP8 method name

query_network_address_history

Endpoint

Method	Route
	/devices/combined/devices/network-address-history/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	The host agent ID (AID) of the host you want to query. Get an agent ID from a detection, the Falcon console, or the Streaming API. Provide the ID in JSON format with the key ids and the value in square brackets, such as: "ids": ["123456789"]
ids			body	string or list of strings	The host agent ID (AID) of the host you want to query. If you provide IDs to the method using this keyword, you do not have to provide a body payload. (Service class usage only)

Usage

In order to use this method, either a body payload or the ids keyword must be provided.

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.query_network_address_history(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.QueryGetNetworkAddressHistoryV1(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

BODY = {
  "ids": [
    "string"
  ]
}

response = falcon.command("QueryGetNetworkAddressHistoryV1", body=BODY)

print(response)

Back to Table of Contents

GetOnlineState_V1

Get the online status for one or more hosts by specifying each host’s unique ID.

PEP8 method name

get_online_state

Endpoint

Method	Route
	/devices/entities/online-state/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	The host AIDs used to retrieve state details for.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_online_state(ids=id_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetOnlineState_V1(ids=id_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("GetOnlineState_V1", ids=id_list)

print(response)

Back to Table of Contents

QueryHiddenDevices

Retrieve hidden hosts that match the provided filter criteria.

PEP8 method name

query_hidden_devices

Endpoint

Method	Route
	/devices/queries/devices-hidden/v1

Required Scope

Content-Type

• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
offset			query	integer	The offset to start retrieving records from
parameters			query	dictionary	Full query string parameters payload in JSON format.
limit			query	integer	The maximum records to return. [1-5000]
sort			query	string	The property to sort by (e.g. status.desc or hostname.asc)
filter			query	string	The filter expression that should be used to limit the results

Usage

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.query_hidden_devices(offset=integer,
                                       limit=integer,
                                       sort="string",
                                       filter="string"
                                       )

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

response = falcon.QueryHiddenDevices(offset=integer,
                                     limit=integer,
                                     sort="string",
                                     filter="string"
                                     )

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("QueryHiddenDevices",
                          offset=integer,
                          limit=integer,
                          sort="string",
                          filter="string"
                          )

print(response)

Back to Table of Contents

UpdateDeviceTags

Append or remove one or more Falcon Grouping Tags on one or more hosts.

PEP8 method name

update_device_tags

Endpoint

Method	Route
	/devices/entities/devices/tags/v1

Required Scope

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	dictionary	Full body payload containing all parameters in JSON format.
action_name			body	string	The action to perform. (add or remove). Service class only
ids			body	string or list of strings	The AID of the host(s) to update. Service class only
tags			body	string or list of strings	The tags to adjust on the host. Service class only

Usage

This operation only supports the Uber class providing body payloads directly. When using the Hosts Service Class, you specify the necessary parameters for this operation as required keywords.

Service class example (PEP8 syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']
tag_list = 'TAG1,TAG2,TAG3'  # Can also pass a list here: ['TAG1', 'TAG2', 'TAG3']

response = falcon.update_device_tags(action_name="string", ids=id_list, tags=tag_list)

print(response)

Service class example (Operation ID syntax)

from falconpy import Hosts

# Do not hardcode API credentials!
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']
tag_list = 'TAG1,TAG2,TAG3'  # Can also pass a list here: ['TAG1', 'TAG2', 'TAG3']

response = falcon.UpdateDeviceTags(action_name="string", ids=id_list, tags=tag_list)

print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

BODY = {
  "action": "string",
  "device_ids": [
    "string"
  ],
  "tags": [
    "string"
  ]
}

response = falcon.command("UpdateDeviceTags", body=BODY)

print(response)

Back to Table of Contents