Catalog

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 with using Orbital and osquery for threat hunting. The Orbital Catalog is a robust library that:

The Query Catalog page lists all the queries that are stored in the catalog

Catalog page

Filters - Use the options in the Filters in the left pane to limit the display to queries that include the selected categories, ATT&CK Tactics, or Techniques. The filters are not exclusive: queries that contain additional categories besides the one in the filter will also be included.

Search Catalog - Use the Search Catalog field to search for queries that contain specific words or phrases. Search will be limited to the selected filter options.

Reset - Click Reset to clear any filters or search terms that have been added. The list will refresh to include all catalog queries.

Name - The Name of the catalog query. Click the name link to open the Query Catalog page with details about that query.

Created and Updated - Dates when the catalog query was created and last updated.

ID - Each catalog query has a unique identifier.

OS - Indicates which operating systems are used by the query.

Category - The catalog consists of queries that cover a range of use cases, including:

Note: The Malware category has been removed from the Orbital Query Catalog. The reason for this is that most malware-oriented queries are short lived, often having a lifespan of weeks.

ATT&CK™ TACTIC - See the MITRE ATT&CK™ Tactics web page for more information.

ATT&CK™ TECHNIQUES - See the MITRE ATT&CK™ Techniques web page for more information.

Using the Query Catalog

OSquery makes it possible for queries to return a wealth of detailed data. While this provides a great deal of flexibility and power in creating queries to deliver on multiple use cases, it also adds a level of complexity and an expectation that the user have deep knowledge of Operating System Internals, SQL, and osquery tables. The query catalog allows you to get started right away by providing a rich, deep collection of common and meaningful queries that are ready for you to use.

The catalog includes several hundred stock queries to help you get started. These queries have been vetted and tested by the Advanced Threat Research and Efficacy Team, and represent a robust collection. A few example queries are:

The implementation of these queries is visible, and allows you to customize and adapt these existing queries in order to support new use cases. The query catalog builds on the efforts of the osquery community to create reusable and high quality queries.

Viewing Catalog Queries

To open a detailed Query Catalog page, click a query name link. Each query catalog page includes a description and the query SQL statement:

Catalog query detail page

The Categories are buttons: click on a category to open the Catalog page in a new tab, displaying only the queries that include that category.

Filters - Use the options in the left panel to filter the display of catalog queries. The display will include all queries that include that category, as shown in the figure below.

Catalog query detail page

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

Search Catalog - Enter words into the Search Catalog field located at the top of the Catalog page to locate terms and phrases, including partial words and variations, within catalog query names and descriptions. The queries listed in the Catalog page will refresh to queries that only contain the search terms.

You can also narrow down your search further by selecting one or more filters in the left panel; search will be limited to the selected options as seen in the following sample, which shows the search results for the term user, with the Forensics filter set. The illustration shows several hits, which are are highlighted in yellow:

Catalog query detail page

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

Copy or Add the SQL to a New Query

The detailed Query Catalog page provides the query SQL statement.

Upload 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.

    • If the file is successfully uploaded and stored in the Catalog, you will receive the following status message.

      Query Upload Success Status Message

    • If the file has been incorrectly formatted, you will receive the following error message.

      Query Upload Error Message

    • If you have accidentally uploaded an existing query pack file, you will receive the following error message.

      Query Already Exist

    Once the query pack has been uploaded and successfully stored in the Catalog, it will be displayed on the Query Catalog List pane.

Download Organization Queries

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

Download organization queries link

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

When you click the Download organization queries link, a file named orgQueries.json will be downloaded to your computer. The structure of this file is shown in the figure below.

{
	"queries": {
		"Query Name": {
			"created": "Date and Time Query Was Created",
			"creator": {
				"created": "Date and Time Query Was Created",
				"id": "User ID Number",
				"name": "Developer's Name"
			},
			"description": "The description of the query is typed in this field.  This can include information such as
			                its purpose, what its target is, and so on",
			"id": "org:This is the organization's ID number",
			"organization": {
				"id": "This is the organization's ID number",
				"name": "This is the name of the organization"
			},
			"query": [
				"This is the query's SQL statement;"
			]
		},
...
}

Download Query Template

Clicking on 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.

Download query template link

When you click the Download query template link, a file named queryPackTemplate.json will be downloaded to your computer. The structure of this file is shown in the figure below.

{
	"queries": {
		"Unique Title 1": {
			"query": [
				"Array of SQL statements to be executed.",
				"At least one required."
			],
			"description": "Text description of what the query does. Required.",
			"platform": [
				"Array",
				"of",
				"compatible",
				"platforms.",
				"Optional."
			],
			"version": "Only run on osquery versions greater than or equal-to this version string. Optional."
		},
		"Unique Title 2 (etc)": {
			"query": [
				"SELECT a, b FROM z WHERE b = \"bee\"",
				"SELECT a, c FROM z WHERE c = \"sea\""
			],
			"description": "Selects data based on letter puns.",
			"platform": [
				"windows",
				"mac",
				"linux"
			],
			"version": "2.4"
		},
		"Only Required Fields": {
			"query": [
				"required"
			],
			"description": "required"
		}
	}
}

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

More Information

Return to Table of Contents