Tags¶

Tags add metadata, or keywords, to intelligence data and provides 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 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 State

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 State/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",
        "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
campaigns
documents
emails
events
incidents
intrusionSets
reports
signatures
threats

For example, we could use the following query to find all Incidents associated with the Nation State tag:

GET /v2/tags/Nation State/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 State/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 State/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,
        "threatAssessConfidence": 50,
        "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 State/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 State/victims

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "victim": [
      {
        "id": "54321",
        "name": "Bad Guy",
        "org": "Example Organization",
        "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 State/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": "myTag", "description": "my description" }

Response:

{
    "status": "Success",
        "data": {
             "tag": {
                "name": "myTag",
                "description": "my description",
                "webLink": "https://....com/auth/tags/tag.xhtml?tag=myTag\u0026owner=System"
            }
        }
}

Tag descriptions can be edited like:

PUT /api/v2/tags/myTag

{ "name": "myTag", "description": "new desc" }

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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

As you would likely expect, deleting a Tag via the API removes that Tag from all Groups, Indicators, and Victims which had the deleted Tag.