Orbital App

Use the Query tab in the Orbital app to construct and execute live, ad-hoc queries on endpoints to gather more information from them. For more information about running queries in Orbital, see the Orbital Queries help topic in Orbital.

1. Endpoints - The first step is to enter the ID of one or more endpoints in your organization that will be queried for information. There are several ways to do this:

   • Click Get endpoints to extract the observables on the page as endpoints to query. This will extract RFC1918 IPV4 addresses, and if a web page uses specific HTML attributes it will include hostnames, Connector GUIDs or Orbital IDs. Observables are extracted from raw unformatted text in the web page.

   • You can also enter the ID of one or more endpoints in your organization that will be queried for information. Separate each ID with a comma and a space.

   • Alternatively, click the (Add Random Endpoints) icon to add multiple random endpoints:

     • On the Add Random Endpoints dialog, specify the number of endpoints in the Number field (default is 10) and check the check box of the operating system you want to limit the query in the OS area (for example, choose Windows to limit the query to that OS).
     • Click Add to insert the endpoints into the Endpoints field.

   • Click the (Operating System Filter) icon to narrow the endpoints to a specific operating system.

   • Click the (Link Queries) icon to use the node list from one or more existing queries as the node list or lists for a new query, provided that the existing query or queries return results that are not empty. For more information, see the Using Linked Queries help topic in Orbital.

   • Click the (Clear Endpoints) icon to remove all the IDs from the Endpoints field or click the (Copy) icon to copy all the IDs in the Endpoints field to your clipboard.

2. Search Query Catalog - Next, select an existing query from the catalog.

   • Click the Search Catalog field to search for and choose a catalog query from the list. The Orbital query catalog contains a rich collection of pre-defined queries that have been created by the Orbital engineering team and TRE (Threat Research for Endpoint) to help you get started. The query catalog helps you quickly learn the power of Orbital and osquery for threat hunting. A Search field is provided at the top of the list; the query list will automatically adjust to only include the catalog queries that contain the search term(s).
   • Choose a query from the list. The name of the query and the SELECT statement are added to the bottom of the panel. Note that some catalog queries will require additional parameters once they have been added. These queries will display a Parameters field describing the required information.

3. Custom SQL - If you are fluent in writing SQL queries, you can enter a custom SQL SELECT statement in this field instead of choosing a catalog query.

4. Click Live Query to send the query to the specified endpoints. The metrics in the right panel are updated.

   

5. Click View Results to pivot into Orbital and see the results on the Results page for your query. For more information on the Results page, see the Query Results Help topic in Orbital.

Schedule Query

You can schedule your query to run on a regularly scheduled basis and have the results sent to an application or remote data store of your choice. For details, see the Schedule Orbital Queries help topic in Orbital.

1. Create your query following the steps in Run Query.

2. Click Schedule Query. The Schedule Query dialog box opens.

   

   • Query Name - The default name is the date and time. Keep the default or edit as needed to be more meaningful.

   • Schedule - Choose the schedule from the drop-down lists, specifying the job interval and duration. First select the time interval (every) then the duration (for). For example, run the query every 24 hours, for 24 hours will result in 1 job being run in the next 24 hours.

     For example, if you want to run a query once an hour for the next 24 hours, select every 1 hour for 24 hours. If you want to run a query once every 10 minutes for the next hour, select every 10 minutes for 1 hour.

     The number of expected result sets per endpoint is displayed to the right of the Schedule drop-down lists.

   • Run Once - Click the toggle button to tell Orbital to run the query being scheduled only once over the subsequent 24 hours.

   • Remote Data Store - Choose a remote data store from the drop-down list. The remote data store is the location where your saved query results will be sent.

3. Click Schedule. The query is scheduled and listed on the Results page.

Use the Script tab in the Orbital app to create, send, and execute a Python script to one or more endpoints to gather more information from them. For more information on scripts, see the Orbital Scripts help topic in Orbital.

Note: Script is only available to users with an Administrator role and the Script feature must be turned on in Orbital. For details, see the Orbital Scripts help topic in Orbital.

1. Endpoints - The first step is to enter the ID of one or more endpoints in your organization that will have the script run against them. There are several ways to do this:

   • Click Get endpoints to extract the observables on the page as endpoints to run the script against them. This will extract RFC1918 IPV4 addresses, and if a web page uses specific HTML attributes it will include hostnames, Connector GUIDs or Orbital IDs. Observables are extracted from raw unformatted text in the web page.

   • You can also enter the ID of one or more endpoints in your organization that will have the script run against them. Separate each ID with a comma and a space.

   • Alternatively, click the (Add Random Endpoints) icon to add multiple random endpoints:

     • On the Add Random Endpoints dialog, specify the number of endpoints in the Number field (default is 10) and check the check box of the operating system you want to run the script against in the OS area (for example, choose Windows to limit the script to that OS).
     • Click Add to insert the endpoints into the Endpoints field.

   • Click the (Operating System Filter) icon to narrow the endpoints to a specific operating system.

   • Click the (Link Queries) icon to link a script to an existing query. Like queries, linking a script to an existing query will allow the script to use the endpoint list from the query linked to. This means that the linked script will only act on those endpoints that the query identifies as meeting its criteria. For details, see the Linkable Scripts section in the Orbital Scripts help topic in Orbital.

   • Click the (Clear Endpoints) icon to remove all the IDs from the Endpoints field or click the (Copy) icon to copy all the IDs in the Endpoints field to your clipboard.

2. Search Scripts Catalog - Next, select an existing Python script from the catalog.

   • Click the Search Catalog field to search for and choose a catalog script from the list. The Orbital script catalog contains a rich collection of pre-defined scripts that have been created by the Orbital engineering team and TRE (Threat Research for Endpoint) to help you get started. The script catalog helps you quickly learn the power of Orbital for threat hunting. A Search field is provided at the top of the list; the query list will automatically adjust to only include the catalog queries that contain the search term(s).
   • Choose a script from the list. The script name and details are added to the bottom of the panel. Note that some catalog scripts will require additional parameters once they have been added. These scripts will display a Parameters field describing the required information.

3. Custom Script - If you are fluent in writing Python scripts, you can enter a custom Python script in this field instead of choosing a catalog script.

4. Click Run Script to run the script and view the results. The results will be returned in the right panel.

   

5. Click View Results to pivot into Orbital and see the results on the Results page for your script. For more information on the Results page, see the Script Results help topic in Orbital.

Schedule Orbital Scripts

You can schedule your scripts to run on a regularly scheduled basis and have the results sent to an application or remote data store of your choice. For details, see the Schedule Orbital Scripts help topic in Orbital.

1. Create your script following the steps in Run Scripts.

2. Click Schedule Script. The Schedule Script dialog box opens.

   

   • Name - The default name is the date and time. Keep the default or edit as needed to be more meaningful.

   • Schedule - Choose the schedule from the drop-down lists, specifying the job interval and duration. First select the time interval (every) then the duration (for). For example, run the query every 24 hours, for 24 hours will result in 1 job being run in the next 24 hours.

     For example, if you want to run a script once an hour for the next 24 hours, select every 1 hour for 24 hours. If you want to run a script once every 10 minutes for the next hour, select every 10 minutes for 1 hour.

     The number of expected result sets per endpoint is displayed to the right of the Schedule drop-down lists.

   • Run Once - Click the toggle button to tell Orbital to run the script being scheduled only once over the subsequent 24 hours.

   • Remote Data Store - Choose a remote data store from the drop-down list. The remote data store is the location where your saved script results will be sent.

3. Click Schedule. The script is scheduled and listed on the Results page.