TQL Operators and Parameters
- 24 Aug 2023
- 8 Minutes to read
-
Print
-
DarkLight
TQL Operators and Parameters
- Updated on 24 Aug 2023
- 8 Minutes to read
-
Print
-
DarkLight
Article Summary
Share feedback
Thanks for sharing your feedback!
Operators
Table 1 provides a list of all ThreatConnect Query Language (TQL) operators in all of their acceptable forms.
| Operators |
|---|
| =, ==, EQ, EQUALS |
| !=, NE |
| >, GT |
| <, LT |
| <=, LEQ |
| >=, GEQ |
| [NOT] IN |
| [NOT] LIKE |
| [NOT] CONTAINS |
| [NOT] STARTSWITH |
| [NOT] ENDSWITH |
General Parameters
Table 2 provides all of the general TQL parameters, including their corresponding ThreatConnect object type and data type.
Note
It is recommended to use ISO-8601-compliant formatting for TQL parameters with Date or Datetime data types.
| Object Type | Parameter | Data Type | Comments |
|---|---|---|---|
| Groups | associatedGroupSource | String | Accepted values:
|
| Groups | associatedIndicator | Integer | Deprecated by nested query; equivalent to hasIndicator(id=n) |
| Groups | associatedIndicatorSource | String | Accepted values:
|
| 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 | Date | |
| Groups | documentDateAdded | Date | |
| Groups | documentFilename | String | |
| Groups | documentFilesize | Long | |
| Groups | documentStatus | String | |
| Groups | documentType | String | |
| Groups | downvoteCount | Integer | |
| Groups | emailDate | Date | |
| Groups | emailFrom | String | |
| Groups | emailScore | Integer | |
| Groups | emailScoreIncludesBody | Boolean | |
| Groups | emailSubject | String | |
| Groups | eventDate | Date | |
| Groups | generatedReport | Boolean | Returns Report Groups that were created using the Publish Report feature in the Report Editor |
| Groups | hasArtifact() | Nested Query | |
| Groups | hasAttribute() | Nested Query | |
| Groups | hasCase() | Nested Query | |
| Groups | hasGroup() | Nested Query | |
| Groups | hasIndicator() | Nested Query | |
| Groups | hasSecurityLabel() | Nested Query | |
| Groups | hasTag() | Nested Query | |
| Groups | hasVictim() | Nested Query | |
| Groups | hasVictimAsset() | Nested Query | |
| Groups | id | Integer | |
| Groups | lastModified | DateTime | |
| Groups | owner | Integer | |
| Groups | ownerName | String | |
| Groups | securityLabel | String | |
| Groups | signatureDateAdded | Date | |
| 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 | Date | |
| Groups | taskDueDate | Date | |
| Groups | taskEscalated | Boolean | |
| Groups | taskEscalationDate | Date | |
| Groups | taskLastModified | Date | |
| Groups | taskOverdue | Boolean | |
| Groups | taskReminded | Boolean | |
| Groups | taskReminderDate | Date | |
| Groups | taskStatus | String | |
| Groups | type | Integer | |
| Groups | typeName | String | |
| Groups | upvoteCount | Integer | |
| Groups | victimAsset | String | Deprecated by nested query; equivalent to hasVictimAsset(name="") |
| 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 | Accepted values:
|
| Indicators | associatedIndicatorSource | String | Accepted values:
|
| Indicators | attributeNN | Dependent | See the “Query for Attributes” section of Constructing Query Expressions for more information. |
| Indicators | confidence | Integer | |
| Indicators | dateAdded | DateTime | Accepted formats: yyyy-MM-dd HH:mm yyyy-MM-dd MM-dd-yyyy |
| Indicators | description | String | |
| Indicators | falsePositiveCount | String | |
| Indicators | fileName | String | |
| Indicators | filePath | String | |
| Indicators | fileSize | BigInteger | |
| Indicators | hasArtifact() | Nested Query | |
| Indicators | hasAttribute() | Nested Query | |
| Indicators | hasCase() | Nested Query | |
| Indicators | hasGroup() | Nested Query | |
| Indicators | hasIndicator() | 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 | |
| Indicators | indicatorActive | Boolean | |
| Indicators | lastFalsePositive | Date | |
| Indicators | lastModified | DateTime | |
| Indicators | lastObserved | DateTime | |
| Indicators | observationCount | Integer | |
| Indicators | owner | Integer | |
| Indicators | ownerName | String | |
| Indicators | rating | Integer | |
| 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 | 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) |
| 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 | hasCase() | Nested Query | |
| Tags | hasGroup() | Nested Query | |
| Tags | hasIndicator() | Nested Query | |
| Tags | hasVictim() | Nested Query | |
| Tags | id | Integer | |
| Tags | lastUsed | Date | |
| Tags | name | String | |
| 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 | summary | String | |
| 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. |
| Tracks | active | Boolean | |
| Tracks | associatedIndicator | Integer | Not deprecated, because Tracks are not part of the nested-query feature |
| Tracks | contains | String | |
| Tracks | dateAdded | Date | |
| Tracks | description | String | |
| Tracks | lastUpdated | Date | |
| Tracks | notContains | String | |
| Tracks | owner | Integer | |
| Tracks | ownerName | String | |
| Tracks | result | String | |
| Tracks | resultCount | Integer | |
| Tracks | resultDate | Date | |
| Tracks | summary | String | |
| 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 | 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 | attributeNN | Dependent | See the “Query for Attributes” section of Constructing Query Expressions for more information. |
| Victims | description | String | |
| 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 | |
| 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
Table 3 provides all of the Workflow-related TQL parameters, including their corresponding ThreatConnect Workflow type, data type, and a description.
Important
Workflow-related TQL parameters are available only in dashboard Query cards and the ThreatConnect v3 API. They are not available in the Browse screen.
Note
It is recommended to use ISO-8601-compliant formatting for TQL parameters with Date or Datetime data types.
| 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 at which an Artifact was added to ThreatConnect |
| 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 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 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 |
| 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 |
| AttributeType | associatedType | String | The data type(s) for which an Attribute Type can be used |
| 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) |
| 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 | attribute | String | An Attribute corresponding to a Case |
| 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 | 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 on which a Case was added to ThreatConnect |
| Case | description | String | The description of a Case |
| 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 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 | 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 | 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 | typeName | String | The name of a Case |
| Case | xid | String | The XID of a Case |
| CaseAttribute | caseId | Integer | The ID number of a Case to which the Attribute is added |
| CaseAttribute | dateAdded | DateTime | The date on which the Attribute was added to the system |
| CaseAttribute | dateVal | DateTime | The date value of an Attribute (only applies 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 (only applies to certain Attribute Types) |
| CaseAttribute | lastModified | DateTime | The date when 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 | source | String | An Attribute’s source |
| CaseAttribute | text | String | The text of an Attribute (only applies 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 |
| Note | artifactId | Integer | The ID number of an Artifact with which a Note is associated |
| Note | author | User | The account login of a user who wrote a Note |
| Note | caseId | Integer | The ID number of a Case with which a Note is associated |
| Note | dateAdded | DateTime | The date on which a Note was written |
| Note | hasArtifact() | Nested Query | A nested query for association to Artifacts |
| Note | hasCase() | Nested Query | A nested query for association to Cases |
| Note | hasTask() | Nested Query | A nested query for association to Tasks |
| Note | id | Integer | The ID number of a Case |
| Note | lastModified | DateTime | The date on which a Note was last modified |
| Note | summary | String | Text of the first 100 characters of a Note |
| Note | taskId | Integer | The ID number of a Task with which a Note is associated |
| Note | workflowEventId | Integer | The ID number of a Workflow Timeline event with which a Note is associated |
| 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 | Date | The completion date of a Task |
| Task | description | String | The description of a Task |
| Task | dueDate | Date | The due date of 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 Notes |
| Task | id | Integer | The ID number of 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 |
| WorkflowEvent | caseId | Integer | The ID number of a Case with which a Timeline event is associated |
| WorkflowEvent | dateAdded | DateTime | The date on which 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 on which 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 | 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 |
| 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 |
ThreatConnect® is a registered trademark of ThreatConnect, Inc.
VirusTotal™ is a trademark of Google, Inc.
MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.
20052-04 v.20.B
Was this article helpful?
