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 /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=12&owner=Example+Organization"
      },
      {
        "name": "Europe",
        "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=17&owner=Example+Organization"
      }
    ]
  }
}

Note

ATT&CK® Tags are not included in response returned for a GET /v2/tags request.

Retrieve a Single Tag

To retrieve a specific Tag, use a query in the following format:

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=12&owner=Example+Organization"
    }
  }
}

Attention

When retrieving a specific ATT&CK Tag, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to retrieve information about the T1566 - Phishing ATT&CK Tag, use Phishing as the Tag name in the query.

Retrieve Tag Associations

Attention

You cannot retrieve Indicators, Groups, or Victims associated to an ATT&CK Tag via the /v2/tags endpoint.

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/#/details/groups/54321/overview"
      }
    ]
  }
}

You can also retrieve 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, the following query will return all Incidents associated with the Nation State Tag:

GET /v2/tags/Nation%20State/groups/incidents

To retrieve a specific Incident associated with the Nation State Tag, include the ID of that Incident in the request URL:

GET /v2/tags/Nation%20State/groups/incidents/54321

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",
        "rating": 3.00,
        "confidence": 75,
        "threatAssessRating": 3.0,
        "threatAssessConfidence": 75.0,
        "threatAssessScore": 507,
        "calScore": 181,
        "calIndicatorStatus": 2,
        "webLink": "https://app.threatconnect.com/#/details/indicators/54321/overview&owner=Example+Organization",
        "summary": "0.0.0.0"
      }
    ]
  }
}

You can also retrieve associated Indicators of a given type using the following format:

GET /v2/tags/{tagName}/indicators/{associatedIndicatorType}

For example, the following query will return 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 return 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"
      }
    ]
  }
}

To retrieve a specific Victim associated with the Nation State Tag, include the ID of that Victim in the request URL:

GET /v2/tags/Nation%20State/victims/54321

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 /v2/tags

{
   "name": "Ransomware",
   "description": "Apply this Tag to objects related to ransomware attacks."
}

Response:

{
    "status": "Success",
        "data": {
             "tag": {
                "name": "Ransomware",
                "description": "Apply this Tag to objects related to ransomware 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 /v2/tags/Ransomware

{
   "name": "Ransomware Attack",
   "description": "Apply this Tag to Indicators and Groups related to ransomware attacks. Do not apply it to Victims."
}

For more details, see:

• Adding Tags to Groups

• Adding Tags to Indicators

• Adding Tags to Tasks

• Adding Tags to Victims

Attention

When applying ATT&CK Tags to an object, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to an object, use Phishing as the Tag name.

Also, if you applied a new Tag to an object and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to an object and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

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 to which the Tag was applied.