Skip to main content

Search Overview

This article details the different search methods across the Brinqa Platform, where you can use these search methods, and how to save search queries for reuse.

Introduction to searches​

The Brinqa Platform includes two different ways to search through your data: Basic or BQL (Brinqa query language). The Basic option contains selectable filters to narrow your search while BQL requires proper query language syntax. You can use search to limit the data that is reviewed in a given context.

You can use the basic search function on any page within your Brinqa Platform that supports basic search filters, including the pages under Inventory, Findings, or Remediation. For example, the following screenshot displays what the filters may look like on the Findings page:

findings page basic filters

While the default filters vary by page, you can add more filters to your basic search by clicking More + and select the filters you want.

To use the basic search filters, to find all active findings with a medium severity, for example, follow these steps:

  1. Navigate to Findings.

  2. Click Basic if not selected already.

  3. Click the Status menu and select Active.

  4. Click the Severity menu and select Medium.

The list view updates automatically upon making a selection.

To view the BQL equivalent of a basic search, click BQL after you run a basic search. For example, the following BQL query is equivalent to the basic search example:

FIND Finding AS f WHERE f.status = "Active" AND f.severity = "Medium"

You can use this method to learn and get familiar with BQL.

BQL is a Brinqa specific query language designed to traverse your data and provide results. BQL defines a means of searching your data and attempts to resemble a natural language for simpler query construction. See BQL query structure for usage information.

Many pages in your Brinqa Platform support the use of BQL, including the pages under Inventory, Findings, Explorer, or Remediation. For example, to use BQL to find all of your compliant and active assets with a "Host" category, follow these steps:

  1. Navigate to Inventory > Assets > All assets.

  2. Click BQL if not selected already.

  3. Type the following query:

    FIND Asset AS a WHERE a.category = "Host" AND a.status = "Active" AND a.complianceStatus = "Compliant"
    tip

    The system displays a list of available objects to select as you type your query.

  4. Press Enter or Return to execute the query.

If your query is valid, a green checkmark displays; if your query is invalid, a red exclamation mark displays. Hold your pointer over the mark to see the explanation on why the query is invalid.

It is important to take note of the page you are on before you attempt to execute a query, otherwise your query may not return any data even when it is valid. Take the following query for example:

Find User as u Where u.authMethod = "SAML"

The above query returns all users who authenticate using the Security Assertion Markup Language (SAML) method. The query is valid. If you are on Explorer or Inventory > Human Resources > People, the query runs successfully because Explorer is a global page that covers all data in your Brinqa Platform, and Human Resources > People lists employees working in your organization. However, if you try to execute the same query on Findings, which does not contain any data on users, the query does not return any data.

tip

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.

BQL query structure​

The basic structure for a valid BQL query is as follows:

  • Start with FIND followed by the data model name you want to target. For example:
FIND Finding
  • Assign the targeted data model an alias using AS to be used in the rest of the query, and then add additional conditions using WHERE, WITH, AND, or OR, followed by attributes that exist on the target data model. For example:
FIND Finding AS f WHERE f.status = "Active"
  • Build on the query further by providing relationships with THAT followed by a relationship verb. For example:
FIND Finding AS f WHERE f.status = "Active" THAT IS FindingDefinition AS fd WHERE fd.cveIds CONTAINS ANY ["CVE-2017-7654"] AND fd.patchAvailable = "True"

Let's break down the components of the above BQL query to better understand how it's constructed:

  • FIND Finding AS f WHERE f.status = "Active": This part of the query selects the starting data model Finding, assigns it an alias f to be used in the rest of the query, and adds a condition to limit the data. In this case, the query only returns active findings.

  • THAT IS FindingDefinition AS fd: This part extends from the Finding data model to the FindingDefinition data model using the relationship keyword THAT IS. The FindingDefinition data model is assigned an alias fd.

  • WHERE fd.cvdIds CONTAINS ANY ["CVE-2017-7654"] AND fd.patchAvailable = "True": This part defines filtering conditions on the FindingDefinition data model using its attributes. In this case, the query only returns finding definitions whose cveIds attribute contains the string "CVE-2017-7645" and the patchAvailable attribute is set to "True".

Refer to BQL keywords for details about basic keywords that make up the clauses of a query statement and query for relationships in BQL for details about how to query your data using the relationships between data models.

Save BQL queries​

You can save your most used and favorite queries to be reused at a later time. Saved queries do not transfer across pages in your instance. In other words, if you save a query on the Findings page, it does not appear in your list of saved queries on the Knowledge base or Inventory page.

To save a BQL query, follow these steps:

  1. Navigate to the page on which you want to save the query.

  2. Click BQL to the right of the search bar.

  3. Type your BQL query and press Enter.

  4. Click Save query save query icon and fill in the following:

    • Title: The name of your saved query.

    • Description: The description of your saved query.

      info

      The query field contains the query and cannot be changed.

    • New label: The label for the query. Labels categorize your saved queries.

  5. Click Save.

Reuse BQL queries​

To reuse a recently used BQL query, follow these steps:

  1. Navigate to the page on which you want to reuse a query.

  2. Click BQL to the right of the search bar.

  3. Click the caret menu caret menu in the search bar to display your most recent queries.

  4. Click the recently used query to populate the search bar with that specific query.

    The query runs automatically.

To use a saved BQL query, follow these steps:

  1. Navigate to the page on which you want to save a query.

  2. Click BQL to the right of the search bar.

  3. Click the caret menu caret menu in the search bar to display your queries.

  4. Click Saved queries. A new window appears.

  5. Hold the pointer over the saved query you want to use and click Select.

    The query populates the search bar and runs automatically.

Delete a saved query​

To delete a saved query, follow these steps:

  1. Navigate to the page on which you want to delete the saved query.

  2. Click BQL to the right of the search bar.

  3. Click the caret menu caret menu icon in the search bar.

  4. Click Saved queries.

  5. Hold the pointer over the saved query you want to delete and click Delete.