Orbital Nodes

Orbital nodes are software services that are installed on endpoints (computer hardware) to aid in the collection of system information used when searching for system and network threats.

Support Policy for Orbital Node Versions

In order for Orbital to be able to detect the latest system threats, Orbital nodes must be updated on a regular basis. To accommodate this need, Cisco has enabled a scheduled, automated update system that will install the latest version of the node when the it becomes available.

However, this may conflict with an organization’s own schedule, so customers have been given a certain level of control over when Orbital will install the latest node. This comes in the form of allowing the customer to define an update window.

Allowing the customer to choose when an update is installed introduces the possibility of running nodes that are out-of-date and, therefore, unsupported. Nodes that are out-of-date will most likely not have the latest features or support for the tables necessary to provide the full scope of information.

In order to support allowing the customer to define when nodes can be updated, Cisco has adopted a node version support policy where they will support the current version and one previous minor version; Cisco version numbering takes the format {major}.{minor}.{patch}.

Note: Patch releases are not considered to be a new node version and are not taken into consideration by this node version support policy.

This node version support policy has been implemented in Orbital through the definition of three version categories, Supported, Unsupported, and Rejected.

Supported nodes are those nodes that are up-to-date or are only one version behind the current node version. These nodes are allowed to connect to the Orbital service and are identified by a green icon, a circle with a checkmark in it (Supported Icon), and by green text.

Unsupported nodes are those nodes that are two or more versions behind the current version (current version and one version older than the current version). These nodes are still allowed to connect to the Orbital service and can be queried by Orbital, however, they should be updated as soon as possible. These nodes are identified by a yellow icon, a triangle with an exclamation mark in it (Unsupported Icon), and by yellow text.

Rejected nodes are those nodes that are old enough that they are no longer supported by the Orbital service. These nodes are not allowed to connect to the Orbital service and are identified by a red icon, an octagon with an “x” in it (Rejected Icon), and by red text.

Orbital’s Endpoints page displays the node version status in an information card, similar to the one shown in the figure below.

Node Version Status Information Card

The Orbital Node’s Impact on Network and Endpoint Infrastructure

The impact that Orbital’s nodes have on the endpoints they are installed on and the networks they are connected to will depend on several factors.

The tables that Orbital uses can impact endpoint performance. Tables that collect information, such as running processes, logged in users, and so on, do not have much impact on endpoint processes. Tables that gather information on resources like file systems, and so on, will require more resources to perform their tasks. If performance of one or more endpoints is a concern for a given period of time, it is recommended that simple queries be run.

Query complexity will also affect the performance of the network the endpoint is attached to. If a query must return a large amount of data to Orbital, it will take up more space on the network and, therefore, slow down the network.

It is important to understand that node activity is serialized. This means that only one query is run on an endpoint’s node at any given time, no matter how many queries are queued to run on that node.

Additionally, Orbital, through osquery, can subscribe to operating system events. This allows the node to return information that is current; however, it can also overload the endpoint’s CPU, so tables that record events have been disabled for Windows and macOS.

Orbital Node Version Releases

Nodes for the different operating systems will have staggered releases and will not necessarily have the same version numbers upon release. This means, for example, that the Linux node may have a version number of 1.17, whereas both the Windows and macOS nodes may have the version number 1.14.

The node version numbers are reflected in the Node Version Status tile located on the Endpoints page, as shown below.

Node Version Status Tile

The Supported [version number] field in the figure above shows a value of 1.14+. This listing shows the oldest node version supported, which in our example is 1.14. The plus (+) symbol tells you that nodes that have version numbers greater than the oldest node version are also supported. For example, version 1.15, version 1.16, version 1.17, etc, are supported by Orbital.

Additionally, Orbital, through osquery, can subscribe to operating system events. This allows the node to return information that is current; however, it can also overload the endpoint’s CPU, so tables that record events have been disabled for Windows and macOS.

Python

If you have chosen to make use of Orbital’s Script feature, Python will be installed alongside the Orbital node. This Orbital installation of Python is secure and completely independent of any prior or subsequent Python installations, it is only available to Orbital. Orbital uses Python version 3.10 or later.

Python Libraries Included With Script

The following Python libraries are provided for use with Orbital scripts:

Script Limits

The following limits govern the creation of Orbital scripts:

Script Parameters

Orbital scripts may use any number of named parameters. The parameter values must be typed directly into the script, rather than being passed as an argument or a script variable.

The parameter syntax takes the format {{ .parameter_name }}

For example, if you have the value Wile E. Coyote for the parameter name and the value Genius for the parameter occupation, the raw script will take the form, as follows:

print("Hi, my name is {{ .name }}, and my occupation is {{ .occupation }}.")

The script will first perform the inline substitution, as follows:

print("Hi, my name is Wile E. Coyote, and my occupation is Genius.")

This substitution will return the following output:

Hi, my name is Wile E. Coyote, and my occupation is Genius.

Escaping Special Characters

The following special Python characters are automatically escaped by Orbital: ', ", \. There is no need to consider special handling of these characters when authoring a script.

For example, if the parameter filename has the value "C:\program files\some application\program name.exe", the raw script will take the form:

print("the filename is: {{.filename}}")

The script will first perform the inline substitution, as follows:

print("The filename is: \"C:\\program files\\some application\\program name.exe\"")

This substitution will return the following output:

The filename is: "C:\program files\some application\program name.exe"

Examples of Using Script’s Parameters in Python

Note: It is recommended that you first set Orbital’s Script parameters as Python variables, then use the Python variables instead of the Script parameters.

An example of using a Script parameter as an int input for a Python function is displayed in the figure below:

pid = {{ .orbital_param_pid }}

print("killing pid: %d" % pid)
os.kill(pid, SIGKILL)

An example of using a Script parameter as a string input for a Python function is displayed in the figure below:

Important Note: Quotation marks must fully enclose the Script parameter before it is passed to Python, as it is passed directly inline.

# use quotes to create a python string
filename = "{{ .orbital_param_filename }}"

print("opening file: %s" % filename)
file = open(filename)

Script Parameter Definition Through the Orbital User Interface

When you are writing your script, using the Orbital Interface, make certain you define the parameter values for the script before you save the script to the Catalog. This will inform future users of the values needed to run the script.

For example, if your are creating the following script:

print("hello, my name is {{ .name }} and my occupation is {{ .occupation }}")

Make certain you add the name and occupation parameters to the Parameters field or fields of the Orbital Builder, as shown in the figure below.

Parameter Definition

Defining the names of your script’s parameters can be done using one of two methods.

The first method is to click Get parameters from custom script. This will instruct Orbital’s Builder to review the script and automatically list all of the parameter names it finds. In our example, it will find the parameter names name and occupation.

The second method is to click on the + Add parameter. This will create a new, empty parameter name/value row, which you will use to enter one of the parameter names in your script. Repeat this action until all of the parameters in your script have been listed.

Refer to the Builder section of the Investigate topic for more information on this feature.

Script Exit Codes

Script exit codes are the vehicle by which the Orbital node informs Orbital how a given executing Python script has completed, whether it was successful or not.

Scripts return an exit code using the sys.exit() function. A zero (0) will be returned if the script completed successfully. A non-zero exit code will be returned if the script failed, producing an error. For example:

fname = "some_file"
try:
  f = open(fname, 'rb')
  # use the file
  sys.exit(0) # success

except OSError:
  print("Could not open/read file:", fname)
  sys.exit(1) # non-zero - error

Note: If a script fails, it will be identified as returning an error in the results listing, similar to the one shown in the figure below.

Script Failed Results

Special Orbital Exit Codes

Customers can make use of exit codes that range from zero (0) to 199. Exit codes 200 and greater are reserved for Orbital internal use only and should not be used in customer scripts.

Code Description
0 Script Successfully Executed
1 - 199 Available to Customer Scripts
200 Script Timed Out
201 Orbital Error
202 Python Execution Error
203 Script Exception Occurred
204 Script Failed to Run
205 Script Feature Not Enabled
206 Python Missing from Node
207 Node Feature Update In Progress or OS Mismatch

Using stderr In Scripts

In those instances where the script returns non-fatal errors or warning conditions, you are encouraged to write them to stderr.

For example:

fname = "some_file"
try:
  f = open(fname, 'rb')
  # use the file
  sys.exit(0) # success

except OSError:
  print("warning - could not open/read file", file=sys.stderr)
  # continue...
  sys.exit(0) # still success

Return to Table of Contents