Use the Catalog

You will use the Orbital Catalog to find and use queries and scripts that the Cisco Threat Research for Endpoint team has created as well as a store for those queries and scripts that you or your organization have created for your own needs.

Find Catalog Queries and Scripts with Filter and Search

Orbital provides you with two methods for locating the desired query or script to use, filters and search.

Filters

Use the filters listed on the left side of the page to filter the display of catalog queries. The display will include all queries that have been grouped into the selected filter category.

For example, select the New filter to display only those queries and scripts that have been added to the Catalog within the last 90 days.

Search Catalog

Type the desired terms or phrases in the Search Catalog field at the top of the Catalog page to locate your desired query or script. Search phrases can include partial words and variations on the query or script name. This will list all matching queries in the catalog. You can also narrow down your search further by selecting one or more filters.

Note: Catalog queries or scripts that have been deprecated cannot be added to your favorites list. Further, those queries or scripts that have been deprecated will be removed from your favorites list, if you have previously added it.

Edit a Custom Query or Script

There may be times when you will need to edit a custom query or script that has been saved to the catalog. In order to edit a custom query or script:

  1. Open the Catalog page.

  2. Navigate to the desired query or script. This can be done by:

    • Browsing to the desired query or script, using the Page Navigation Buttons.

    • Using the Search Catalog field to find the query or script.

  3. Highlight the custom query or script.

  4. Click the query or script's action menu.

  5. Select the Edit menu command.

    6. This will display the Edit Query/Script popup.

  6. Make the necessary changes to the query or script, using the Name, Description, OS, and Custom SQL interface elements.

  7. Save the changes to the query by clicking Save.

Copy or Add SQL or Python to a New Query or Script

The detailed Catalog page provides the query SQL or script Python statement.

  • To copy the SQL or Python code, click the Copy icon above the statement.

  • To add additional SQL or Python statements to the query or script you're building click the Add (+) icon. Catalog queries and scripts are designed to be run independently, so you can only add one to run at a time.

Upload Queries

Note:

This function is only available to use with queries.

The Upload queries feature uses query packs to add new queries to Orbital's Query Catalog. Query packs can contain one or more queries, allowing you to create groupings of similar queries. This feature allows you the flexibility of creating your queries on a local machine where they can be safely tested, without risking your operating environment. Once uploaded, these queries can be used by anyone in your organization.

Query packs are contained in a JSON file. The structure of the JSON file is outlined in the queryPackTemplate.json file. Refer to the Download Query Template section for more information on the file structure.

To use the feature:

  1. Navigate to Orbital's Catalog page.

  2. Click Download query template. This will download the Query Template to your local computer. This step is optional, but having the template will help in defining the information and structure needed for the query packs.

  3. Navigate to the downloaded template file.

  4. Rename the edited template file to a name that describes the query or set of queries the file contains. Do not change the file extension.

  5. Edit the template file to include one or more queries you wish to add to the Catalog. Refer to the Download Query Template section for more information on the query template structure.

    • The query name that will appear in the Query Catalog page is taken from the Query Name field in the query pack file.

  6. Save your changes.

  7. Return to the Orbital Catalog page.

  8. Click Upload queries. This will open a file navigation dialogue.

  9. Navigate to your query pack file and select it.

  10. Click Open. This will upload your query pack file to Orbital. Once the query pack has been uploaded and successfully stored in the Catalog, it will be displayed on the Query Catalog List pane.

Download Query Template

Note:

This function is only available to use with queries.

Clicking on Download then the Download query template link, shown in the figure below, allows you to download a template that you can use to create an osquery Query Pack This query pack can contain one or more queries that can be uploaded to the Orbital Catalog, using the Upload queries feature. Refer to the Upload Queries section for more information on using the Upload Queries feature.

When you click the Download query template link, a file named queryPackTemplate.json will be downloaded.

Note: Orbital will accept a value populating the Version field; however, currently Orbital ignores this value.

Download Organization Queries or Scripts

The Download organization queries/scripts link allows you to download all of the queries or scripts, stored in the Orbital Catalog, that have been created by your organization.

Note: This download feature will not include any of the stock scripts in the downloaded file. Stock scripts are those scripts that have been added to the Orbital Catalog by the Orbital development team.

When you click the Download organization queries/scripts link, a file named orgQueries.json or orgScripts.json will be downloaded.

More Info