Hosts - CrowdStrike/falconpy GitHub Wiki

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 ID Description
GetDeviceDetails Redirect Recommended
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 Deprecated
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
POST /devices/entities/devices/v2

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
ids
Service Class Support
Uber Class Support
 body string or list of strings The host agent IDs used to get details on.
Maximum: 5000.
parameters
Service Class Support
Uber Class Support
 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
GET /devices/entities/devices/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings The host agent IDs used to get details on.
Maximum: 500
parameters
Service Class Support
Uber Class Support
 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
GET /devices/entities/devices/v2

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings The host agent IDs used to get details on.
Maximum: 100
parameters
Service Class Support
Uber Class Support
 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
POST /devices/entities/devices/v2

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
ids
Service Class Support
Uber Class Support
 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
POST /devices/entities/devices-actions/v2

Required Scope

hosts:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
action_name
Service Class Support
Uber Class Support
 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
Service Class Support
Uber Class Support
 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
Service Class Support
No Uber Class Support
 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
Service Class Support
Uber Class Support
 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
POST /devices/entities/group-actions/v1

Required Scope

hosts:write

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
action_name
Service Class Support
Uber Class Support
 query string Action to perform:
  • add_group_member
  • remove_all
  • remove_group_member
action_parameters
Service Class Support
Uber Class Support
 query dictionary Dictionary containing the name and value for the action parameter.
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format. Not required if using the action_parameters or keyword.
disable_hostname_check
Service Class Support
Uber Class Support
 query boolean Flag to indicate that hostnames should not be checked when using the add_group_member action.
ids
Service Class Support
No Uber Class Support
 body string or list of strings Group ID(s) to perform action against.
parameters
Service Class Support
Uber Class Support
 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
GET /devices/queries/devices/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
offset
Service Class Support
Uber Class Support
 query integer The offset to start retrieving records from
parameters
Service Class Support
Uber Class Support
 query dictionary Full query string parameters payload in JSON format.
limit
Service Class Support
Uber Class Support
 query integer The maximum records to return. [1-5000]
sort
Service Class Support
Uber Class Support
 query string The property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support
Uber Class Support
 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 No The ID of the device.

Ex: 061a51ec742c44624a176f079d742052
agent_load_flags String No CrowdStrike agent configuration notes
agent_version String No CrowdStrike agent configuration notes
bios_manufacturer String No Bios manufacture name.

Ex: Phoenix Technologies LTD
bios_version String No Bios version.

Ex: 6.00
config_id_base String No CrowdStrike agent configuration notes
config_id_build String No CrowdStrike agent configuration notes
config_id_platform String No CrowdStrike agent configuration notes
cpu_signature String Yes The CPU signature of the device.

Ex: GenuineIntel
deployment_type String Yes Linux deployment type:
  • Standard
  • DaemonSet
external_ip IP Address Yes External IP of the device, as seen by CrowdStrike.

Ex: 192.0.2.100
first_seen Timestamp Yes 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 No 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 Yes User logon event timestamp, once a week.
last_seen Timestamp Yes 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 Yes Linux sensor mode:
  • Kernel Mode
  • User Mode
local_ip IP Address No 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 (*) No 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 No The MAC address of the device

Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domain String No Active Directory domain name.
major_version String No Major version of the Operating System
minor_version String No Minor version of the Operating System
modified_timestamp Timestamp Yes The last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_version String No Operating system version.

Ex: Windows 7
ou String No Active Directory organizational unit name.
platform_id String No CrowdStrike agent configuration notes
platform_name String No Operating system platform.

Available options:
  • Windows
  • Mac
  • Linux
product_type_desc String No Name of product type.
reduced_functionality_mode String Yes 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 No Name of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_number String Yes Serial number of the device.

Ex: C42AFKEBM563
site_name String No Active Directory site name.
status String No 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 No Name of system manufacturer

Ex: VMware, Inc.
system_product_name String No Name of system product

Ex: VMware Virtual Platform
tags String No 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
GET /devices/queries/devices-scroll/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
offset
Service Class Support
Uber Class Support
 query string The offset to page from, for the next result set
parameters
Service Class Support
Uber Class Support
 query dictionary Full query string parameters payload in JSON format.
limit
Service Class Support
Uber Class Support
 query integer The maximum records to return. [1-10000]
sort
Service Class Support
Uber Class Support
 query string The property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support
Uber Class Support
 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 No The ID of the device.

Ex: 061a51ec742c44624a176f079d742052
agent_load_flags String No CrowdStrike agent configuration notes
agent_version String No CrowdStrike agent configuration notes
bios_manufacturer String No Bios manufacture name.

Ex: Phoenix Technologies LTD
bios_version String No Bios version.

Ex: 6.00
config_id_base String No CrowdStrike agent configuration notes
config_id_build String No CrowdStrike agent configuration notes
config_id_platform String No CrowdStrike agent configuration notes
cpu_signature String Yes The CPU signature of the device.

Ex: GenuineIntel
deployment_type String Yes Linux deployment type:
  • Standard
  • DaemonSet
external_ip IP Address Yes External IP of the device, as seen by CrowdStrike.

Ex: 192.0.2.100
first_seen Timestamp Yes 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 No 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 Yes User logon event timestamp, once a week.
last_seen Timestamp Yes 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 Yes Linux sensor mode:
  • Kernel Mode
  • User Mode
local_ip IP Address No 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 (*) No 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 No The MAC address of the device

Ex: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
machine_domain String No Active Directory domain name.
major_version String No Major version of the Operating System
minor_version String No Minor version of the Operating System
modified_timestamp Timestamp Yes The last time that the machine record was updated. Can include status like containment status changes or configuration group changes.
os_version String No Operating system version.

Ex: Windows 7
ou String No Active Directory organizational unit name.
platform_id String No CrowdStrike agent configuration notes
platform_name String No Operating system platform.

Available options:
  • Windows
  • Mac
  • Linux
product_type_desc String No Name of product type.
reduced_functionality_mode String Yes 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 No Name of the Falcon deployment group, if the this machine is part of a Falcon sensor deployment group.
serial_number String Yes Serial number of the device.

Ex: C42AFKEBM563
site_name String No Active Directory site name.
status String No 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 No Name of system manufacturer

Ex: VMware, Inc.
system_product_name String No Name of system product

Ex: VMware Virtual Platform
tags String No 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
POST /devices/combined/devices/login-history/v1

Required Scope

hosts:read

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
 Uber Class Required
 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
Service Class Support
No Uber Class Support
 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
POST /devices/combined/devices/login-history/v2

Required Scope

hosts:read

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
 Uber Class Required
 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
Service Class Support
No Uber Class Support
 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
POST /devices/combined/devices/network-address-history/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Required
 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
Service Class Support
No Uber Class Support
 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
GET /devices/entities/online-state/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings The host AIDs used to retrieve state details for.
parameters
Service Class Support
Uber Class Support
 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
GET /devices/queries/devices-hidden/v1

Required Scope

hosts:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
offset
Service Class Support
Uber Class Support
 query integer The offset to start retrieving records from
parameters
Service Class Support
Uber Class Support
 query dictionary Full query string parameters payload in JSON format.
limit
Service Class Support
Uber Class Support
 query integer The maximum records to return. [1-5000]
sort
Service Class Support
Uber Class Support
 query string The property to sort by (e.g. status.desc or hostname.asc)
filter
Service Class Support
Uber Class Support
 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
PATCH /devices/entities/devices/tags/v1

Required Scope

hosts:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Unsupported
Required
 body dictionary Full body payload containing all parameters in JSON format.
action_name
Supported
Unsupported
 body string The action to perform. (add or remove).
Service class only
ids
Supported
Unsupported
 body string or list of strings The AID of the host(s) to update.
Service class only
tags
Supported
Unsupported
 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

⚠️ **GitHub.com Fallback** ⚠️