Tags¶
Tags add metadata, or keywords, to intelligence data and provide a way to quickly identify or follow associated activities of a particular interest across the entire ThreatConnect platform.
Retrieve Tags¶
Tag descriptions can be viewed using the following request:
GET /api/v2/tags?detailed=true
Filtering Tags¶
When retrieving Tags from ThreatConnect, it is possible to filter on the following data points:
Filter | Data Type | Operator(s) |
---|---|---|
name | string | = , ^ |
weight* | integer | = , < , > |
* In the context of Tags, ‘weight’ refers to how many times a Tag has been used.
Hint
The “^” character means “starts with”. For example, this character would be used to find all URL Indicators that start with http://xn--
or all Groups whose name starts with APT
.
Note
The =
, <
, >
, and ^
operators in any filters must be URL encoded as follows:
Character | URL Encoded Form |
---|---|
= | %3D |
< | %3C |
> | %3E |
^ | %5E |
The following query will return all Tags that start with “Bad” (name^Bad
):
GET /v2/tags/?filters=name%5EBad
The following query will return all Tags whose name is “Bad” (name=Bad
):
GET /v2/tags/?filters=name%3DBad
The following query will return all Tags with a weight greater than 2 (weight>2
):
GET /v2/tags/?filters=weight%3E2
Retrieve All Tags¶
To retrieve all tags, use the following query:
GET /v2/tags/
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"tag": [
{
"name": "Nation State",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=Nation+State&owner=Example+Organization"
},
{
"name": "Europe",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=Europe&owner=Example+Organization"
}
]
}
}
Retrieve a Single Tag¶
To retrieve a specific tag, use a query in the following format:
Introduction here
GET /v2/tags/{tagName}
For example, the following query will return information about the Nation State
tag:
GET /v2/tags/Nation%20State
JSON Response:
{
"status": "Success",
"data": {
"tag": {
"name": "Nation State",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=Nation+State&owner=Example+Organization"
}
}
}
Retrieve Tag Associations¶
Group to Tag Associations¶
To view Groups associated with a given Tag, use a query in the following format:
GET /v2/tags/{tagName}/groups
For example, the query below will retrieve all of the Groups associated with the Nation State
tag:
GET /v2/tags/Nation%20State/groups
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"group": [
{
"id": "54321",
"name": "IOCs_report_2017.doc",
"type": "Document",
"ownerName": "Example Organization",
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-13T17:51:17",
"webLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=54321"
}
]
}
}
You can also find associated Groups of a given type using the following format:
GET /v2/tags/{tagName}/groups/{associatedGroupType}
Replace {associatedGroupType}
with one of the following Group types:
adversaries
attackPatterns
campaigns
coursesOfAction
documents
emails
events
incidents
intrusionSets
malware
reports
signatures
tactics
threats
tools
vulnerabilities
For example, we could use the following query to find all Incidents associated with the Nation State
tag:
GET /v2/tags/Nation%20State/groups/incidents
We can also drill down even further by adding the ID of an associated Group to the end of the query such as:
GET /v2/tags/Nation%20State/groups/incidents/54321
Where 54321
is the ID of an Incident associated with the Nation State
tag.
Indicator to Tag Associations¶
To view Indicators associated with a given Tag, use a query in the following format:
GET /v2/tags/{tagName}/indicators
For example, the query below will retrieve all of the Indicators associated with the Nation State
tag:
GET /v2/tags/Nation%20State/indicators
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"indicator": [
{
"id": "54321",
"ownerName": "Example Organization",
"type": "Address",
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-20T15:43:09Z",
"threatAssessRating": 3.0,
"threatAssessConfidence": 75.0,
"threatAssessScore": 507,
"calScore": 181,
"calIndicatorStatus": 2,
"webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=0.0.0.0&owner=Example+Organization",
"summary": "0.0.0.0"
}
]
}
}
You can also find associated Indicators of a given type using the following format:
GET /v2/tags/{tagName}/indicators/{associatedIndicatorType}
For example, we could use the following query to find all Address Indicators associated with the Nation State
tag:
GET /v2/tags/Nation%20State/indicators/addresses
Victim to Tag Associations¶
To view Victims associated with a given Tag, use a query in the following format:
GET /v2/tags/{tagName}/victims
For example, the query below will retrieve all of the Victims associated with the Nation State
tag:
GET /v2/tags/Nation%20State/victims
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"victim": [
{
"id": "54321",
"name": "Bad Guy",
"org": "Example Organization",
"suborg": "",
"workLocation": "Washington D.C.",
"nationality": "",
"webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
}
]
}
}
We can also drill down even further by adding the ID of an associated Victim to the end of the query like:
GET /v2/tags/Nation%20State/victims/54321
Where 54321
is the ID of a Victim associated with the Nation State
tag.
Create Tags¶
To create a new Tag via API, simply add a Tag to a Group, Indicator, Task, or Victim and the new Tag will be created.
Tag descriptions can be written with the following request:
POST /api/v2/tags
{
"name": "Phishing",
"description": "Apply this Tag to objects related to phishing attacks."
}
Response:
{
"status": "Success",
"data": {
"tag": {
"name": "Phishing",
"description": "Apply this Tag to objects related to phishing attacks.",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=12346&owner=Example+Organization"
}
}
}
A Tag’s name and description can be edited as follows:
PUT /api/v2/tags/Phishing
{
"name": "Phishing Attack",
"description": "Apply this Tag to Indicators and Groups related to phishing attacks. Do not apply it to Victims."
}
For more details, see:
Delete Tags¶
To delete a Tag, use the query format below:
DELETE /v2/tags/{tagName}
For example, the following query will delete the Nation State
Tag:
DELETE /v2/tags/Nation State
JSON Response:
{
"status": "Success"
}
Deleting a Tag via the API removes that Tag from all Groups, Indicators, and Victims that had the deleted Tag.