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:
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 Tip | BQL 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 = "Confirmed 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 = "Confirmed 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 . Rapid7VulnerabilityDefinition 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 Case | BQL 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 Case | BQL Query |
---|---|
Retrieve all inactive assets with active critical findings. | FIND Asset AS a THAT HAS Finding AS f WHERE a.status = "Confirmed inactive" AND f.status = "Confirmed active" AND f.riskRating = "Critical" |
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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 ip THAT INSTALLED_ON Asset AS a Where ip.displayName = "1Password for Windows" |
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 ip THAT INSTALLED_ON Asset AS a WHERE ip.name IN ["Torrent", "Bit-Torrent"] AND a.status = "Confirmed 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"] |
Retrieve all applications that support code projects with a high risk rating and that also support hosts with a critical risk rating. | FIND Application AS a THAT SUPPORTS CodeProject AS c AND a THAT SUPPORTS Host WHERE c.riskRating = "High" AND h.riskRating = "Critical" |
Retrieve all applications with open tickets for static code findings | FIND Application AS a THAT SUPPORTS CodeProject AS c THAT HAS StaticCodeFinding AS s THAT HAS Ticket AS t |
Retrieve assets with a Crown Jewel risk factor that haven't been seen in the last 30 days. A Crown Jewel refers to assets that hold high value or importance to an organization. | FIND Asset AS a THAT HAS RiskFactor as rf WHERE a.lastSeen NOT IN LAST 30 Days AND rf.name = "Crown Jewel" |
Retrieve all assets tagged as "External" that are associated with findings linked to CVE records where exploits exist. | Find Asset as a WHERE a.tags CONTAINS "External" THAT HAS Finding as f THAT IS FindingDefinition as fd THAT EXPLOITS CveRecord as cve WHERE cve.exploits EXISTS |
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 Case | BQL 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 ["Confirmed 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 Case | BQL Query |
---|---|
Retrieve all critical and exploitable findings that are due in the next 30 days. | FIND Finding AS f THAT HAS RiskFactor AS r WHERE f.dueDate IN NEXT 30 Days AND f.riskRating = "Critical" AND r.name CONTAINS "Exploitable" |
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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 = "Confirmed 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 |
Retrieve critical Microsoft vulnerabilities eligible for patching, first detected over 90 days ago in a designated environment, affecting workstations. | FIND Vulnerability AS v THAT HAS Asset as a AND v THAT IS VulnerabilityDefinition as v2 AND a THAT IS AssetType AS a2 AND a THAT WITHIN Environment as e WHERE v.firstFound NOT IN LAST 90 Days AND v.status = "Confirmed active" AND v.riskRating = "Critical" AND v2.patchAvailable = TRUE AND v2.displayName CONTAINS "Microsoft" AND a2.displayName CONTAINS "Workstation" AND e.displayName LIKE "EnvironmentName" AND a.os CONTAINS "Microsoft" AND a.os <= "Microsoft Windows 10" |
Retrieve vulnerabilities within a specific environment, e.g.: PCI, that has a Risk Score greater than or equal to 8 | FIND Vulnerability AS v THAT HAS Asset AS a AND a THAT WITHIN Environment AS e WHERE v.riskScore >= 8 AND e.name LIKE "PCI" |
Retrieve all exception requests that are older than 30 days that contain out-of-compliance findings with risk score greater than 5. | FIND ExceptionRequest AS e THAT REQUESTED Finding AS f WHERE e.status = "New" AND e.dateCreated NOT IN LAST 30 Days AND f.riskScore >= 5.0 AND f.complianceStatus = "Out of SLA" |
Ownership queries
The following table details some BQL queries that pertain to ownership clusters. You can use ownership queries to extract insights regarding risk and remediation ownership clusters.
Some of the examples involve relationship keywords. For information about how to view data model relationships, see examine relationships between data models.
Table 6: Ownership queries
Use Case | BQL Query |
---|---|
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 critical vulnerabilities owned by a specific remediation ownership cluster. | FIND Vulnerability AS v THAT HAS Asset AS a AND a THAT OWNS_REMEDIATION RemediationOwner AS ro WHERE v.riskRating = "Critical" AND ro.name LIKE "Windows Workstation Remediation Team" |
Retrieve assets that have risk or remediation owners. | FIND Asset AS a THAT OWNS_REMEDIATION RemediationOwner AS ro AND a THAT OWNS_RISK RiskOwner as ro2 |
Retrieve assets that do not have risk or remediation owners. | FIND Asset AS a THAT OWNS_REMEDIATION RemediationOwner AS ro AND a THAT OWNS_RISK RiskOwner AS ro2 WHERE ro.name CONTAINS "Unassigned" AND ro2.name CONTAINS "Unassigned" |
Retrieve critical assets that belong to a specific remediation owner cluster. | Find RemediationOwner AS ro THAT OWNS_REMEDIATION Asset AS a WHERE ro.name LIKE "Windows Workstation Remediation Team" and a.riskRating = "Critical" |
Retrieve critical assets with exploitable findings that belong to a specific risk owner cluster. | Find RiskOwner AS ro THAT OWNS_RISK Asset AS a THAT HAS Finding AS f THAT HAS RiskFactor AS r WHERE ro.name LIKE "Digital Storefront" and a.riskRating = "Critical" AND r.name CONTAINS "Exploitable" |