Nucleus Query Language (NQL)

Overview

The Nucleus Query Language, or NQL is a semantic query language that flattens the Nucleus Data Core into a single, simple way to ask any question you need about your vulnerabilities, assets, threats, software, and more. Queries are built around keywords, logical operators, and comparisons to be able to ask any question that you wish.

NQL Queries

Queries (or NQL queries) represents a question asked by a vulnerability management professional. One example might be:

“Show me all vulnerabilities with a status of Waiting For 3rd Party that are due within the next 30 days.”

The answer to this question from Nucleus helps vulnerability managers proactively communicate with vendors and track upcoming deadlines for third-party remediation. Results are returned to the user and are called a result set. NQL queries can be saved as different saved searches on the All Findings Page. Once a search is saved it can be accessed again using the same All findings page.

NQL Queries follow a straightforward pattern:

Determine the question to ask. Example questions might be:
1. "Show me high-priority overdue vulnerabilities requiring immediate attention”
2. “Show me recently discovered critical vulnerabilities with exception requests”
3. “I want to see all critical vulnerabilities across production assets”
Formulate the appropriate NQL query
Use the Explore Interface to execute the query
Take action on the results, which may include report generation or modifying findings

NQL Structure

NQL queries can be expressed using a Basic or Advanced structure depending on your needs. The first allows you to leverage the Nucleus UI to manage columns and sorting, and the more advanced version allows you to specify columns in your NQL expression itself as well as more advanced filtering and sorting using logical comparison operators and keywords.

Simple Format

SELECT dataset WHERE condition1 AND condition2 …

The above expression will use default columns (or whatever columns you choose in the UI) and will use a default sorting mechanism.

Advanced Format

Default column names

SELECT field1, field2, field3 FROM dataset where condition1 AND condition2 ORDER by field1 DESC

The above expression allows you to specify which columns you would like to return without needing to interact with the Nucleus UI controls

Specify Column Names

SELECT field1 AS "field name", field2 AS "field name", field3 AS "field name" FROM dataset where condition1 AND condition2 ORDER by field1 DESC, field2 ASC

The above expression allows you to do two additional things:

Name the columns for each field
Combine the ordering syntax so you can create advanced sorting logic, such as ORDER BY severity DESC, nucleus_threat_rating DESC

Basic NQL Query

It may be useful to try out a simple query before diving deeper into the language. A simple query would return all findings with critical severity using the simple NQL syntax.

Vulnerability Management Question	NQL Query
Show me all critical severity findings sorted by the Nucleus recommended prioritization methodology	`SELECT Findings WHERE severity = "Critical"`

This NQL query will show all finding instances in Nucleus where the severity is Critical in the result set. Notice the use of the equal sign (“=”) which is a comparison operator as well as the use of the findings dataset where we are pulling data from.

We can expand on this query to make it more specific to only identify critical findings on assets in the Production asset group. We can add some more columns and introduce sorting by the name of the finding:

Vulnerability Management Question	NQL Query
Simple Syntax: Show me all critical severity findings on assets in the Production Asset group sorted by when they were discovered	`SELECT findings WHERE severity = "Critical" AND asset_group IN ("Production") ORDER BY finding_discovered ASC`
Advanced Syntax: Same as above expression but adds sorting on severity (descending) and the finding discovered date (ascending)	`SELECT finding_name, finding_risk_score, finding_source, asset_name, severity, nucleus_threat_rating, finding_discovered FROM findings WHERE severity = "Critical " AND asset_group IN ("Production") ORDER BY severity DESC, finding_discovered ASC`

Vulnerability Management Question

NQL Query

Simple Syntax: Show me all critical severity findings on assets in the Production Asset group sorted by when they were discovered

SELECT findings WHERE severity = "Critical" AND asset_group IN ("Production") 
ORDER BY finding_discovered ASC

Advanced Syntax: Same as above expression but adds sorting on severity (descending) and the finding discovered date (ascending)

SELECT finding_name, finding_risk_score, finding_source, asset_name, severity, nucleus_threat_rating, finding_discovered FROM findings 
WHERE severity = "Critical " AND asset_group IN ("Production") 
ORDER BY severity DESC, finding_discovered ASC

Query Construction

The following picture shows a useful way of thinking about queries: Columns, Dataset, Filter, Sort for the advanced NQL syntax. First identify the columns to show, then the dataset, then apply filter logic on the selected fields. Finally, order the results in ascending order by when the finding was discovered.

The following sections define the available keywords, logical operators, comparison operators and possible field types.

NQL Keywords

Keyword	Description
AS	Renames a field with an alias. Column aliasing is optional and does not affect the results
ASC	Sorts the result set in ascending order.
DESC	Sorts the result set in descending order.
EMPTY	Evaluated as an empty value when used in comparison operations, for example: `SELECT finding_name FROM findings WHERE due_date = EMPTY`
FROM	Specifies the dataset to return data from.
LIMIT	Limits the result set to a particular value
ORDER BY	Sorts the result set in ascending or descending order. Valid sort directions are ASC, DESC and NONE.
SELECT	Specifies the fields from a dataset that you want to return.
TODAY	Resolves to the current date in the user's time zone for use in date functions, for example: `SELECT finding_name, DATE_DIFF(TODAY, finding_discovered) AS 'Calculated Age' FROM findings` Format: YYYY-MM-DD (e.g., "2025-01-15")
WHERE	Filters results to include only records that fulfill specified condition(s).

NQL Comparison Operators

Operator	Description
=	Equal to. Also used with EMPTY for NULL checking. Example: = EMPTY
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to
!=	Not equal to
<>	Not equal to (alternative)

NQL Special Operators

Operator	Description
CONTAINS	TRUE if the value IS a substring match
NOT CONTAINS	TRUE if the value IS NOT a substring match
IN	TRUE if the value IS equal to one of a list of expressions
NOT IN	TRUE if the value IS NOT equal to one of a list of expressions

NQL Logical Operators

Logical Operator	Description
AND	The value is TRUE if all conditions separated by the AND are TRUE
OR	The value is TRUE if at least one condition separated by OR is TRUE

NQL supports AND & OR logical operators with parentheses () for grouping conditions in WHERE clauses for more powerful and flexible queries, for example:
SELECT finding_name, severity, finding_source, cves, asset_name
FROM findings 
WHERE (finding_source = "Nessus" OR finding_source = "Nexpose" OR finding_source = "Rapid7") 
  AND (severity = "Critical" OR severity = "High") 
  AND cve_count > 0  

Calculation Functions (non‑aggregate)

NQL supports a set of non‑aggregate calculation functions you can use in both SELECT and WHERE clauses. These functions operate on each row individually (they do not require GROUP BY). You can assign a column alias using AS in the SELECT clause and then reuse that alias in both the WHERE and ORDER BY clauses, for example:

SELECT MULTIPLY(finding_risk_score, 10) AS ten_x_risk
FROM findings
WHERE ten_x_risk > 1000
ORDER BY ten_x_risk DESC

Alias rules

Alias names must be unique within the query.
An alias must not have the same name as an existing field in the dataset (for example, severity AS severity is invalid).
If an alias conflicts with a field name or another alias, the query will return an error.

Nested functions

You can also nest functions as long as the input and output types are compatible, for example:

SELECT ADD(MULTIPLY(finding_risk_score, 10), 5) AS 'ten_x_risk_plus_five'
FROM findings

String Functions

Function	Description
`CONCAT(str1, str2, ...)`	Concatenates two or more strings.
`SUBSTRING(str, pos, len)`	Returns a substring of `str`, starting at position `pos` for `len` characters.

Numeric Functions

Function	Description
`ADD(num1, num2, ...)`	Adds two or more numbers.
`SUBTRACT(num1, num2)`	Subtracts `num2` from `num1`.
`MULTIPLY(num1, num2, ...)`	Multiplies two or more numbers.
`DIVIDE(num1, num2)`	Divides `num1` by `num2`.
`ROUND(num, decimals)`	Rounds a number to the specified number of decimals.

These all expect numeric arguments (either numeric fields or numeric literals like 10 or 0.5).

Date and Datetime Functions

Function	Description
`DATE_ADD(date, value, unit)`	Adds or subtracts time from a date/datetime field. Example units: `DAY`, `WEEK`, `MONTH`, `YEAR`, `HOUR`, `MINUTE`, `SECOND`.
`DATE_DIFF(date1, date2)`	Returns the difference between `date1` and `date2` in days.
`DATE_FORMAT(date, format)`	Converts a date/datetime field to a string, using the supplied format string.
`DAY(date)`, `MONTH(date)`, `YEAR(date)`	Extract the corresponding part of a date.

You can pass date/datetime fields, the keyword TODAY, or quoted date literals (for example, "2026-12-31").

List Functions

Some fields, such as asset_group, are lists. You can use list functions to work with them:

Function	Description
`LIST_LENGTH(list_field)`	Returns how many values are in the list.
`IN_LIST(list_field, value)`	Returns `true` if `value` appears in `list_field`.

Field Types

Type	Description	Supported Operators
String	Text	=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN
Number	A positive number	=, >, <, >=, <=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN
Date	A date in the format YYYY-MM-DD	=, >, <, >=, <=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN
Datetime	A date-time	=, >, <, >=,<=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN
List	A list of values	=, CONTAINS, NOT CONTAINS, IN, NOT IN
Boolean	Yes or No	=, !=

Relative Date and Datetime Filters

For date and datetime fields (such as finding_discovered, finding_last_seen, and host_last_seen_date), NQL supports both absolute and relative values in WHERE clause comparisons.

Absolute Values

You can compare directly to a specific date:

...
WHERE finding_discovered >= "2026-01-01"
...

Relative Values

You can also filter relative to the current date using:

...
WHERE due_date < TODAY  //Overdue findings
...
WHERE finding_discovered > '-7d' //Findings discovered in the last 7 days
...
WHERE due_date < '7d'  //Findings due in the next 7 days
...

Relative offsets are supported in the range of 1–365 days and are evaluated with second‑level precision.

NQL Datasets

This section describes the available datasets

Dataset	Description
findings	All finding instances in the current project

NOTE: Only findings of type vulnerability are currently supported by NQL

Findings Dataset: Fields

This section describes the available fields for the findings dataset.

Field Name	Data Type	Description	Possible Values
age	Number	Number of days since the discovered date	N/A
asset_business_owner_team	List	Business Owner Team on asset	List of defined teams
asset_group	Array	The list of asset groups an asset belongs to	Varies based on the asset groups in your project
asset_info	Object	Collection of asset metadata fields	Varies by asset and scan source.
asset_name	String	The name of the asset associated with a finding instance	Includes the host name and IP when available. Ex: localhost.localdomain (192.168.1.3)
asset_support_team	List	Support Team on asset	List of defined teams
asset_type	List	The type of asset	Various asset types
assigned_team	List	Team assigned to a finding instance	Varies based on the teams in your project
business_criticality	List	Business criticality level of the asset	Critical, High, Moderate, Low
compliance_scope	List	Compliance scope of the asset	In-Scope, Out-of-Scope
cve_count	Number	Count of CVEs associated with the finding	N/A
cves	String	CVEs associated with the finding	Varies by vulnerability and CVE
data_sensitivity	List	Data sensitivity level of the asset	Critical, High, Moderate, Low
due_date	Date	The due date set on a finding	N/A
exploitable	Boolean	Whether or not Nucleus has determined if the finding is exploitable	Yes/No
finding_discovered	Datetime	Date and time a finding was discovered (as reported by the finding source)	N/A
finding_last_seen	Date	The last time a scanner saw this finding in a scan	N/A
finding_name	String	The name of a finding instance	N/A
finding_risk_score	Number	The Nucleus risk score for a finding instance	0 to 1000
finding_source	String	The source/scan type that discovered the finding	N/A
finding_status	List	Status of the finding for a finding instance	Active: Active, Exception Requested, Fixed, In Progress, Potential, Waiting for 3rd Party, Waiting for Verification.
host_name	String	The host name of the asset associated with a finding instance	Ex: localhost.localdomain
ip_address	String	Primary IP address for the asset	N/A
mandiant_exploit_in_the_wild	Boolean	Finding has known exploits reported to be found in the wild by Mandiant	Yes/No
mandiant_exploit_rating	List	Mandiant's exploit rating for a finding	Wide, Confirmed, Available, Anticipated, No Known
mandiant_exploited_by_malware	Boolean	Finding has known malware exploits available according to Mandiant	Yes/No
mandiant_risk_rating	List	Mandiant's risk rating for a finding	Critical, High, Medium, Low
mandiant_zero_day	Boolean	Finding is a Zero Day vulnerability according to Mandiant	Yes/No
network_exposure	List	Network exposure level of the asset	Internal, External
nucleus_ease_of_exploitation	List	The determined ease of exploitation based on the threat insights feed	Very Easy, Easy, Moderate, Hard, Very Hard, Unknown
nucleus_exploitation_consequence	List	The consequence of exploiting this vulnerability	The contents of this field vary based on the consequence. For Example: Code Execution, Command Execution, etc.
nucleus_exploited	Boolean	Whether or not the vulnerability has been exploited based on the threat insights feed	Yes/No
nucleus_exploited_by_malware	Boolean	Whether or not Nucleus has determined if the finding has been exploited by malware in the wild	Yes/No
nucleus_exploited_by_malware	Boolean	Whether or not the vulnerability has been exploited by malware based on the threat insights feed	Yes/No
nucleus_exploited_by_ransomware	Boolean	Whether or not the vulnerability has been exploited by ransomware based on the threat insights feed	Yes/No
nucleus_impacts_ot	Boolean	Whether or not Nucleus has determined if the finding impacts operational technology/IT	Yes/No
nucleus_patch_available	Boolean	Whether or not the vulnerability has a patch available based on the threat insights feed	Yes/No
nucleus_private_exploit_available	Boolean	Whether or not the vulnerability has a private exploit based on the threat insights feed	Yes/No
nucleus_public_exploit_available	Boolean	Whether or not the vulnerability has a public exploit based on the threat insights feed	Yes/No
nucleus_public_exploit_available	Boolean	Whether or not Nucleus has determined if the finding has a public exploit available	Yes/No
nucleus_remote_exploitation	Boolean	Whether or not the vulnerability can be remotely exploited based on the threat insights feed	Yes/No
nucleus_threat_rating	List	The determined threat rating of the vulnerability based on the threat insights feed	Existential, Critical, High, Medium, Low
nucleus_zero_day	Boolean	Whether or not the vulnerability is a zero day based on the threat insights feed	Yes/No
nucleus_zero_day_previously	Boolean	Whether or not the vulnerability was a zero day based on the threat insights feed	Yes/No
severity	List	The Nucleus severity of a finding instance	Critical, High, Medium, Low, Informational

Documentation Index