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:

• Adding Tags to Groups
• Adding Tags to Indicators
• Adding Tags to Tasks
• Adding Tags to Victims

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.