Contents x
TQL Generator
  • 15 Jan 2025
  • 9 Minutes to read
  • Print
  • Dark
    Light
Contents

TQL Generator

  • Updated on 15 Jan 2025
  • 9 Minutes to read
  • Print
  • Dark
    Light
Article summary

Overview

The ThreatConnect® Query Language (TQL) Generator is an artificial intelligence (AI) tool that translates plain-English prompts into TQL, making it quick and easy to retrieve targeted data sets in ThreatConnect and eliminating the need to have deep knowledge of TQL to construct advanced queries. Integrated directly into ThreatConnect, the TQL Generator understands the ThreatConnect data model and user interface intuitively. You can also share feedback about the TQL Generator and the results it provides to help ThreatConnect improve this feature.

Important
As of ThreatConnect 7.8, the TQL Generator is a beta feature available to customers that have opted in to using it. The TQL Generator is available on the Browse screen only at this time; however, it will be made available in all of the places where you can use TQL to search and filter your data in future ThreatConnect releases.

Before You Start

User Roles

  • To generate a TQL query with the TQL Generator, your user account can have any Organization role.
  • To copy, run, and save TQL queries generated with the TQL Generator, your user account can have any Organization role.

Prerequisites

  • You must opt in to the beta use of the TQL Generator via your Customer Success Manager to have access to it.

Using the TQL Generator

The TQL Generator is an AI-based utility available on the Browse screen in ThreatConnect. After you submit an English prompt describing a subset of data you would like to retrieve in ThreatConnect, the TQL Generator’s AI model will translate your prompt into a TQL query, verify that the TQL used in the query is valid, and return the query to you. You can then copy, run, or save the query and submit feedback about the query and your experience with the TQL Generator.

Follow these steps to use the TQL Generator on the Browse screen:

  1. Hover over Browse on the top navigation bar and select the type of object for which to query. Alternatively, click Browse on the top navigation bar, click Advanced at the upper-right corner of the screen, and select the type of object to query for in the dropdown at the top left of the Browse screen.
  2. Click TQL Generator at the upper-right corner of the Browse screen.
    Note
    If the TQL Generator button is not available on the Browse screen, contact your Customer Success Manager to ensure you are opted in to the beta use of the TQL Generator.
  3. Enter an English prompt (e.g., I want to search for host indicators that have the active status) into the Query box on the TQL Generator drawer, and then click Generate TQL. After a few moments, the TQL Generator will display a TQL query based on the prompt you provided (Figure 1).
    Figure 1_TQL Generator_7.8.0

     

    Important
    The TQL query will apply to the Object Type specified in the TQL Generator’s TQL Output section. This object type is determined by the Browse screen filter settings. For example, if the Browse screen is displaying one or more Indicator types, then the Object Type will be Indicators. The object type requested by your prompt must match the object type selected on the Browse screen.
  4. Select one of the following options in the TQL Generator’s TQL Output section:
    • Copy to clipboard: Copy the TQL query to your computer’s clipboard. This feature is useful when you want to use the TQL query in other areas of ThreatConnect or in the ThreatConnect v3 API.
    • Run Query: Run the TQL query and view its results on the Browse screen.
    • Save Query: Save the TQL query for later use, such as running the query at a later time, using the query in Query cards added to custom dashboards, and adding the query to an Intelligence Requirement (IR) or a Group to create associations to objects returned via the query.
      Note
      TQL queries are saved to your user profile only. Other users in your Organization cannot view and manage your saved TQL queries.
  5. (Optional) Expand the Provide Feedback card on the TQL Generator to submit feedback about the query and your experience with the TQL Generator. Sharing feedback is encouraged, as feedback submissions will be evaluated by ThreatConnect to improve the functionality of the TQL Generator.

Persisting Content in the TQL Generator

The TQL Generator is designed to be used as a side workspace to generate and save TQL queries while viewing data on the Browse screen. As such, a query will persist in the TQL Generator, even if you close it, until you generate a new query, you navigate away from the Browse screen, you log out of ThreatConnect, or your ThreatConnect session expires. This behavior allows you to return to the TQL Generator and make changes to the prompt used to generate the query; copy, run, or save the query; or submit feedback about the query.

Troubleshooting the TQL Generator

Submitting Prompts That TQL Does Not Support

The TQL Generator is designed to generate a valid TQL query based on an English prompt. If you provide a prompt that TQL does not support or cannot be used for searching data in ThreatConnect (e.g., I want to search for my account settings), the TQL Generator will display an error stating "Sorry, TQL does not support this request." In this scenario, change the prompt to something that TQL supports.

Understanding Object Type

Queries returned by the TQL Generator are scoped to the object type displayed on the Browse screen (i.e., Intelligence Requirements, Indicators, Groups, Tags, Victims, or Victim Assets). This ensures that the TQL Generator produces queries that are relevant to the objects you are viewing and helps improve the results the TQL Generator receives from the AI model.

When the object type requested in your prompt does not match the object type you are viewing on the Browse screen, the TQL Generator may fail to generate a query, display a warning to indicate that the query it returns may not apply to the object type you are viewing, or provide a query that does not return the data requested by your prompt. Make sure to adjust the Browse screen filters to display the object type your prompt requests.

Submitting Non-English Prompts

While the TQL Generator can accept requests in other languages besides English, this functionality is not fully supported in ThreatConnect 7.8. If you enter a prompt in another language besides English, review the TQL Generator’s results carefully for potential issues.

TQL Could Not Be Generated

The TQL Generator is designed to generate valid TQL queries. Before the TQL Generator provides you with a TQL query based on the prompt you submitted, it will attempt to validate whether the response returned from the AI model contains valid TQL. If the AI model’s response cannot be validated, the TQL Generator will display a message stating “ The text entered did not generate a valid TQL query. Reword the input and try again.” (Figure 2). Requests that do not produce valid TQL queries are captured anonymously for evaluation so that ThreatConnect can improve the feature in future iterations.

Figure 2_TQL Generator_7.8.0

 

Query Results Do Not Match Expectations

If you run a generated query and get results that do not match your expectations, double check all filters on the Browse screen, including My Intel Sources, to ensure that they are not excluding expected data. For example, if you enter a prompt such as “I want all reports in CAL ATL that have the apt28 tag,” but My Intel Sources is filtered to exclude the CAL Automated Threat Library Source, the prompt returned by the TQL Generator will yield no results when run on the Browse screen.

Submitting Feedback About the TQL Generator

You can submit feedback about your experience with the TQL Generator and the results it provided to help ThreatConnect identify ways to improve the feature. All feedback is anonymous and will be used to improve the quality of results provided by the TQL Generator.

Follow these steps to submit feedback within the TQL Generator:

  1. Use the TQL Generator to generate a TQL query.
  2. Expand the Provide Feedback card in the TQL Output section on the TQL Generator drawer (Figure 3), and then fill out the following fields on the card:
    Figure 3_TQL Generator_7.8.0

     

    • Was the TQL Output accurate?: Specify whether the generated TQL query was accurate (Yes) or inaccurate (No).
    • Provide Feedback or Elaborate on Issues (Optional): Enter additional feedback about the generated TQL query and share details about your experience with the TQL Generator.
  3. Click Submit Feedback on the Provide Feedback card.

TQL Generator Examples

The following sections contain example prompts that you can submit to the TQL Generator and the output that each example produces. You can use these examples to guide you as you write your own prompts.

Indicators

English InputTQL Output

I want host and address indicators with a score greater than 600 that are on the Automated Threat Library source and have been created since October 1, 2024

typeName in ("Host", "Address") and threatAssessScore > 600 and ownerName = "CAL Automated Threat Library" and dateAdded > "2024-10-01"

ip addresses added this month with a threat assess score higher than 600 and have an active status

typeName in ("Address") and dateAdded >= "THISMONTH()" and threatAssessScore > 600 and indicatorActive = true

hosts with active dns monitoring that have been updated in the past 90 days

typeName in ("Host") and hostDnsActive = true and lastModified > "NOW() - 90 DAYS"

urls and hosts with a threat rating of 3 or more that have been updated in the last 90 days

typeName in ("URL", "Host") and rating >= 3 and lastModified > "NOW() - 90 DAYS"

all hosts in cal automated threat library that have been created today and have a tag

typeName in ("Host") and ownerName = "CAL Automated Threat Library" and dateAdded >= "TODAY()" and hasTag()

I want indicators with attack tags and 5 skulls

rating = 5 and hasTag(techniqueId is not null)

 Groups

English InputTQL Output

I want all reports in ATL that have a tag that contains finance created between Nov 1 2024 and today

typeName in ("Report") and ownerName = "CAL Automated Threat Library" and hasTag(name CONTAINS "finance") and dateAdded >= "2024-11-01" and dateAdded <= "TODAY()"

I need all vulnerabilities with relationships to CAL ATL reports created in the last 30 days

typeName = "Vulnerability" and hasGroup(typeName = "Report" and ownerName = "CAL Automated Threat Library" and dateAdded >= "NOW() - 30 DAYS")

groups with the tag apt29 created after October 15 2024

hasTag(summary="apt29") and dateAdded > "2024-10-15"

Tags

English InputTQL Output

Tags whose name starts with APT

name STARTSWITH "APT"

I need any tag that contains “CVE” in its name

name CONTAINS "CVE"

Frequently Asked Questions (FAQ)

What data are captured while using the TQL Generator?

The TQL Generator is an external service used by a ThreatConnect instance that customers must opt in to use via their Customer Success Manager. While using the TQL Generator, the following minimal anonymous analytics are captured for monitoring and improvement purposes:

  • Anonymous API calls to the service
  • Anonymous information about the request, corresponding object type, and generated TQL query when one of the following conditions are met:
    • There is a failure to generate a valid TQL query
    • You submit positive or negative feedback via the Provide Feedback card
    • You save the query generated by the TQL Generator
    • You copy the query generated by the TQL Generator

If you have questions or concerns about using the TQL Generator or the data it collects, contact your Customer Success Manager. Customer feedback during the TQL Generator’s beta period is important in helping ThreatConnect align the feature with your environment and needs.

ThreatConnect® is a registered trademark of ThreatConnect, Inc.

20052-05 v.01.A

Was this article helpful?
What's Next
Company
Sales and Support
Follow Us
© 2012–2025 ThreatConnect, Inc. All Rights Reserved.