Using Orbital Scripts

Use Orbital’s Investigate page, shown in the figure below, to construct and execute ad hoc scripts on identified endpoints in order to perform threat counteraction measures or gather additional information on them.

There are several avenues you can take to access Orbital’s Investigate page:

• From Secure Endpoint:

  1. Select Computers from the Management menu.

  2. Select the desired endpoint.

  3. Expand the endpoint listing.

  4. Click Orbital.

     Orbital opens on the Investigate page with the GUID of the endpoint you selected added to the Endpoints field.

• Open Orbital from inside Cisco XDR or SecureX.

• Open Orbital directly at https://orbital.amp.cisco.com.

If necessary, click Log in with Cisco XDR or Log in with Cisco SecureX to authenticate using your existing Secure Endpoint credentials. Refer to the Cisco Security Cloud Sign On Quick Quick Start Guide for more information on logging in through. Cisco XDR or SecureX.

Endpoints - Choose the Script Target

1. In the Endpoints field, enter the ID of one or more endpoints in your organization that will have the script run against them, as shown in the figure below.

   

   To remove an endpoint from the field, click the X at the right end of the endpoint label.

   a. You can add multiple endpoints. Click at the right end of the field, as show in the figure below.

   

   The Add Multiple Endpoints dialog opens:

   

   Note: The default value for the Endpoints field is 10, it is not the maximum number of endpoints you can include in a script run. This value can be changed by either typing in a new number into the field or using the up and down arrows to specify another number.

   b. Type the number of random endpoints you wish to run the script against into the Number field, if you wish to include more or less than ten endpoints.

   c. Click Add. The endpoints are then added to the Endpoints field, as shown in the figure below.

   

Enter a Script

You can type in or paste a Python script into the Custom Script field, or select one from the Catalog.

1. Click Browse. The Script Catalog dialog opens:

   

   This 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. This information should help you quickly learn how powerful Orbital is for threat hunting.

   A Search field appears at the top of the dialog. The script list will automatically adjust to display only those catalog script that contain the search term(s).

2. Click on a script name to view detailed information:

   

3. Choose a script from the list.

   

   The script detail dialog includes a detailed script description, plus the ID, OS, Categories, ATT&CK™ Techniques and Tactics, information and warning messages, and the Python script.

   Note: Some catalog scripts will require additional parameters once they have been added. These scripts will display one or more Parameters fields describing the required information after they’ve been added.

   

Note: The Python code added from the Catalog will be hidden by default. To display the code, click on the name of the catalog script.

Note: Any values or parameters you enter into the Investigate page fields will be retained if you move to another page or tab, then return to the Investigate page. However, if you click Clear, refresh your browser, or your Orbital session expires, any values entered into the Investigate page fields will not be retained.

Running a Custom Script From the Catalog

Follow the steps below to run an custom script:

1. Click Investigate to open the Investigate page shown in the figure below.

   

2. Define the endpoints that the script will be run against.

   a. Enter the ID for one or more of your organization’s endpoints in the Endpoints field, shown in the figure below.

   

   or

   a. Click the button located under the lower-right corner of the Endopoints field, as shown in the figure below, to add multiple random endpoints.

   

   The Add Random Endpoints dialog, shown in the figure below, opens:

   

   b. Select the desired operating system or system(s) from the Add Random Endpoints dialog.

   c. Click Add. The selected endpoints are added to the Endpoints field, as shown in the figure below.

   

3. Define your script by selecting an existing script from the Orbital Catalog.

   a. Click Browse Catalog. The Catalog popup window opens as shown in the figure below.

   

   b. Type the name of the script you wish to run in the Search field. The script list will automatically adjust to only include the catalog scripts that contain the search term(s).

   c. Click on the desired script name to view its detailed information, shown in the figure below.

   

   Review the contents of the script’s detailed information and decide if you wish to use the script or not.

   • If you decide not to use the script, click the Back button, shown in the figure below, located in the top-left of the page to return to the script search list.

   

   d. When you have found the script you wish to run, click Use script, shown in the figure below.

   

   e. Add any required parameters in the Parameters field, shown in the figure below, if the script requires you to specify them.

   

4. Click Run Script to run the script and view the results. The results will be returned in the right-side pane, shown in the figure below.

   

Saving A Script To the Catalog

To save a custom script to the Orbital catalog:

1. Navigate to Orbital’s Investigate page.

2. Place your cursor in the Custom Script field, shown in the figure below.

   

3. Type your Python code into the Custom Script field. You will notice that as you type your Python code, the Save Script button is displayed, as shown in the figure below.

   

4. Click Save Script. This will display the Save Script dialog, shown in the figure below.

   

5. Type the name that the script will be saved under in the catalog in the Script Name field.

6. Type a description of the script into the Description field.

7. Select the operating system or operating systems that the script will be run against, using the OS checkboxes. This defaults to no operating systems selected. Once you have selected one or more operating systems, the Save button will be displayed.

8. Click Save. This will remove the Save Script dialog from the screen and return to the Investigate page. The newly saved script is listed at the bottom of the page, as shown in the figure below.

   

Custom Script

To send the script to the specified endpoints click Run Script. The results will be returned in the right pane:

Study the results and the Python script to learn how to edit catalog scripts and write your own Python to follow your investigation wherever it leads. You can edit the script and click Run Script again; the results will refresh.

Download

The Download function allows you to download the records of all the results of the active ad hoc query. The records retrieved using Download can be either formatted in a Comma Separated Value (CSV) file or a JavaScript Object Notation (JSON) file.

To download the active ad hoc query results:

1. Click Download. This will display the file type selector, as shown in the figure below.

2. Select the file type, either JSON or CSV. This will display the Preparing download… message, as shown below.

When the results file is ready to download, Orbital will display the download is ready message, as shown below.

3. Click download is ready.

   This will download the ad hoc query results in a ZIP file.

More Info

• Script Basics

Return to Table of Contents