Overview
A ThreatConnect® Query Language (TQL) query expression includes a parameter name, an operator, and a value or list of values, and you can combine multiple query expressions using parentheses and AND/OR logic. This article provides a list of all TQL operators and parameters available in ThreatConnect.
Note
A value’s case sensitivity may depend on database deployment type, the operator being applied to it, or other factors.
Operators
Table 1 describes the ThreatConnect Query Language (TQL) operators in all their acceptable forms.
Note
Operators are case insensitive. For example, when using the
IN operator in a query, it can be written as IN or in.
| Operator(s) | Description | Example |
|---|---|---|
| =, ==, EQ, EQUALS | Returns objects that equal the specified value. | typeName = "Adversary" |
| !=, NE | Returns objects that do not equal the specified value. | typeName != "Adversary" |
| >, GT | Returns objects that are greater than the specified value. | dateAdded > "2023-12-31" |
| <, LT | Returns objects that are less than the specified value. | dateAdded < "2023-12-31" |
| <=, LEQ | Returns objects that are less than or equal to the specified value. | dateAdded <= "2023-12-31" |
| >=, GEQ | Returns objects that are greater than or equal to the specified value. | dateAdded >= "2023-12-31" |
| IN | Returns objects that match any value in a list of values. | typeName IN ("Host", "URL") |
| LIKE | Returns objects that match an exact term or a pattern. Use the percent symbol (%) as a wildcard to represent zero, one, or multiple characters in a pattern. | typeName LIKE ("Email%") |
| CONTAINS | Returns objects that contain the specified value. | summary CONTAINS "bad" |
| STARTSWITH | Returns objects that start with the specified value. | summary STARTSWITH "CVE-" |
| ENDSWITH | Returns objects that end with the specified value. | summary ENDSWITH ".com" |
| NOT | Negates the IN, LIKE, CONTAINS, STARTSWITH, or ENDSWITH operator or a nested query in an expression. Place NOT before the operator or nested query to be negated. | summary NOT CONTAINS "bad" |
| AND | Logical and that returns objects for which all conditions in the expression are true. | typeName = "Host" AND dateAdded >= "2023-12-31" |
| OR | Logical or that returns objects for which any condition in the expression is true. | typeName = "Host" OR dateAdded >= "2023-12-31" |
Parameters
The following subsections describe the threat intelligence, Workflow, and general TQL parameters available in ThreatConnect.
Note
Parameters are case insensitive. For example, when using the
typeName parameter in a query, it can be written as typeName or typename.Threat Intelligence Parameters
The following subsections describe the TQL parameters available for threat intelligence data objects in ThreatConnect.
Note
Use ISO-8601-compliant formatting for TQL parameters whose data type is DateTime.
Groups
Table 2 provides the TQL parameters available for Groups. Table 3 provides the TQL parameters available for unified Groups.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Groups | aiLastRetrievalDate | DateTime | The date and time the Group’s AI-generated summary was last retrieved from its source (for Document, Event, and Report Groups only) |
| Groups | aiProvider | String | The provider of an AI-generated summary for a relevant Group (ThreatConnect AI for user-generated summaries; the name of the feed for AI insights provided by participating feeds) |
| Groups | associatedGroupSource | String | Acceptable values:
|
| Groups | associatedIndicator | Integer | Deprecated by nested query; equivalent to hasIndicator(id=n) |
| Groups | associatedIndicatorSource | String | Acceptable values:
|
| Groups | attackTag | String | The name of an ATT&CK® Tag applied to the Group |
| Groups | attributeNN | Dependent | See the “Query for Attributes” section of Constructing Query Expressions for more information. |
| Groups | createdBy | User | Any username in the user’s Organization (e.g., createdBy = "joeuser@gmail.com") |
| Groups | dateAdded | DateTime | |
| Groups | documentDateAdded | DateTime | |
| Groups | documentFilename | String | |
| Groups | documentFilesize | Long | |
| Groups | documentStatus | String | |
| Groups | documentType | String | |
| Groups | downvoteCount | Integer | |
| Groups | emailDate | DateTime | |
| Groups | emailFrom | String | |
| Groups | emailScore | Integer | |
| Groups | emailScoreIncludesBody | Boolean | |
| Groups | emailSubject | String | |
| Groups | eventDate | DateTime | The date the event that the Group represents occurred (for Event and Incident Groups only) |
| Groups | eventType | Enum | The type of event that the Group represents (for Event Groups only) Acceptable values:
|
| Groups | externalDateAdded | DateTime | The date and time the Group was first created by a third party |
| Groups | externalDateExpires | DateTime | The date and time the Group expires in a third party |
| Groups | externalLastModified | DateTime | The date and time the Group was last modified in a third party |
| Groups | firstSeen | DateTime | The date and time the Group was first seen |
| Groups | generatedReport | Boolean | Returns Report Groups that were created using the Publish Report feature in the Report Editor |
| Groups | hasAllTags() | Nested Query | A nested query that returns only Groups with all specified Tags applied to them. The query must be of the form hasAllTags(id=x) or hasAllTags(id IN (x,y)), where x and y represent Tag ID numbers. |
| Groups | hasArtifact() | Nested Query | |
| Groups | hasAttribute() | Nested Query | |
| Groups | hasCase() | Nested Query | |
| Groups | hasCommonGroup() | Nested Query | A nested query that returns Groups that meet the specified unified Group criteria. See Table 3 for a list of parameters that can be used within the hasCommonGroup() nested query parameter. |
| Groups | hasCommonVulnerability() | Nested Query | A nested query that returns Groups that meet the specified unified Vulnerability Group criteria. See Table 3 for a list of parameters that can be used within the hasCommonVulnerability() nested query parameter. |
| Groups | hasGroup() | Nested Query | |
| Groups | hasIndicator() | Nested Query | |
| Groups | hasIntelQuery() | Nested Query | |
| Groups | hasIntelRequirement() | Nested Query | |
| Groups | hasSecurityLabel() | Nested Query | |
| Groups | hasTag() | Nested Query | |
| Groups | hasThreatActorProfile() | Nested Query | A nested query that returns Groups that meet the specified Threat Actor Profile criteria. See Table 5 for a list of parameters that can be used within the hasThreatActorProfile() nested query parameter. |
| Groups | hasVictim() | Nested Query | |
| Groups | hasVictimAsset() | Nested Query | |
| Groups | id | Integer | The ID number of a Group. This number can be found in the URL of the Group’s Details screen, between groups/ and /overview. |
| Groups | insights | String | The AI-generated summary of a Group provided by a participating feed for a relevant Group |
| Groups | lastModified | DateTime | |
| Groups | lastSeen | DateTime | The date and time the Group was last seen |
| Groups | owner | Integer | |
| Groups | ownerName | String | |
| Groups | publishDate | DateTime | The date the Group was published (for Report Groups only) |
| Groups | securityLabel | String | |
| Groups | signatureDateAdded | DateTime | |
| Groups | signatureFilename | String | |
| Groups | signatureType | String | |
| Groups | status | String | |
| Groups | summary | String | |
| Groups | tag | String | Deprecated by nested query; equivalent to hasTag(summary="") |
| Groups | tagOwner | Integer | Deprecated by nested query; equivalent to hasTag(owner=n) |
| Groups | tagOwnerName | String | Deprecated by nested query; equivalent to hasTag(ownerName="") |
| Groups | taskAssignee | User | me is the only valid value |
| Groups | taskAssigneePseudo | User | |
| Groups | taskDateAdded | DateTime | |
| Groups | taskDueDate | DateTime | |
| Groups | taskEscalated | Boolean | |
| Groups | taskEscalationDate | DateTime | |
| Groups | taskLastModified | DateTime | |
| Groups | taskOverdue | Boolean | |
| Groups | taskReminded | Boolean | |
| Groups | taskReminderDate | DateTime | |
| Groups | taskStatus | String | |
| Groups | type | Integer | |
| Groups | typeName | String | |
| Groups | upvoteCount | Integer | |
| Groups | victimAsset | String | Deprecated by nested query; equivalent to hasVictimAsset(name="") |
hasCommonGroup() and hasCommonVulnerability() Parameters
Table 3 provides the TQL parameters that can be used within the hasCommonGroup() and hasCommonVulnerability() nested query parameters.
Note
The hasCommonGroup() nested query parameter filters Adversary, Intrusion Set, and Threat Groups that belong to a Threat Actor Profile, and Vulnerability Groups that belong to a unified Vulnerability Group. The hasCommonVulnerability() nested query parameter filters only Vulnerability Groups that belong to a unified Vulnerability Group.
| Parameter | Data Type | Comments |
|---|---|---|
| All Unified Groups (Unified Vulnerability Groups and Threat Actor Profiles) | ||
| dateAdded | DateTime | The date and time a unified Group was first created in ThreatConnect |
| description | String | The description of a unified Group |
| hasGroup() | Nested Query | A nested query for association to other Groups |
| id | Integer | The ID number of a unified Group |
| lastAssessed | DateTime | The date and time a unified Group was last assessed by a third party (e.g., VulnCheck) |
| lastModified | DateTime | The date and time a unified Group was last modified in, or re-ingested into, ThreatConnect |
| summary | String | The name/summary of a unified Group |
| type | Integer | The ID number of a unified Group's type |
| typeName | String | The name of a unified Group's type |
| Unified Vulnerability Groups | ||
| criteria | String | The Common Platform Enumeration (CPE) match criteria of a Vulnerability |
| cvss_score_v2 | Double | The CVSS V2 score of a Vulnerability. Scores range from 0–10. |
| cvss_score_v3 | Double | The CVSS V3 score of a Vulnerability. Scores range from 0–10. |
| cvss_score_v3_1 | Double | The CVSS V3.1 score of a Vulnerability. Scores range from 0–10. |
| cvss_score_v4 | Double | The CVSS V4 score of a Vulnerability. Scores range from 0–10. |
| cvss_severity_v2 | Enum | The CVSS V2 severity of a Vulnerability Acceptable values:
|
| cvss_severity_v3 | Enum | The CVSS V3 severity of a Vulnerability Acceptable values:
|
| cvss_severity_v3_1 | Enum | The CVSS V3.1 severity of a Vulnerability Acceptable values:
|
| cvss_severity_v4 | Enum | The CVSS V4 severity of a Vulnerability Acceptable values:
|
| cvss_v2 | String | The CVSS V2 vector string of a Vulnerability |
| cvss_v3 | String | The CVSS V3 vector string of a Vulnerability |
| cvss_v3_1 | String | The CVSS V3.1 vector string of a Vulnerability |
| cvss_v4 | String | The CVSS V4 vector string of a Vulnerability |
| dueDate | DateTime | The date by which organizations are expected to patch or mitigate a Vulnerability listed in the U.S. Cybersecurity and Infrastructure Security Agency (CISA) Known Exploited Vulnerabilities (KEV) Catalog |
| externalDateAdded | DateTime | The date a Vulnerability was added to the KEV Catalog |
| hasAffectedProduct() | Nested Query | A nested query that returns Vulnerability Groups that meet the specified affected product criteria. See Table 4 for a list of parameters that can be used within the hasAffectedProduct() nested query parameter. |
| knownRansomwareCampaignUse | String | The designation as to whether a KEV Vulnerability is known to have been used in a ransomware campaign Acceptable values:
|
| lastPublished | DateTime | The date and time a Vulnerability was published in the National Institute of Standards and Technology (NIST) National Vulnerability Database (NVD) |
| notes | String | The additional notes provided for a KEV Vulnerability |
| requiredAction | String | The immediate action required by federal entities and other organizations to address a KEV Vulnerability |
| shortDescription | String | The short description of a KEV Vulnerability |
| source | String | The reference source for a Vulnerability |
| subtype | String | The subtype of a Vulnerability Acceptable values:
|
| title | String | The summary of a Vulnerability provided by a third party (e.g., VulnCheck) |
| vendorProject | String | The vendor project that discovered a KEV Vulnerability |
| vulnerabilityName | String | The name of a KEV Vulnerability |
hasAffectedProduct() Parameters
Table 4 provides the TQL parameters that can be used within the hasAffectedProduct() nested query parameter.
| Parameter | Data Type | Comments |
|---|---|---|
| cpe23uri | String | A CPE 2.3-formatted string |
| dateAdded | DateTime | The date and time an affected product was first created in ThreatConnect |
| edition | String | Edition information applied by the vendor to characterize an affected product (e.g., Professional, Enterprise) |
| hasCommonGroup() | Nested Query | A nested query that returns Groups that meet the specified unified Group criteria. See Table 3 for a list of parameters that can be used within the hasCommonGroup() nested query parameter. |
| id | Integer | An affected product's ID number |
| language | String | The language supported in an affected product's user interface |
| lastModified | DateTime | The date and time an affected product was last modified in, or re-ingested into, ThreatConnect |
| other | String | Additional vendor- or product-specific information available for an affected product |
| part | String | The type of affected product Acceptable values:
|
| product | String | An affected product's name or title |
| swEdition | String | An affected product's software edition, which identifies how an affected product is marketed to end users |
| targetHw | String | The instruction set architecture in which an affected product operates |
| targetSw | String | The software environment in which an affected product operates |
| update | String | An affected product's update or revision |
| vendor | String | An affected product's vendor |
| version | String | An affected product's version number |
| vulnerabilityId | Integer | The ID number of a unified Vulnerability Group associated with an affected product |
hasThreatActorProfile() Parameters
Table 5 provides the TQL parameters that can be used within the hasThreatActorProfile() nested query parameter.
| Parameter | Data Type | Comments |
|---|---|---|
| deprecated | Boolean | A flag indicating whether the Threat Actor Profile is deprecated |
| externalDateAdded | DateTime | The date and time the Threat Actor Profile was first created by MITRE ATT&CK |
| externalDateModified | DateTime | The date and time the Threat Actor Profile was last modified by MITRE ATT&CK |
| mitreId | String | The MITRE ID of the Threat Actor Profile |
| mitreLink | String | The URL of the MITRE ID details page on the MITRE ATT&CK website |
Indicators
Table 6 provides the TQL parameters available for Indicators.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Indicators | abuseIpdbConfidenceScore | Integer | The Confidence of Abuse percentage calculated by AbuseIPDB for the Indicator. It is a rating, from 0 to 100, of how confident AbuseIPDB is, based on user reports, that an IP address is entirely malicious. |
| Indicators | activeLocked | Boolean | |
| Indicators | addressASN | Integer | |
| Indicators | addressCIDR | CIDR Expression | |
| Indicators | addressCity | String | |
| Indicators | addressCountryCode | String | |
| Indicators | addressCountryName | String | |
| Indicators | addressIpVal | BigInteger | |
| Indicators | addressIsIpv6 | Boolean | |
| Indicators | addressRegisteringOrg | String | |
| Indicators | addressState | String | |
| Indicators | addressTimezone | String | |
| Indicators | associatedGroup | Integer | Deprecated by nested query; equivalent to hasGroup(id=n) |
| Indicators | associatedGroupSource | String | Acceptable values:
|
| Indicators | associatedIndicatorSource | String | Acceptable values:
|
| Indicators | attackTag | String | The name of an ATT&CK Tag applied to the Indicator |
| Indicators | attributeNN | Dependent | See the “Query for Attributes” section of Constructing Query Expressions for more information. |
| Indicators | calScore | Integer | A stored version of the Indicator’s CAL™ Global Threat Score. This ThreatConnect-stored version of the CAL Global Threat Score is typically updated daily. The timing may vary per instance. Note that the stored version may not match the CAL Global Threat Score displayed on an Indicator’s Details screen, which derives the CAL Global Threat Score on demand. |
| Indicators | confidence | Integer | |
| Indicators | dateAdded | DateTime | |
| Indicators | description | String | |
| Indicators | dtLastUpdated | DateTime | The last date and time the Indicator was looked at with DomainTools® |
| Indicators | dtMalwareScore | Integer | The malware score for the Indicator in DomainTools |
| Indicators | dtOverallScore | Integer | The overall score for the Indicator in DomainTools |
| Indicators | dtPhishingScore | Integer | The phishing score for the Indicator in DomainTools |
| Indicators | dtSpamScore | Integer | The spam score for the Indicator in DomainTools |
| Indicators | dtStatus | Boolean | The domain status for the Indicator in DomainTools |
| Indicators | externalDateAdded | DateTime | The date and time the Indicator was first created by a third party |
| Indicators | externalDateExpires | DateTime | The date and time the Indicator expires in a third party |
| Indicators | externalLastModified | DateTime | The date and time the Indicator was last modified by a third party |
| Indicators | falsePositiveCount | String | |
| Indicators | fileName | String | |
| Indicators | filePath | String | |
| Indicators | fileSize | BigInteger | |
| Indicators | firstSeen | DateTime | The date and time the Indicator was first seen |
| Indicators | hasAllTags() | Nested Query | A nested query that returns only Indicators with all specified Tags applied to them. The query must be of the form hasAllTags(id=x) or hasAllTags(id IN (x,y)), where x and y represent Tag ID numbers. |
| Indicators | hasArtifact() | Nested Query | |
| Indicators | hasAttribute() | Nested Query | |
| Indicators | hasCase() | Nested Query | |
| Indicators | hasCustomAssociation() | Nested Query | |
| Indicators | hasGroup() | Nested Query | |
| Indicators | hasIndicator() | Nested Query | |
| Indicators | hasIntelRequirement() | Nested Query | |
| Indicators | hasSecurityLabel() | Nested Query | |
| Indicators | hasTag() | Nested Query | |
| Indicators | hasVictim() | Nested Query | |
| Indicators | hasVictimAsset() | Nested Query | |
| Indicators | hostDnsActive | Boolean | |
| Indicators | hostWhoisActive | Boolean | |
| Indicators | id | Integer | The ID number of an Indicator. This number can be found in the URL of the Indicator’s Details screen, between indicators/ and /overview. |
| Indicators | indicatorActive | Boolean | |
| Indicators | lastFalsePositive | DateTime | |
| Indicators | lastModified | DateTime | |
| Indicators | lastObserved | DateTime | |
| Indicators | lastSeen | DateTime | The date and time the Indicator was last seen |
| Indicators | observationCount | Integer | |
| Indicators | owner | Integer | |
| Indicators | ownerName | String | |
| Indicators | rating | Integer | |
| Indicators | sameNameAs | Integer | Used to search for Indicators by ID number instead of their full summary string |
| Indicators | securityLabel | String | |
| Indicators | source | String | |
| Indicators | summary | String | |
| Indicators | tag | String | Deprecated by nested query; equivalent to hasTag(summary="") |
| Indicators | tagOwner | Integer | Deprecated by nested query; equivalent to hasTag(owner=n) |
| Indicators | tagOwnerName | String | Deprecated by nested query; equivalent to hasTag(ownerName="") |
| Indicators | threatAssessLastUpdated | DateTime | The date and time an Indicator’s ThreatAssess score was most recently updated (or, for newly scored Indicators, the date and time the Indicator’s ThreatAssess score was first calculated) |
| Indicators | threatAssessScore | Integer | |
| Indicators | type | Integer | |
| Indicators | typeName | String | |
| Indicators | value1 | String | Used to search for Indicators that include multiple fields (e.g., File Indicators, Registry Key Indicators) |
| Indicators | value2 | String | Used to search for Indicators that include multiple fields (e.g., File Indicators, Registry Key Indicators) |
| Indicators | value3 | String | Used to search for Indicators that include multiple fields (e.g., File Indicators, Registry Key Indicators) |
| Indicators | vtLastUpdated | DateTime | The last date and time the Indicator was looked at with VirusTotal™ |
| Indicators | vtMaliciousCount | Integer | The number of malicious reports for an Indicator from VirusTotal (i.e., the VirusTotal score) |
Intelligence Requirements
Table 7 provides the TQL parameters available for Intelligence Requirements (IRs).
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Intelligence Requirements | category | String | The category of an IR |
| Intelligence Requirements | dateAdded | DateTime | The date and time an IR was added to ThreatConnect |
| Intelligence Requirements | hasArtifact() | Nested Query | A nested query for association to Artifacts |
| Intelligence Requirements | hasCase() | Nested Query | A nested query for association to Cases |
| Intelligence Requirements | hasGroup() | Nested Query | A nested query for association to Groups |
| Intelligence Requirements | hasIndicator() | Nested Query | A nested query for association to Indicators |
| Intelligence Requirements | hasTag() | Nested Query | A nested query for association to Tags |
| Intelligence Requirements | hasVictim() | Nested Query | A nested query for association to Victims |
| Intelligence Requirements | hasVictimAsset() | Nested Query | A nested query for association to Victim Assets |
| Intelligence Requirements | id | Integer | The ID number of an IR. This number can be found in the URL of the IR’s Details screen, between intel-requirements/ and /overview. |
| Intelligence Requirements | lastModified | DateTime | The last modified date for an IR |
| Intelligence Requirements | owner | Integer | The ID of an IR’s owner |
| Intelligence Requirements | ownerName | String | The name of an IR's owner |
| Intelligence Requirements | requirement | String | The summary of an IR |
| Intelligence Requirements | subtype | String | The subtype of an IR |
| Intelligence Requirements | tag | String | The name of a Tag applied to an IR |
| Intelligence Requirements | uniqueId | String | The unique ID of an IR. This is the number that was entered in the ID field when the IR was created. It is found at the upper left of the header of the IR’s Details screen, both next to the Browse link and above the IR’s summary. |
Intelligence Requirement Results
Table 8 provides the TQL parameters available for Intelligence Requirement (IR) results.
Important
You can query for Intelligence Requirement results only in dashboard Query cards and when using the ThreatConnect v3 API. You cannot query for them on the Legacy Browse screen or when searching by object type on the Search screen.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Intelligence Requirement Results | archivedDate | DateTime | The date and time an IR query result was archived |
| Intelligence Requirement Results | dateAdded | DateTime | The date and time the ThreatConnect object to which an IR query result corresponds was created |
| Intelligence Requirement Results | hasIntelRequirement() | Nested Query | |
| Intelligence Requirement Results | id | Integer | The ID number of an IR query result |
| Intelligence Requirement Results | intelId | Integer | The ID number of the ThreatConnect object to which an IR query result corresponds |
| Intelligence Requirement Results | intelReqId | Integer | The ID number of the IR to which an IR query result corresponds |
| Intelligence Requirement Results | intelType | String | The type of ThreatConnect object to which an IR query result corresponds (e.g., Address, Host, Adversary, Campaign) |
| Intelligence Requirement Results | isArchived | Boolean | A flag indicating whether an IR query result has been archived |
| Intelligence Requirement Results | isAssociated | Boolean | A flag indicating whether an IR query result has been associated to an IR |
| Intelligence Requirement Results | isDeleted | Boolean | A flag indicating whether an IR query result has been deleted |
| Intelligence Requirement Results | isFalsePositive | Boolean | A flag indicating whether an IR query result has been flagged as a false positive |
| Intelligence Requirement Results | isLocal | Boolean | A flag indicating whether an IR query result exists in the owners to which you have access on your ThreatConnect instance |
| Intelligence Requirement Results | lastMatchedDate | DateTime | The date and time that an IR query result last matched the IR’s keyword query |
| Intelligence Requirement Results | lastModified | DateTime | The date and time the ThreatConnect object to which an IR query result corresponds was last modified |
| Intelligence Requirement Results | owner | Integer | The ID number of the owner of the ThreatConnect object to which an IR query result corresponds |
| Intelligence Requirement Results | ownerName | String | The name of the owner of the ThreatConnect object to which an IR query result corresponds |
| Intelligence Requirement Results | score | Decimal | A weighted score indicating the relevancy of an IR query result Note The score for an IR query result is not available in the ThreatConnect UI. It can be accessed only via TQL queries and the v3 API. This parameter can be used to target IR query results that have the most relevancy out of all available IR query results. |
| Intelligence Requirement Results | summary | String | The summary of the ThreatConnect object to which an IR query result corresponds |
Tags
Table 9 provides the TQL parameters available for Tags.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Tags | active | Boolean | Read-only field that can be false for certain ATT&CK Tags that become deprecated over time and will be excluded from places such as the ATT&CK Visualizer. The value of this parameter is true in all other cases. |
| Tags | associatedCase | Integer | Deprecated by nested query; equivalent to hasCase(id=n) |
| Tags | associatedGroup | Integer | Deprecated by nested query; equivalent to hasGroup(id=n) |
| Tags | associatedIndicator | Integer | Deprecated by nested query; equivalent to hasIndicator(id=n) |
| Tags | associatedVictim | Integer | Deprecated by nested query; equivalent to hasVictim(id=n) |
| Tags | caseId | Integer | |
| Tags | description | String | |
| Tags | financialRisk | String | The financial risk level of an ATT&CK Tag as it relates to the user's Organization. This score is derived from ThreatConnect Risk Quantifier (RQ). For more information, see ATT&CK RQ Financial Impact. Acceptable values:
|
| Tags | hasCase() | Nested Query | |
| Tags | hasGroup() | Nested Query | |
| Tags | hasIndicator() | Nested Query | |
| Tags | hasVictim() | Nested Query | |
| Tags | id | Integer | The ID number of a Tag. This number can be found in the URL of the Tag’s Details screen, after tag.xhtml?tag=. |
| Tags | lastUsed | DateTime | |
| Tags | name | String | The name of the Tag (case sensitive) |
| Tags | normalized | Boolean | Read-only field that indicates if a Tag is defined as a main Tag within a Tag normalization rule. |
| Tags | owner | Integer | |
| Tags | ownerName | String | |
| Tags | securityCoverage | Enum | The security coverage level assigned to an ATT&CK Tag in your Organization. Acceptable values:
|
| Tags | summary | String | The name of the Tag (case insensitive) |
| Tags | techniqueId | String | The standard ID for specific MITRE ATT&CK techniques and sub-techniques (e.g., T1234, T1234.001). The value of this parameter is null for all non-ATT&CK Tags. |
Victim Assets
Table 10 provides the TQL parameters available for Victim Assets.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Victim Assets | asset | String | |
| Victim Assets | associatedGroup | Integer | Deprecated by nested query; equivalent to hasGroup(id=n) |
| Victim Assets | hasGroup() | Nested Query | |
| Victim Assets | hasIndicator() | Nested Query | |
| Victim Assets | hasVictim() | Nested Query | |
| Victim Assets | hasVictimAsset() | Nested Query | |
| Victim Assets | id | Integer | |
| Victim Assets | owner | Integer | |
| Victim Assets | ownerName | String | |
| Victim Assets | summary | String | |
| Victim Assets | type | Integer | |
| Victim Assets | typeName | String | |
| Victim Assets | victimId | Integer | |
| Victim Assets | victimName | String |
Victims
Table 11 provides the TQL parameters available for Victims.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Victims | assetName | String | Deprecated by nested query; equivalent to hasVictimAsset(summary="") |
| Victims | assetType | Integer | Deprecated by nested query; equivalent to hasVictimAsset(type=n) |
| Victims | assetTypeName | String | Deprecated by nested query; equivalent to hasVictimAsset(typeName="") |
| Victims | attackTag | String | The name of an ATT&CK Tag applied to the Victim |
| Victims | attributeNN | Dependent | See the “Query for Attributes” section of Constructing Query Expressions for more information. |
| Victims | description | String | |
| Victims | hasAllTags() | Nested Query | A nested query that returns only Victims with all specified Tags applied to them. The query must be of the form hasAllTags(id=x) or hasAllTags(id IN (x,y)), where x and y represent Tag ID numbers. |
| Victims | hasAttribute() | Nested Query | |
| Victims | hasGroup() | Nested Query | |
| Victims | hasIndicator() | Nested Query | |
| Victims | hasSecurityLabel() | Nested Query | |
| Victims | hasTag() | Nested Query | |
| Victims | hasVictim() | Nested Query | |
| Victims | hasVictimAsset() | Nested Query | |
| Victims | id | Integer | The ID number of a Victim. This number can be found in the URL of the Victim’s Details screen, after victim.xhtml?victim=. |
| Victims | name | String | |
| Victims | nationality | String | |
| Victims | organization | String | |
| Victims | owner | Integer | |
| Victims | ownerName | String | |
| Victims | securityLabel | String | |
| Victims | subOrg | String | |
| Victims | summary | String | Equivalent to name |
| Victims | tag | String | Deprecated by nested query; equivalent to hasTag(summary="") |
| Victims | tagOwner | Integer | Deprecated by nested query; equivalent to hasTag(owner=n) |
| Victims | tagOwnerName | String | Deprecated by nested query; equivalent to hasTag(ownerName="") |
| Victims | workLocation | String |
Workflow Parameters
The following subsections describe the TQL parameters available for Workflow objects in ThreatConnect.
Important
You can query for Workflow objects only in dashboard Query cards and the ThreatConnect v3 API. You cannot query for them on the Legacy Browse screen or when searching by object type on the Search screen .
Note
Use ISO-8601-compliant formatting for TQL parameters whose data type is DateTime.
Artifacts
Table 12 provides the TQL parameters available for Artifacts.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| Artifact | analyticsScore | Integer | The ThreatAssess assessment level of the Artifact |
| Artifact | caseId | Integer | The ID number of a Case associated with an Artifact |
| Artifact | dateAdded | DateTime | The date and time an Artifact was created |
| Artifact | hasCase() | Nested Query | A nested query for association to other Cases |
| Artifact | hasGroup() | Nested Query | A nested query for association to other Groups |
| Artifact | hasIndicator() | Nested Query | A nested query for association to other Indicators |
| Artifact | hasNote() | Nested Query | A nested query for association to other Case Notes |
| Artifact | hasTask() | Nested Query | A nested query for association to other Tasks |
| Artifact | id | Integer | The ID number of an Artifact |
| Artifact | indicatorActive | Boolean | A flag indicating whether the Artifact is active |
| Artifact | noteId | Integer | The ID number of a Case Note associated with an Artifact |
| Artifact | source | String | The source of an Artifact |
| Artifact | summary | String | The summary of an Artifact |
| Artifact | taskId | Integer | The ID number of a Task associated with an Artifact |
| Artifact | type | String | The type name of an Artifact |
| Artifact | typeName | String | The type name of an Artifact |
Artifact Types
Table 13 provides the TQL parameters available for Artifact types.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| ArtifactType | active | Boolean | The active status of an Artifact type |
| ArtifactType | dataType | Enum | The data type of an Artifact type |
| ArtifactType | description | String | The description of an Artifact type |
| ArtifactType | id | Integer | The ID number of an Artifact type |
| ArtifactType | intelType | String | The intel type of an Artifact type |
| ArtifactType | managed | Boolean | The managed status of an Artifact type |
| ArtifactType | name | String | The name of an Artifact type |
Cases
Table 14 provides the TQL parameters available for Cases.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| Case | assignedToUserOrGroup | Enum | The type of Case assignee (either User or Group) |
| Case | assigneeName | String | The name of the user or user group assigned to the Case |
| Case | attackTag | String | The name of an ATT&CK Tag applied to the Case |
| Case | attribute | String | An Attribute corresponding to a Case |
| Case | calScore | Integer | A stored version of the Case’s CAL Global Threat Score (i.e., the highest CAL Global Threat Score among the Case’s Artifacts that have a CAL Global Threat Score and an active Indicator statusdetermined by CAL). This ThreatConnect-stored version of the CAL Global Threat Score is typically updated daily. The timing may vary per instance. Note that the stored version may not match the CAL Global Threat Score displayed on an Indicator’s or Case’s Details screen, which derives the CAL Global Threat Score on demand. |
| Case | caseCloseDate | DateTime | The date and time a Case was closed |
| Case | caseCloseTime | DateTime | The date and time a Case was closed |
| Case | caseCloseUser | User | The username of the user who closed a Case |
| Case | caseDetectionTime | DateTime | The date and time a security incident or threat (i.e., the event that caused a Case to be opened) was detected (e.g., by the security team) |
| Case | caseDetectionUser | User | The username of the user who logged a Case’s detection time |
| Case | caseOccurrenceTime | DateTime | The date and time a security incident or threat (i.e., the event that caused a Case to be opened) occurred |
| Case | caseOccurrenceUser | User | The username of the user who logged a Case’s occurrence time |
| Case | caseOpenDate | DateTime | The date and time a Case was opened |
| Case | caseOpenTime | DateTime | The date and time a Case was opened |
| Case | caseOpenUser | User | The username of the user who opened a Case |
| Case | createdBy | User | The username of the user who created a Case |
| Case | createdById | Integer | The user ID number of the user who created a Case |
| Case | dateAdded | DateTime | The date and time a Case was created |
| Case | description | String | The description of a Case |
| Case | detectionDue | DateTime | The Service Level Agreement (SLA) detection due date for a Case |
| Case | detectionOverdue | Boolean | A flag indicating whether a Case exceeded the allowed completion time for its SLA detection due date |
| Case | hasAllTags() | Nested Query | A nested query that returns only Cases with all specified Tags applied to them. The query must be of the form hasAllTags(id=x) or hasAllTags(id IN (x,y)), where x and y represent Tag ID numbers. |
| Case | hasArtifact() | Nested Query | A nested query for association to Artifacts |
| Case | hasCase() | Nested Query | A nested query for association to other Cases |
| Case | hasGroup() | Nested Query | A nested query for association to other Groups |
| Case | hasIndicator() | Nested Query | A nested query for association to other Indicators |
| Case | hasNote() | Nested Query | A nested query for association to Case Notes |
| Case | hasTag() | Nested Query | A nested query for association to labels |
| Case | hasTask() | Nested Query | A nested query for association to Tasks |
| Case | hasWorkflowTemplate() | Nested Query | A nested query for association to Workflow Templates |
| Case | id | Integer | The ID number of a Case |
| Case | idAsString | String | The ID number of a Case as a String |
| Case | lastUpdated | DateTime | The date and time a Case was last updated |
| Case | missingArtifactCount | Integer | The number of required Artifacts that have not been collected for a Case’s Tasks |
| Case | name | String | The name of a Case Note If querying for Cases with a name that contains a backslash character (\), use a double backslash (\\) in the query to escape the single backslash. For more information, see the “Workflow-Related Queries” section of Constructing Query Expressions. |
| Case | owner | Integer | The ID number for the owner of a Case |
| Case | ownerName | String | The name of the owner of a Case |
| Case | resolution | String | The resolution of a Case |
| Case | responseDue | DateTime | The SLA response due date for a Case |
| Case | responseOverdue | Boolean | A flag indicating whether a Case exceeded the allowed completion time for its SLA response due date |
| Case | severity | Enum | The severity of a Case |
| Case | status | Enum | The status of a Case |
| Case | tag | String | The name of a Tag applied to a Case |
| Case | targetId | Integer | The user or user group ID number for a Case assignee |
| Case | targetType | Enum | The target type for a Case (either User or Group) |
| Case | threatAssessScore | Integer | The ThreatAssess score of a Case (i.e., the highest ThreatAssess score among the Case’s Artifacts with a ThreatAssess score) |
| Case | timeToDetect | Integer | The amount of time, in seconds, it took to either detect a security incident or threat after it occurred or open a Case for a security incident or threat after it was detected |
| Case | timeToRespond | Integer | The amount of time, in seconds, it took to respond to a security incident or threat after it was detected |
| Case | typeName | String | The name of a Case |
| Case | xid | String | The XID of a Case |
Case Attributes
Table 15 provides the TQL parameters available for Case Attributes.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| CaseAttribute | caseId | Integer | The ID number of a Case to which the Attribute is added |
| CaseAttribute | dateAdded | DateTime | The date and time the Attribute was created |
| CaseAttribute | dateVal | DateTime | The date value of an Attribute (applies only to certain Attribute Types) |
| CaseAttribute | displayed | Boolean | A flag indicating whether the Attribute is displayed in a Case |
| CaseAttribute | hasCase() | Nested Query | A nested query for association to other Cases |
| CaseAttribute | id | Integer | The ID number of an Attribute |
| CaseAttribute | intVal | Integer | The integer value of an Attribute (applies only to certain Attribute Types) |
| CaseAttribute | lastModified | DateTime | The date and time an Attribute was last modified |
| CaseAttribute | maxSize | Integer | The maximum length of an Attribute’s text |
| CaseAttribute | owner | Integer | The ID of the owner in which an Attribute exists |
| CaseAttribute | ownerName | String | The name of the owner in which an Attribute exists |
| CaseAttribute | shortText | String | The short text of an Attribute (applies only to certain Attribute Types) |
| CaseAttribute | source | String | An Attribute’s source |
| CaseAttribute | text | String | The text of an Attribute (applies only to certain Attribute Types) |
| CaseAttribute | type | Integer | The ID number of an Attribute’s Type |
| CaseAttribute | typeName | String | The name of an Attribute’s Type |
| CaseAttribute | user | String | The username of the user who created an Attribute |
Case Notes
Table 16 provides the TQL parameters available for Case Notes.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| Case Note | artifactId | Integer | The ID number of an Artifact with which a Case Note is associated |
| Case Note | author | User | The account login of a user who wrote a Case Note |
| Case Note | caseId | Integer | The ID number of a Case with which a Case Note is associated |
| Case Note | data | String | The contents of a Case Note |
| Case Note | dateAdded | DateTime | The date and time a Case Note was created |
| Case Note | hasArtifact() | Nested Query | A nested query for association to Artifacts |
| Case Note | hasCase() | Nested Query | A nested query for association to Cases |
| Case Note | hasTask() | Nested Query | A nested query for association to Tasks |
| Case Note | id | Integer | The ID number of a Case Note |
| Case Note | lastModified | DateTime | The date and time a Case Note was last modified |
| Case Note | summary | String | Text of the first 100 characters of a Case Note |
| Case Note | taskId | Integer | The ID number of a Task with which a Case Note is associated |
| Case Note | workflowEventId | Integer | The ID number of a Workflow Timeline event with which a Case Note is associated |
Tasks
Table 17 provides the TQL parameters available for Tasks.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| Task | assignedToUserOrGroup | Enum | The type of Task assignee (either User or Group) |
| Task | assigneeName | String | The name of the user or user group assigned to the Task |
| Task | automated | Boolean | A flag indicating whether a Task is automated |
| Task | caseId | Integer | The ID number of a Case with which a Task is associated |
| Task | caseIdAsString | String | The ID number of a Case as a String |
| Task | caseSeverity | Enum | The severity of a Case associated with a Task |
| Task | completedBy | User | The username of a user who completed a Task |
| Task | completedDate | DateTime | The date and time a Task was completed |
| Task | description | String | The description of a Task |
| Task | dueDate | DateTime | The due date for a Task |
| Task | hasArtifact() | Nested Query | A nested query for association to other Artifacts |
| Task | hasCase() | Nested Query | A nested query for association to other Cases |
| Task | hasNote() | Nested Query | A nested query for association to other Case Notes |
| Task | id | Integer | The ID number of a Task |
| Task | missingArtifactCount | Integer | The number of required Artifacts that have not been collected for a Task |
| Task | name | String | The name of a Task |
| Task | owner | Integer | The ID of the owner in which a Task exists |
| Task | ownerName | String | The name of the owner in which a Task exists |
| Task | required | Boolean | A flag indicating whether a Task is required or not |
| Task | status | Enum | The status of a Task |
| Task | targetId | Long | The user or user group ID number for a Task assignee |
| Task | targetType | Enum | The target type for a Task (either User or Group) |
| Task | workflowPhase | Integer | The Workflow Phase of a Task |
| Task | workflowStep | Integer | The Workflow step of a Task |
| Task | xid | String | The XID of a Task |
Workflow Events
Table 18 provides the TQL parameters available for Workflow Events (i.e., Timeline Events).
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| WorkflowEvent | caseId | Integer | The ID number of a Case with which a Timeline Event is associated |
| WorkflowEvent | dateAdded | DateTime | The date and time a Timeline Event was added |
| WorkflowEvent | deleted | Boolean | The deletion status of a Timeline Event |
| WorkflowEvent | deletedReason | String | The reason a Timeline Event was deleted |
| WorkflowEvent | eventDate | DateTime | The date and time a Timeline Event occurred |
| WorkflowEvent | id | Integer | The ID number of a Timeline Event |
| WorkflowEvent | link | StringUpper | The item to which a Timeline Event pertains, in format <type>:<id> |
| WorkflowEvent | summary | String | The text of a Timeline Event |
| WorkflowEvent | systemGenerated | Boolean | Flag determining whether a Timeline Event was created automatically by the system |
| WorkflowEvent | userName | String | The username associated with a Timeline Event |
Workflow Templates
Table 19 provides the TQL parameters available for Workflow Templates.
| Workflow Type | Parameter | Data Type | Description |
|---|---|---|---|
| WorkflowTemplate | active | Boolean | The active status of a Workflow Template |
| WorkflowTemplate | description | String | The description of a Workflow Template |
| WorkflowTemplate | id | Integer | The ID number of a Workflow Template |
| WorkflowTemplate | name | String | The name of a Workflow Template |
| WorkflowTemplate | owner | Integer | The ID of the owner in which a Workflow Template exists |
| WorkflowTemplate | ownerName | String | The name of the owner in which a Workflow Template exists |
| WorkflowTemplate | targetId | Integer | The user or user group ID for the default assignee for a Workflow Template |
| WorkflowTemplate | targetType | Enum | The target type for a Workflow Template (either User or Group) |
| WorkflowTemplate | version | Integer | The version of a Workflow Template |
General Parameters
The following subsections describe all the general TQL parameters available in ThreatConnect.
Attribute Types
Table 20 provides the TQL parameters available for Attribute Types.
| Object Type | Parameter | Data Type | Description |
|---|---|---|---|
| AttributeType | associatedType | String | The data type(s) for which an Attribute Type can be used |
| AttributeType | default | Boolean | A flag designating whether the Attribute Type is a default Attribute Type |
| AttributeType | defaultOwnerId | Integer | The ID number of the owner in which an Attribute Preference is configured for the Attribute Type |
| AttributeType | description | String | The description of an Attribute Type |
| AttributeType | id | Integer | The ID number of an Attribute Type |
| AttributeType | maxsize | Integer | The maximum size, in characters, of an Attribute Type’s value. |
| AttributeType | name | String | The name of an Attribute Type |
| AttributeType | owner | Integer | The ID number for the owner of an Attribute Type |
| AttributeType | ownerName | String | The name of the owner of an Attribute Type |
| AttributeType | system | Boolean | A flag designating whether to show System-level Attributes (TRUE) or owner-specific Attributes only (FALSE) |
Indicator Exclusion Lists
Table 21 provides the TQL parameters available for Indicator Exclusion Lists.
Important
Querying for Indicator Exclusion Lists with TQL is available only in the ThreatConnect v3 API.
| Object Type | Parameter | Data Type | Description |
|---|---|---|---|
| IndicatorExclusionLists | active | Boolean | Specifies whether an Indicator Exclusion List is active |
| IndicatorExclusionLists | id | Integer | The ID number of an Indicator Exclusion List |
| IndicatorExclusionLists | managed | Boolean | Specifies whether an Indicator Exclusion List is a non-custom, default Exclusion List managed at the System level |
| IndicatorExclusionLists | name | String | The name of an Indicator Exclusion List |
| IndicatorExclusionLists | owner | String | The ID number of the owner to which an owner-level Indicator Exclusion List applies |
Posts
Table 22 provides the TQL parameters available for posts (Notes).
Important
Querying for posts with TQL is available only in the ThreatConnect v3 API.
| Object Type | Parameter | Data Type | Description |
|---|---|---|---|
| Posts | dateAdded | DateTime | The date and time the post was created |
| Posts | dateModified | DateTime | The date and time the post was last modified |
| Posts | id | Integer | The ID number of the post |
| Posts | objectId | String | The type and ID combination of the object that the post is added to (e.g., B12345) Acceptable type identifiers:
|
| Posts | text | String | The contents of the post |
ThreatConnect® is a registered trademark, and CAL™ is a trademark, of ThreatConnect, Inc.
DomainTools® is a registered trademark of DomainTools, LLC.
VirusTotal™ is a trademark of Google, Inc.
MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.
20052-04 v.28.A