Skip to main content

BQL Use Cases

This article provides tips for using the Brinqa Query Language (BQL) to filter data in your Brinqa Platform, including assets, vulnerabilities, tickets, and general security data. Both simple and advanced BQL queries are covered, with a focus on the use cases tailored to address common issues that Brinqa aims to solve.

BQL tips

The following table presents a set of helpful tips with examples to assist in the proper execution of your BQL queries:

tip

Keywords are not case sensitive in BQL queries, but they appear in uppercase letters in the examples throughout this article to differentiate with other parts of the query.

Table 1: BQL tips with examples

BQL TipBQL Query
Start your queries with FIND, followed by a data model, and then specify data model attributes with the WHERE clause and operators.FIND Vulnerability AS v WHERE v.severity = "Medium" AND v.lastUpdated SINCE 2023-01-01
Attributes must exist on the target data model for the query to run. Check the data model reference for attributes and additional information.FIND Finding AS f WHERE f.severity = "Medium" is valid since severity exists on Finding.
FIND Finding AS f WHERE f.os = "Linux" is not valid since os does not exist on Finding.
Data model names are case-sensitive.FIND Vulnerability, FIND Asset, etc.
BQL keywords are not case-sensitive.find Vulnerability, FIND Vulnerability, and Find Vulnerability return the same results.
Wildcards (*) are only supported for the LIKE and NOT LIKE string operators.FIND Asset AS a WHERE a.name LIKE "demo*"
FIND Asset AS a WHERE a.name NOT LIKE "demo*"
Dates must be in the format of YYYY-MM-DD.FIND Finding AS f WHERE f.lastUpdated BEFORE 2023-11-31
When using List operators, the terms or values must be encased in brackets [], with each value wrapped in double quotes "" and separated by commas.FIND Vulnerability AS v WHERE v.severity CONTAINS ANY ["Critical", "High", "Medium"]
String values are not case-sensitive and must be wrapped in double quotes.FIND Finding AS f WHERE f.status = "active"
FIND Vulnerability AS v WHERE v.riskRating = "Critical".
Number and date values do not have to be wrapped in double quotes "".FIND Finding as f WHERE f.lastUpdated SINCE 2023-01-01
FIND Vulnerability as v WHERE v.riskScore = 3
If a query is valid but does not return the expected data or results in an error, try the same query on a page that supports the data model you are querying.FIND Finding AS f WHERE f.severity = "Critical" AND f.status = "Active" is a valid query, but will not return the expected results if ran on an Inventory page. Run this query on Findings or better yet, Explorer to get the intended results.
You can retrieve data from source data models (SDMs) before they are consolidated into Brinqa unified data models (UDMs) by using the THAT SOURCED_FROM term.FIND Finding AS f THAT IS VulnerabilityDefinition AS vd THAT SOURCED_FROM Rapid7VulnerabilityDefinition AS r7vd WHERE r7vd.sourceRiskScore > 900.
Rapid7VulnerabiltyDefinition is not a UDM and sourceRiskScore is not an attribute that exists on any UDM. Rather, they both pertain to data from Rapid7 before it's been consolidated to a UDM in the Brinqa Platform.

Simple inventory queries

The following table lists some straightforward queries for gaining insights into your unified asset inventory. These queries are classified as simple as they only involve one condition, such as the count of open findings on an asset, the name of the operating system running on a host, and etc. You can use the same syntax on other target data models and attributes.

Table 2: Simple inventory queries

Use CaseBQL Query
Retrieve endpoints missing certain agents, e.g.: CrowdStrike.FIND Asset as a WHERE a.dataIntegrationTitles NOT CONTAINS ANY ["CrowdStrike"]
Retrieve all assets by a specific name. This name can be the string identifier of a server, network device, cloud instance, and etc.FIND Asset AS a WHERE a.name = "web-server-01"
Retrieve ephemeral devices.FIND Asset AS a WHERE a.lastSeen IN LAST 2 Days
Retrieve assets with over 100 open findings.FIND Asset AS a WHERE a.openFindingCount > 100
Retrieve all assets with public IP addresses.FIND Host AS h WHERE h.publicIpAddresses IS NOT NULL
Retrieve all cloud instances not being scanned for vulnerabilities.FIND Host AS h WHERE h.cloudInstanceID IS NOT NULL
Retrieve assets with a specific risk score.FIND Asset AS a WHERE a.riskScore > 5
Retrieve assets that are sourced from a specific connector.FIND Asset AS a WHERE a.connectorNames CONTAINS "Tenable.sc"
Retrieve all devices that were last seen after a specific date.FIND Device as d WHERE d.lastSeen SINCE 2020-11-31
Retrieve all out-of-compliance devices.FIND Device AS d WHERE d.complianceStatus = "Non compliant"
Retrieve all hosts running on a specific operating system.FIND Host as h WHERE h.os CONTAINS "Mac"
FIND Host AS h WHERE h.os CONTAINS "Linux"
Retrieve hosts on a specific IP address.FIND Host AS h WHERE h.ipAddresses CONTAINS ANY ["198.51.100.102"]
FIND Host AS h WHERE h.ipAddresses CONTAINS ANY ["192.168.100.200", "172.16.50.60"]
Retrieve hosts where an attribute does not contain any data.FIND Host AS h WHERE h.name NOT EXISTS
FIND Host AS h Where h.name EXISTS
Retrieve all users that have not logged in for 7 days.FIND User AS u WHERE u.lastLogin NOT IN LAST 7 Days
Retrieve all installed software on assets.FIND InstalledPackage AS s THAT INSTALLED_ON Asset AS a

Advanced inventory queries

The following table details some more advanced BQL queries that you can run to gain insights into your unified asset inventory. You can construct more extensive BQL queries by using Boolean operators, adding additional conditions, and querying for relationships. For information about how to view data model relationships, see examine relationships between data models.

Table 3: Advanced inventory queries

Use CaseBQL Query
Retrieve endpoint agents, e.g.: CrowdStrike, that are not functioning correctly. The BQL example uses 98765 as the AssetType ID, but the AssetType ID may vary depending on your data.FIND Asset AS a WHERE a.dataIntegrationTitles NOT CONTAINS ANY ["CrowdStrike"] THAT IS AssetType AS at WHERE at.name IN ["Laptops"]
Retrieve assets that belong to a specific cluster type.FIND Asset AS a THAT IS AssetType AS at WHERE at.name = "Laptop"
Retrieve all active assets with findings that have a risk score of 10.FIND Asset AS a THAT HAS Finding AS f WHERE f.riskScore = 10 AND a.status = "active"
Retrieve all active assets with findings that have a risk score greater than 7 and that are sourced from a specific connector.FIND Asset AS a THAT HAS Finding AS f WHERE a.status = "active" AND f.riskScore > 7 AND f.connectorNames CONTAINS ANY ["Tenable.sc"]
Retrieve assets with active and critical vulnerabilities that are sourced from specific connectors.FIND Asset AS a THAT HAS Vulnerability AS v WHERE v.status = "Active" AND v.severity = "Critical" AND v.connectorNames CONTAINS ANY ["Qualys Vulnerability Management", "Tenable.sc"]
Retrieve all assets with findings that have a specific risk factor applied.FIND Asset AS a THAT HAS Finding AS f THAT HAS RiskFactor as rf WHERE rf.name = "PII"
Retrieve all active assets with findings that have a risk score of 10 and were found in the last 7 days.FIND Asset AS a THAT HAS Finding AS f WHERE f.riskScore = 10 AND a.status = "active" AND f.lastFound IN LAST 7 days
Retrieve all non-compliant, active code projects that are sourced from a specific data integration.FIND CodeProject AS c WHERE c.status = "Active" AND c.dataIntegrationTitles CONTAINS ANY ["Snyk"] AND c.complianceStatus = "Non compliant"
Retrieve all active hosts with a specific finding count and operating system that are sourced from a specific connector.FIND Host AS h WHERE h.openFindingCount > 50 AND h.status = "Active" AND h.os CONTAINS "Windows" AND h.connectorNames CONTAINS ANY ["Tenable.sc"]
Retrieve all assets with findings that do not have tickets created.FIND Asset AS a THAT HAS Finding AS f THAT NOT HAS Ticket
Retrieve all installations for a specific software and the assets that the software is installed on.FIND InstalledPackage as si THAT INSTALLED_ON Asset AS a Where si.displayName = "1Password for Windows"
Retrieve the user that is responsible for a risk or remediation.FIND User AS u THAT OWNS RiskOwner AS ro WHERE ro.name = "Name"
FIND User AS u THAT OWNS RemediationOwner AS ro WHERE ro.name = "Name"
Retrieve all assets that are covered by the Asset Management connector category, but not Endpoint Protection.FIND Asset AS a WHERE a.connectorCategories CONTAINS “Asset Management” AND a.connectorCategories NOT CONTAINS “Endpoint Protection”
Retrieve unmanaged devices.FIND Asset AS a THAT NOT OWNS Person AS p
Retrieve all active assets that have some type of Torrent or Bit-torrent software installed on them.FIND InstalledPackage AS si THAT INSTALLED_ON Asset AS a WHERE si.name IN ["Torrent", "Bit-Torrent"] AND a.status = "Active"
Retrieve assets that have not been recently scanned for vulnerabilities. The BQL example uses Qualys VM as the vulnerability scanner, but you can replace it with a different vulnerability scanner, such as Tenable.io or Tenable.sc.FIND Asset AS a WHERE a.lastSeen BETWEEN [ 2023-02-01T23:07:26.000Z TO 2023-03-13T22:07:38.000Z ] AND a.dataIntegrationTitles IN ["Qualys VM"]

Simple finding queries

The following table outlines some straightforward queries to gain insights into your findings and vulnerabilities. These queries are considered simple because they only have one condition, such as the status of a vulnerability, severity level, or a specific risk score.

Table 4: Simple finding queries

Use CaseBQL Query
Retrieve all findings with an exception request.FIND Finding AS f THAT REQUESTED ExceptionRequest
Retrieve all findings found in the last 7 days.FIND Finding AS f WHERE f.firstFound IN LAST 7 Days
Retrieve all findings that are due in 14 days.FIND Finding AS f WHERE f.dueDate IN NEXT 14 Days
Retrieve all findings with a specific severity or a range of severities.FIND Finding AS f WHERE f.severity = "High"
FIND Finding AS f WHERE f.severity CONTAINS ANY ["Medium", "High", "Critical"]
Retrieve all findings with a specific status.FIND Finding AS f WHERE f.status = "Fixed"
FIND Finding AS f WHERE f.status IN ["Active", "False positive"]
Retrieve all findings with a specific risk score.FIND Finding AS f WHERE f.riskScore > 8
Retrieve all finding definitions that are associated with malware.FIND FindingDefinition AS fd WHERE fd.category CONTAINS "Malware"
Retrieve all finding definitions that are sourced from a specific data integration.FIND FindingDefinition AS fd WHERE fd.dataIntegrationTitles CONTAINS "Qualys"
Retrieve all vulnerabilities that were last updated by a specific date.FIND Vulnerability AS v WHERE v.lastUpdated SINCE 2022-12-31
Retrieve all vulnerabilities that are older than 30 days.FIND Vulnerability AS v WHERE v.ageInDays > 30
Retrieve all finding definitions related to a CVE ID or multiple CVE IDs.FIND FindingDefinition AS fd WHERE fd.cveIds CONTAINS "2022"
FIND FindingDefinition AS fd WHERE fd.cveIds CONTAINS ANY ["CVE-2022-21299", "CVE-2022-21299"]

Advanced finding queries

The following table details some advanced BQL queries you can run that involve multiple conditions, relationships, and various operators.

Some of the examples involve relationship keywords. For information about how to view data model relationships, see examine relationships between data models.

Table 5: Advanced finding queries

Use CaseBQL Query
Retrieve all high severity findings from a specific data integration.FIND Finding AS f WHERE f.status = "False positive" AND f.dataIntegrationTitles CONTAINS ANY ["Veracode"] AND f.severity = "High"
Retrieve all findings with finding definitions that were published in the last 30 days.FIND Finding AS f THAT IS FindingDefinition AS fd WHERE fd.publishedDate IN LAST 30 days
Retrieve all findings that are within SLA and due in the next 30 days.FIND Finding AS f WHERE f.dueDate IN NEXT 30 Days AND f.complianceStatus = "Within SLA"
Retrieve all high and critical findings discovered in the last 90 days.FIND Finding AS f WHERE f.severity CONTAINS ANY ["Critical", "High"] AND f.firstFound IN LAST 90 Days
Retrieve all active findings with a patch available.FIND Finding AS f THAT IS FindingDefinition AS fd WHERE fd.patchAvailable = "True" AND f.status = "active"
Retrieve all active findings with assets sourced from a specific connector that have a specific open finding count.FIND Finding AS f WHERE f.status = "Active" THAT HAS Asset AS a WHERE a.openFindingCount > 50 AND a.connectorNames CONTAINS "Tenable.io"
Retrieve all finding definitions with specific CVE IDs, are critical in severity, and are sourced from a specific connector.FIND FindingDefinition AS fd WHERE fd.cveIds CONTAINS ANY ["CVE-2021-21972", "CVE-2021-3165"] AND fd.severity = "Critical" AND fd.connectorNames CONTAINS "Qualys"
Retrieve all out-of-compliance findings with a patch available.FIND Finding as f THAT IS FindingDefinition AS fd WHERE fd.patchAvailable = "True" AND f.complianceStatus = "Out of compliance"
Retrieve all active and critical vulnerabilities sourced from specific connectors.FIND Vulnerability AS v WHERE v.status = "Active" AND v.severity = "Critical" AND v.connectorNames IN ["Qualys Vulnerability Management", "Tenable.sc"]
Retrieve all active and medium vulnerabilities sourced from Brinqa Connect.FIND Vulnerability AS v WHERE v.status = "Active" AND v.severity = "Medium" AND v.connectorNames CONTAINS "Brinqa Connect"
Retrieve all vulnerabilities on active assets from multiple connectors.FIND Vulnerability AS v THAT HAS Asset AS a Where a.status = "Active" AND a.connectorNames CONTAINS ALL ["Qualys Vulnerability Management", "Tenable.sc"]
Retrieve a specific number of out-of-compliance vulnerabilities with a Common Vulnerability Scoring System (CVSS) v3 base score greater than 8.FIND Vulnerability AS v THAT IS VulnerabilityDefinition AS vd WHERE vd.cvssV3BaseScore > 8 AND vd.numberOutOfCompliance > 100
Retrieve critical findings affecting a business service owned by a specific person.FIND Finding AS f THAT HAS Asset AS a THAT SUPPORTS BusinessService AS b THAT OWNS Person AS p WHERE p.name = "John Doe" AND f.riskRating = "Critical"
Retrieve findings due in 30 days with expired SSL (secure sockets layer) certificates.FIND Finding AS f WHERE f.dueDate IN NEXT 30 Days THAT IS FindingDefinition AS fd WHERE fd.name CONTAINS "SSL Certificate - Expired"
Retrieve all active, CISA-exploitable vulnerabilities in environment clusters that contain DMZ in the title.FIND Finding AS f THAT IS FindingDefinition AS fd AND f THAT HAS Host as h AND h THAT WITHIN Environment AS e WHERE f.status = "Active" AND fd.associatedCvesIsCisaExploitable = "True" AND e.name CONTAINS "DMZ"
Retrieve all findings with a vulnerability definition from a connector's SDM that has a specific source risk score.FIND Finding AS f THAT IS VulnerabilityDefinition AS vd THAT SOURCED_FROM Rapid7VulnerabilityDefinition AS r7vd WHERE r7vd.sourceRiskScore > 900