Query API

This API requests scheduling a query and returns an object that provides information needed to collect the results.

Note: Orbital will retain the results of all queries for a minimum of 48 hours.

Scheduled queries can have a duration assigned to them specify how long the query will run for. If one or more nodes come online after the query has started running, the results for those new nodes will be created when the nodes connect. A more detailed description of Scheduled Queries can be found at Scheduled Queries.

Live queries, however, behave differently. Live queries run immediately and return information from only those nodes that are connected at the time the query is run. See the Results API for how to retrieve a query’s results. A more detailed description of Live Queries can be found at Live Queries.

Note: Live Queries are also known as probes.

Request Parameters

Orbital accepts the following parameters when creating a query.

The interval is an api analog of the Run Once function, located on the Scheduled Queries form of the User Interface. Refer to the Scheduled Query popup’s Run Once function section for more information.

osquery Objects in Queries

Orbital supports sending a list of arbitrary osquery statements to Orbital nodes for evaluation in the osQuery query parameter. You can give these statements a label, which will be used in the results object to distinguish tables of results. This is a good practice when you combine multiple statements in a single Orbital Query.

[{
  "label": "list_applications",
  "name": "List Applications",
  "sql": "SELECT * FROM applications;"
}]

Postback Objects in Queries

A Postback specifies either an existing Webhook ID or an URL where results for the specified scheduled query will be sent. The remote data store must be able to respond with a 200 to a POST at the time of the query request, in order for the request to get scheduled.

Postback Fields

Specifying Nodes as Subjects of Queries

Orbital supports a number of different methods for specifying the nodes to query. Any or all of the following prefixes may be combined when creating a query and any nodes that match the specified prefix or prefixes will run the query. With the exception of the all, random, netmask, and wildcard prefixes, any prefixes listed in the table below can be used on the Endpoints page to search for nodes.

A Number of Prefixes are Also Available to Identify Nodes by Specific Properties

Prefix Auto-Detectable Allowed Values Case Sensitive Allows Wildcard Example Description
allowOS No windows, linux, darwin No No "allowOS:darwin" Only nodes with one of the specified OSes are allowed from the set of nodes otherwise specified.
amp Yes GUID format Yes No "amp:348301bf-2082-4d83-b340-e6ab2e58579c" A Secure Endpoint Computer GUID
ampuuid Yes GUID format Yes No "ampuuid:348301bf-2082-4d83-b340-e6ab2e58579c" A Secure Endpoint Computer GUID
anyconnectudid No n/a Yes No "anyconnectudid:163F665789D42AA0EB883A023D67D8CE391DF362" The AnyConnect UDID (supported as of node version 1.17 or higher)
host No n/a No Yes "host:DESKTOP-XYZ" A host name.
hostname No n/a No Yes "hostname:WOPR" A host name.
hwaddr Yes MAC format No Yes "hwaddr:02:42:c8:1f:7d:fa" A MAC address
ip Yes IPv4 or IPv6 format n/a Yes* "ip:10.0.0.1" A network ipv4 or ipv6 address. When wildcard is used, only matches IPv4.
ip4 Yes IPv4 format n/a Yes "ip4:10.0.0.1" A network ipv4 address
ipv4 Yes IPv4 format n/a Yes "ipv4:10.0.0.1" A network ipv4 address
ip6 Yes IPv6 format n/a Yes "ip6:fe80::3926:f1ac:d0cf:d1d7" A network ipv6 address
ipv6 Yes IPv6 format n/a Yes "ip6:fe80::3926:f1ac:d0cf:d1d7" A network ipv6 address
mac Yes MAC format No Yes "mac:02:42:c8:1f:7d:fa" A MAC address
machine No n/a Yes No “machine:48469d02bacd44eba481a1a3f0020ea1” The unique machine identifier (supported as of node version 1.17 or higher). See details below.
netmask Yes CIDR Notation n/a No "netmask:192.168.1.168/24" A network ipv4 address with trailing netmask bit count
nodeversion No An existing node version. n/a No "nodeversion:1.12.6" An Orbital node version in either {major}.{minor} format or {major}.{minor}.{patch} format. *Using {major}.{minor} will match all patch versions for the given parameters.
orb Yes n/a Yes No "orb:oLPkT67m4nj-QpdGDPNCmQ" An Orbital ID
orbital Yes n/a Yes No "orbital:oLPkT67m4nj-QpdGDPNCmQ" An Orbital ID
os No windows, linux, darwin No No "os:windows" Every node with the given OS.
osqueryversion No An existing osquery version. n/a No "osqueryversion:4.4.0" An Osquery version in either {major}.{minor} format or {major}.{minor}.{patch} format. *Using {major}.{minor} will match all patch versions for the given parameters.
random No Numbers > 0 n/a No "random:5" The specified number of random endpoints.
queryId No Any valid Orbital Query ID Yes No "queryId:zfmCLhXjFO6aIvV3frhg_w" queryId links the new query to an existing query. Refer to Linked Queries for more information.

Other wildcard examples:

If you specify the prefix all in the nodes list, Orbital will query all of the nodes in your organization. This can be very useful in general threat hunting and data collecting queries; however, using the all prefix may return results for an extremely large number of nodes, depending on the size of your organization. Because of this, you may wish to narrow the results returned by the query by using one of the other prefixes, such as the os prefix. The os prefix allows you to specify the operating system the query will run on. For example, if you specify the Linux operating system, your query will only run against those endpoints that are running Linux nodes. For more information on prefixes, refer to the Prefix Table above.

Machine Identifier

The machine prefix returns a unique identifier.

Query API Limits

The following values represent the maximum and minimum limits for six (6) Query API parameters.

The None of the specified nodes were found Error Message

This error message may cause some confusion if it is displayed. Orbital users are told that they are able to search across nodes that are not currently online, but will be searched when the node or nodes come back online. In spite of this, the error message, None of the specified nodes were found. may be displayed. The reason for this is straightforward, Orbital has not registered the node yet and is; therefore, unaware that it exists. Also, if you are querying across multiple nodes and none of the nodes being queried are known, the error message will be displayed.

For example, if the node host-1312-win-MB has been exposed to Orbital in the last 90 days, Orbital will wait for it to come back online and then search across it. However, if a new node named host-1701-thom-MB has not been exposed to Orbital and is included in the query, Orbital will display the None of the specified nodes were found., as Orbital does not yet know about the node.

Note: It is important to understand that this error message will not be displayed if at least one node being queried is known.

Example 1: Getting a List of Processes From the Front Desk

The body of any Orbital API request must be formatted in JSON format and must be accompanied by a bearer authorization header containing an access token. See Orbital API Authentication for more information on authentication.

Scheduled Query Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  nodes:='["host:FRONT-DESK-123"]'

Live Query or Probe Example

http https://$service/v0/probe \
     "Authorization:Bearer $token" \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  nodes:='["host:FRONT-DESK-123"]'

Example 2: A Non-Stock Query

This example shows the format of all the fields except postback, stock and stockargs, running on a couple explicit nodes plus all Windows nodes.

Scheduled Query Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123", "ip:1.2.3.4"]' \
  expiry:=1688974114 \
  interval:=600 \
  os:='["windows"]' \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  context:='{"description":"front desk", "value":"anything"}'

Live Query or Probe Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123", "ip:1.2.3.4"]' \
  expiry:=1688974114 \
  os:='["windows"]' \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  context:='{"description":"front desk", "value":"anything"}'

Example 3: A Stock Query

This example shows the format of all the fields except postback and osquery, running on a couple explicit nodes plus all Windows nodes. It’s using the stock query with id arp_cache_inspection and query parameters ip_to_mac_count, ip_address, and mac_address.

Scheduled Query Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123", "ip:1.2.3.4"]' \
  expiry:=1688974114 \
  interval:=600 \
  os:='["windows"]' \
  stock='arp_cache_inspection' \
  stockArgs:='{"ip_to_mac_count":["2"], "ip_address":["%"], "mac_address":["%"]}' \
  context:='{"description":"front desk", "value":"anything"}'

Live Query or Probe Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123", "ip:1.2.3.4"]' \
  expiry:=1688974114 \
  os:='["windows"]' \
  stock='arp_cache_inspection' \
  stockArgs:='{"ip_to_mac_count":["2"], "ip_address":["%"], "mac_address":["%"]}' \
  context:='{"description":"front desk", "value":"anything"}'

Example 4: A Postback, Using an Existing Webhook

This example shows the format of all the fields except stock and stockargs, running on an explicit node, and using a predefined Webhook object as a remote data store.

Scheduled Query Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123"]' \
  expiry:=1688974114 \
  interval:=600 \
  os:='["windows"]' \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  context:='{"description":"front desk", "value":"anything"}' \
  postback:='{"webhookid":"65CLM4Jnns8uXa9bbBKksA"}'

Live Query or Probe Example

Live queries (probes) do not provide postback, so there is no example that can be provided.

Example 5: A Postback, Using an Ad Hoc Webhook

This example shows the format of all the fields except stock and stockargs, running on an explicit node, and using an ad hoc postback to define the remote data store.

Scheduled Query Example

http https://$service/v0/query \
     "Authorization:Bearer $token" \
  name='My Custom Query' \
  nodes:='["host:FRONT-DESK-123"]' \
  expiry:=1688974114 \
  interval:=600 \
  os:='["windows"]' \
  osQuery:='[{"sql": "SELECT * FROM processes;"}]' \
  context:='{"description":"front desk", "value":"anything"}' \
  postback:='{"url":"https://mywebserver.com","format":"expanded","fingerprint":"C728DF57BE22F0B2391DD3F7C402063F7E3241B50EB758755B96FBADAAA7A361"}'

Live Query or Probe Example

Live queries (probes) do not provide postback, so there is no example that can be provided.

Return to Table of Contents