Visual Query Builder

This article details the Brinqa Visual Query Builder (VQB) and how to use it effectively to return data and learn the Brinqa Query Language (BQL).

What is the VQB?

The VQB is a user-friendly tool designed to visualize the process of building BQL queries, making data search and retrieval simple, straightforward, and intuitive. With the VQB, you can construct powerful BQL queries in an easy-to-use interface, without in-depth knowledge of the BQL syntax. Whether you're identifying specific vulnerabilities or monitoring compliance, VQB can help you leverage your data with ease, enhancing your cyber risk management efforts. The VQB allows you to build and test diverse queries with a point-and-click approach, transforming the complex task of remembering BQL keywords, operators, or functions into a visual exploration.

How to use the VQB

The VQB is a powerful tool that simplifies the process of creating BQL queries. It enables you to visually construct queries through a point-and-click interface without needing to memorize the syntax of BQL.

You can use the VQB on any page that supports the use of BQL, such as Inventory, Clusters, Findings, and Explorer.

tip

When using the VQB on the Inventory > All assets page, you can only build queries pertaining to your assets or data models that extend assets, such as hosts, devices, software, or containers. The same logic applies to Findings. You can only build queries surrounding findings and data models that extend findings, such as violations or vulnerabilities.

Key features of the VQB

The VQB is designed with a variety of key features that enable the query-building process. These features include:

• Select a data model: The VQB starts with you selecting a data model that your query revolves around. Each data model contains its unique attributes and relationships. This selection sets the context of your query, determining the attributes and relationships available for inclusion in the query.

  

• Configure attribute filters: An attribute filter is a condition based on the attributes that exist on the selected data model. Different attributes have different possible operators. For instance, date attributes offer unique operators. Check the BQL documentation for a comprehensive list of operators. Attributes that exist on the Host data model include Status, Operating system, IP addresses, and more. See the Host data model reference for the full list of attributes.

  

  • Combine attribute filters: The VQB allows you to add more than one attribute filter to your query. You can use the AND and OR logical operators to create more complex conditions. The AND operator returns results only if both conditions are met, while the OR operator returns results if either condition is met. You can also group conditions with the "Add group condition (AND)" or "Add group condition (OR)" options. These grouping conditions use parentheses to dictate the order in which conditions are evaluated. For example:

    • A AND (B OR C): Returns results if A is true and either B or C is true.
    • A OR B OR C: Returns results if any one of A, B, or C is true.
    • A AND B OR C: Returns results if A and B are true, or if C is true.

    

• Configure relationship filters: The VQB lets you explore the relationships between your target data model and other data models. For example, some of the relationships that the Host data model supports includes

  • DEPLOYED_FROM HostImage: Represents that a specific host is deployed from a particular host image. A host image, in this context, is typically a blueprint used to create a host with predefined configurations, software, or operating system. Understanding this relationship can help track the origin of the host, which can be useful for auditing, troubleshooting, and managing consistency across hosts.

  • OWNS Person: Implies that a certain individual, identified as Person in the data model, is the owner of the host. This person might be responsible for the host's operation, management, or security. Having this information can be useful for accountability and for directing queries or actions to the right individual.

  • SUPPORTS BusinessService: Signifies that a host provides support for a particular business service. In other words, the host may be running applications or services that are critical to a business function. Understanding this relationship can be important for assessing the potential impact on business services if the host experiences issues, as well as for prioritizing resources and efforts in maintaining the host.

  You can modify relationships in the VQB by using the additional options in the kebab (three vertical dots) menu:

  • Invert relationship: Prefixes NOT to your existing relationship, which implies that the specified relationship does not exist.

  • Make optional: Prefixes OPTIONALLY before your relationship, which allows for optional relationship traversal in your query.

  

• Toggle the search bar icons: The search bar contains the following icons that can help manage your queries:

  • : Clear the current query and reset the builder.

  • : Open a new tab in your browser for the BQL documentation.

  • : Toggle between collapsing and expanding the search bar.

  • : Save the current query for future use.

  • : Access recent and saved queries for quick utilization.

Tutorial: Use the VQB to retrieve critical findings affecting a business service

This tutorial demonstrates how you can use the VQB to build a query that retrieves all active assets with critical findings due in the next 30 days, which are affecting a business service. You can use this query to identify and prioritize critical threats directly impacting your core business services, as these threats can lead to significant disruptions if not mitigated. The BQL query you are constructing leverages the Asset data model to establish a relationship between Finding and BusinessService. Here is how it looks:

FIND Finding AS f THAT HAS Asset AS a THAT SUPPORTS BusinessService AS b WHERE f.riskRating = "Critical" AND f.dueDate In NEXT 30 Days AND a.status = "Active"

To build this query using the VQB, follow these steps:

1. Navigate to Explorer or Findings.

2. Click the icon to the left of the search area, and then select Query builder.

   

3. Click Select data model, select Finding > Finding, and then click Apply.

   If you are on the Findings page, the Finding data model is already selected.

4. Click Relationship filter, select HAS, and then select Asset.

   This relationship filter retrieves findings that are contextually relevant and tied to assets.

5. Under THAT HAS Asset as a, click Relationship filter, select SUPPORTS, and then select Business service.

   This relationship filter ties the findings to specific assets that support a business service. This connection can provide context for the potential business impact of the critical findings.

6. Under Find Finding AS f, click Attribute filter, and then click Risk rating. You can also search for "Risk rating" in the search bar. Fill in the following fields:

   • Operator: Click the drop-down and select Equals to.

   • Value: Click the drop-down, select Critical, and then click Apply.

     This attribute filter only retrieves findings with a critical risk rating, letting you address the most severe findings first.

7. Under Find Finding as f, click Attribute filter again, click Add condition (AND), and then click Due date. Fill in the following fields:

   • Operator: Click the drop-down and select In next.

   • Number: Type 30.

   • Units. Click the drop-down, select Days, and then click Apply.

     This attribute filter retrieves findings that are due to be resolved in the next 30 days. Focusing on findings due within the next 30 days can help you focus on imminent risks and prioritize your risk mitigation efforts.

8. Under THAT HAS Asset as a, click Attribute filter, and then click Status. Fill in the following fields:

   • Operator: Click the drop-down and select Equals to.

   • Value: Click the drop-down, select Active, and then click Apply.

     This attribute filter retrieves only active assets. Inactive assets may not pose an immediate threat and may only clutter your results, making it harder to prioritize actions.

9. Click Apply filters to run the query.

The following screenshot illustrates what the visual query resembles. After verifying the validity of the query and running it successfully, you can save it for future use. To learn more, see Save and reuse queries.

Tutorial: Use the VQB to retrieve assets with critical findings not affecting a business service

This tutorial demonstrates how you can use the VQB to build a query that retrieves all active assets with critical findings that are not affecting a business service. You can use this query to identify and prioritize critical threats that are not directly associated with your core business services, as not all security threats directly impact business services; some can exist on isolated or peripheral assets. These threats, while not immediately disruptive, can escalate and pose significant risks over time if not addressed.

The BQL query you are constructing leverages the Asset data model to establish a relationship between Finding and BusinessService. Here is how it looks:

FIND Finding AS f WHERE f.riskRating = "Critical" THAT HAS Asset AS a WHERE a.status = "Active" THAT NOT SUPPORTS BusinessService AS b

To build this query using the VQB, follow these steps:

1. Navigate to Explorer or Findings.

2. Click the icon to the left of the search area, and then select Query builder.

   

3. Click Select data model, select Finding > Finding, and then click Apply.

   If you are on the Findings page, the Finding data model is already selected.

4. Click Relationship filter, select HAS, and then select Asset.

   This relationship filter retrieves findings that are contextually relevant and tied to assets.

5. Under THAT HAS Asset as a, click Relationship filter, select SUPPORTS, and then select Business service.

6. Click the kebab (three vertical dots) menu to the right of THAT SUPPORTS BusinessService as b and select Invert relationship.

   This relationship filter ties the findings to specific assets that do not support a business service and changes the relationship to THAT NOT SUPPORTS.

7. Under Find Finding AS f, click Attribute filter, and then click Risk rating. You can also search for "Risk rating" in the search bar. Fill in the following fields:

   • Operator: Click the drop-down and select Equals to.

   • Value: Click the drop-down, select Critical, and then click Apply.

     This attribute filter only retrieves findings with a critical risk rating, letting you address the most severe findings first.

8. Under THAT HAS Asset as a, click Attribute filter, and then click Status. Fill in the following fields:

   • Operator: Click the drop-down and select Equals to.

   • Value: Click the drop-down, select Active, and then click Apply.

     This attribute filter retrieves only active assets. Inactive assets may not pose an immediate threat and may only clutter your results, making it harder to prioritize actions.

9. Click Apply filters to run the query.

The following screenshot illustrates what the visual query resembles. After verifying the validity of the query and running it successfully, you can save it for future use. To learn more, see Save and reuse queries