CrowdStrike Falcon CrowdStrike Subreddit

Using the Hosts service collection

Uber class support Service class support Documentation Version Page Updated Samples Available

This service collection has code examples posted to the repository.

Table of Contents

Operation IDDescription
GetDeviceDetails Redirect Recommended
PEP 8get_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 Deprecated
PEP 8get_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 8get_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 8post_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 8perform_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
PEP8perform_group_action
Performs the specified action on the provided prevention policy IDs.
QueryDevicesByFilter
PEP 8query_devices_by_filter
Search for hosts in your environment by platform, hostname, IP, and other criteria.
QueryDevicesByFilterScroll
PEP 8query_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 8query_device_login_history
Retrieve details about recent login sessions for a set of devices.
QueryDeviceLoginHistoryV2
PEP 8query_device_login_history_v2
Retrieve details about recent login sessions for a set of devices.
QueryGetNetworkAddressHistoryV1
PEP 8query_network_address_history
Retrieve history of IP and MAC addresses of devices.
GetOnlineState_V1
PEP 8get_online_state
Get the online status for one or more hosts by specifying each host’s unique ID.
QueryHiddenDevices
PEP 8query_hidden_devices
Retrieve hidden hosts that match the provided filter criteria.
UpdateDeviceTags
PEP 8update_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

MethodRoute
POST/devices/entities/devices/v2

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
ids
Service Class Support

Uber Class Support
bodystring or list of stringsThe host agent IDs used to get details on.
Maximum: 5000.
parameters
Service Class Support

Uber Class Support
query
(will be converted to body)
dictionaryFull 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

MethodRoute
GET/devices/entities/devices/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsThe host agent IDs used to get details on.
Maximum: 500
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/devices/entities/devices/v2

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsThe host agent IDs used to get details on.
Maximum: 100
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
POST/devices/entities/devices/v2

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
ids
Service Class Support

Uber Class Support
bodystring or list of stringsThe 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

MethodRoute
POST/devices/entities/devices-actions/v2

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
action_name
Service Class Support

Uber Class Support
querystringSpecify 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
Service Class Support

Uber Class Support
bodydictionaryThe 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
Service Class Support

No Uber Class Support
bodystring or list of stringsThe 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)
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
POST/devices/entities/group-actions/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
action_name
Service Class Support

Uber Class Support
querystringAction to perform:
  • add_group_member
  • remove_all
  • remove_group_member
action_parameters
Service Class Support

Uber Class Support
querydictionaryDictionary containing the name and value for the action parameter.
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format. Not required if using the action_parameters or keyword.
disable_hostname_check
Service Class Support

Uber Class Support
querybooleanFlag to indicate that hostnames should not be checked when using the add_group_member action.
ids
Service Class Support

No Uber Class Support
bodystring or list of stringsGroup ID(s) to perform action against.
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/devices/queries/devices/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
offset
Service Class Support

Uber Class Support
queryintegerThe offset to start retrieving records from
parameters
Service Class Support

Uber Class Support
querydictionaryFull query string parameters payload in JSON format.
limit
Service Class Support

Uber Class Support
queryintegerThe maximum records to return. [1-5000]
sort
Service Class Support

Uber Class Support
querystringThe property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support

Uber Class Support
querystringThe 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.

NameTypeOperatorsDescription
device_idStringNoThe ID of the device.

Ex: 061a51ec742c44624a176f079d742052
agent_load_flagsStringNoCrowdStrike agent configuration notes
agent_versionStringNoCrowdStrike agent configuration notes
bios_manufacturerStringNoBios manufacture name.

Ex: Phoenix Technologies LTD
bios_versionStringNoBios version.

Ex: 6.00
config_id_baseStringNoCrowdStrike agent configuration notes
config_id_buildStringNoCrowdStrike agent configuration notes
config_id_platformStringNoCrowdStrike agent configuration notes
cpu_signatureStringYesThe CPU signature of the device.

Ex: GenuineIntel
deployment_typeStringYesLinux deployment type:
  • Standard
  • DaemonSet
external_ipIP AddressYesExternal IP of the device, as seen by CrowdStrike.

Ex: 192.0.2.100
first_seenTimestampYesTimestamp of device’s first connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ").

Ex: 2016-07-19T11:14:15Z
hostnameStringNoThe 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_timestampTimestampYesUser logon event timestamp, once a week.
last_seenTimestampYesTimestamp 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_modeStringYesLinux sensor mode:
  • Kernel Mode
  • User Mode
local_ipIP AddressNoThe 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.rawIP Address with wildcards (*)NoA 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_addressStringNoThe MAC address of the device

Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domainStringNoActive Directory domain name.
major_versionStringNoMajor version of the Operating System
minor_versionStringNoMinor version of the Operating System
modified_timestampTimestampYesThe last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_versionStringNoOperating system version.

Ex: Windows 7
ouStringNoActive Directory organizational unit name.
platform_idStringNoCrowdStrike agent configuration notes
platform_nameStringNoOperating system platform.

Available options:
  • Windows
  • Mac
  • Linux
product_type_descStringNoName of product type.
reduced_functionality_modeStringYesReduced 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_groupStringNoName of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_numberStringYesSerial number of the device.

Ex: C42AFKEBM563
site_nameStringNoActive Directory site name.
statusStringNoContainment 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_manufacturerStringNoName of system manufacturer

Ex: VMware, Inc.
system_product_nameStringNoName of system product

Ex: VMware Virtual Platform
tagsStringNoFalcon 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

MethodRoute
GET/devices/queries/devices-scroll/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
offset
Service Class Support

Uber Class Support
querystringThe offset to page from, for the next result set
parameters
Service Class Support

Uber Class Support
querydictionaryFull query string parameters payload in JSON format.
limit
Service Class Support

Uber Class Support
queryintegerThe maximum records to return. [1-5000]
sort
Service Class Support

Uber Class Support
querystringThe property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support

Uber Class Support
querystringThe 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.

NameTypeOperatorsDescription
device_idStringNoThe ID of the device.

Ex: 061a51ec742c44624a176f079d742052
agent_load_flagsStringNoCrowdStrike agent configuration notes
agent_versionStringNoCrowdStrike agent configuration notes
bios_manufacturerStringNoBios manufacture name.

Ex: Phoenix Technologies LTD
bios_versionStringNoBios version.

Ex: 6.00
config_id_baseStringNoCrowdStrike agent configuration notes
config_id_buildStringNoCrowdStrike agent configuration notes
config_id_platformStringNoCrowdStrike agent configuration notes
cpu_signatureStringYesThe CPU signature of the device.

Ex: GenuineIntel
deployment_typeStringYesLinux deployment type:
  • Standard
  • DaemonSet
external_ipIP AddressYesExternal IP of the device, as seen by CrowdStrike.

Ex: 192.0.2.100
first_seenTimestampYesTimestamp of device’s first connection to Falcon, in UTC date format ("YYYY-MM-DDTHH:MM:SSZ").

Ex: 2016-07-19T11:14:15Z
hostnameStringNoThe 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_timestampTimestampYesUser logon event timestamp, once a week.
last_seenTimestampYesTimestamp 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_modeStringYesLinux sensor mode:
  • Kernel Mode
  • User Mode
local_ipIP AddressNoThe 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.rawIP Address with wildcards (*)NoA 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_addressStringNoThe MAC address of the device

Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domainStringNoActive Directory domain name.
major_versionStringNoMajor version of the Operating System
minor_versionStringNoMinor version of the Operating System
modified_timestampTimestampYesThe last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_versionStringNoOperating system version.

Ex: Windows 7
ouStringNoActive Directory organizational unit name.
platform_idStringNoCrowdStrike agent configuration notes
platform_nameStringNoOperating system platform.

Available options:
  • Windows
  • Mac
  • Linux
product_type_descStringNoName of product type.
reduced_functionality_modeStringYesReduced 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_groupStringNoName of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_numberStringYesSerial number of the device.

Ex: C42AFKEBM563
site_nameStringNoActive Directory site name.
statusStringNoContainment 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_manufacturerStringNoName of system manufacturer

Ex: VMware, Inc.
system_product_nameStringNoName of system product

Ex: VMware Virtual Platform
tagsStringNoFalcon 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

MethodRoute
POST/devices/combined/devices/login-history/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support
Uber Class Required
bodystringThe 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
Service Class Support

No Uber Class Support
bodystring or list of stringsThe 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

MethodRoute
POST/devices/combined/devices/login-history/v2

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support
Uber Class Required
bodystringThe 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
Service Class Support

No Uber Class Support
bodystring or list of stringsThe 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

MethodRoute
POST/devices/combined/devices/network-address-history/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Required
bodystringThe 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
Service Class Support

No Uber Class Support
bodystring or list of stringsThe 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

MethodRoute
GET/devices/entities/online-state/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsThe host AIDs used to retrieve state details for.
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/devices/queries/devices-hidden/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
offset
Service Class Support

Uber Class Support
queryintegerThe offset to start retrieving records from
parameters
Service Class Support

Uber Class Support
querydictionaryFull query string parameters payload in JSON format.
limit
Service Class Support

Uber Class Support
queryintegerThe maximum records to return. [1-5000]
sort
Service Class Support

Uber Class Support
querystringThe property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support

Uber Class Support
querystringThe 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

MethodRoute
PATCH/devices/entities/devices/tags/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Unsupported

Required
bodydictionaryFull body payload containing all parameters in JSON format.
action_name
Supported

Unsupported
bodystringThe action to perform. (add or remove).
Service class only
ids
Supported

Unsupported
bodystring or list of stringsThe AID of the host(s) to update.
Service class only
tags
Supported

Unsupported
bodystring or list of stringsThe 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