Tags

Tags can be used to add metadata, or keywords, to Groups, Indicators, Victims, and Workflow Cases. They provide a way to quickly identify or follow associated activities of a particular interest across ThreatConnect.

Endpoint: /api/v3/tags

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/tags endpoint:

OPTIONS /v3/tags

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request to the /v3/tags endpoint.

Field	Description	Type	Required for Creation?	Updatable?
description	The Tag’s description	String	FALSE	TRUE
name	The Tag’s name	String	TRUE	TRUE
owner	The Organization, Community, or Source to which the Tag belongs	String	FALSE	FALSE
securityCoverage	The security coverage level assigned to an ATT&CK® Tag (see the “Assign Security Coverage to ATT&CK Tags” section for more information)	Security Coverage Object	FALSE	TRUE

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/tags endpoint:

OPTIONS /v3/tags/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/tags endpoint:

OPTIONS /v3/tags/tql

Create Tags

The following example illustrates the basic format for creating a Tag:

POST /v3/tags
Content-Type: application/json

{
    "name": "Tag name goes here",
    "description": "Tag description goes here"
}

For example, the following request will create a Tag named Ransomware in your Organization:

POST /v3/tags
Content-Type: application/json

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

JSON Response

{
    "data": {
        "id": 1,
        "name": "Ransomware"",
        "owner": "Demo Organization",
        "description": "Apply this Tag to objects related to ransomware attacks.",
        "lastUsed": "2021-11-08T18:01:36Z"
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a POST request to the /v3/tags endpoint.

Attention

If you created a new Tag that 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 created a new Tag that matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Retrieve Tags

Retrieve All Tags

Send the following request to retrieve data for all system-generated ATT&CK Tags and Tags in your ThreatConnect owners:

GET /v3/tags

JSON Response

{
    "next": "https://app.threatconnect.com/api/v3/tags?resultStart=100&resultLimit=100",
    "data": [
        {
            "id": 1,
            "name": "Ransomware",
            "owner": "Demo Organization",
            "description": "Apply this Tag to objects related to ransomware attacks.",
            "lastUsed": "2021-11-08T18:01:36Z"
        },
        {
            "id": 2,
            "name": "Malicious Host",
            "owner": "Demo Organization",
            "lastUsed": "2021-11-14T13:54:20Z"
        },
        {
            "id": 3,
            "name": "Robbery",
            "owner": "Demo Community",
            "lastUsed": "2021-11-14T18:52:38Z"
        },
        {...},
        {
            "id": 100,
            "name": "Process Injection: Thread Local Storage",
            "description": "Adversaries may inject malicious code into processes via thread local storage (TLS) callbacks in order to evade process-based defenses as well as possibly elevate privileges. TLS callback injection is a method of executing arbitrary code in the address space of a separate live process. \n\nTLS callback injection involves manipulating pointers inside a portable executable (PE) to redirect a process to malicious code before reaching the code's legitimate entry point. TLS callbacks are normally used by the OS to setup and/or cleanup data used by threads. Manipulating TLS callbacks may be performed by allocating and writing to specific offsets within a process’ memory space using other [Process Injection](https://attack.mitre.org/techniques/T1055) techniques such as [Process Hollowing](https://attack.mitre.org/techniques/T1055/012).(Citation: FireEye TLS Nov 2017)\n\nRunning code in the context of another process may allow access to the process's memory, system/network resources, and possibly elevated privileges. Execution via TLS callback injection may also evade detection from security products since the execution is masked under a legitimate process. ",
            "lastUsed": "2023-06-05T19:39:45Z",
            "techniqueId": "T1055.005",
            "platforms": {
                "data": [
                    "Windows"
                ],
                "count": 1
            }
        }
    ],
    "status": "Success"
}

Hint

Use the owner query parameter to limit the results to a specific owner.

Retrieve a Specific Tag

Send a request in the following format to retrieve data for a specific Tag:

GET /v3/tags/{tagId}

For example, the following request will retrieve data for the Tag whose ID is 2:

GET /v3/tags/2

JSON Response

{
    "data": {
        "id": 2,
        "name": "Malicious Host",
        "owner": "Demo Organization",
        "lastUsed": "2021-11-14T13:54:20Z"
    },
    "status": "Success"
}

Retrieve Tags by Type

Retrieve Standard Tags

As of ThreatConnect version 7.2, the API response for a GET request to the /v3/tags endpoint will include standard Tags and system-generated ATT&CK® Tags (i.e., Tag objects that include the techniqueId field). A standard Tag is any Tag that is not an ATT&CK Tag.

To retrieve only standard Tags, send the following request:

Request (Decoded URL)

GET /v3/tags?tql=techniqueId is null

Request (Encoded URL)

GET /v3/tags?tql=techniqueId%20is%20null

Retrieve ATT&CK Tags

As of ThreatConnect version 7.2, the API response for a GET request to the /v3/tags endpoint will include standard Tags and system-generated ATT&CK Tags (i.e., Tag objects that include the techniqueId field). An ATT&CK Tag is a system-generated Tag representing a MITRE ATT&CK® Enterprise technique or sub-technique.

To retrieve only ATT&CK Tags, send the following request:

Request (Decoded URL)

GET /v3/tags?tql=techniqueId is not null

Request (Encoded URL)

GET /v3/tags?tql=techniqueId%20is%20not%20null

Retrieve Main Tags

As of ThreatConnect version 7.2, System Administrators can create Tag normalization rules that define one or more synonymous Tags that will be converted to a main Tag whenever they are applied to an object.

To retrieve only main Tags, send the following request:

Request (Decoded URL)

GET v3/tags?tql=normalized EQ true

Request (Encoded URL)

GET /v3/tags?tql=normalized%20EQ%20true

Note

This request will not return all main Tags defined within Tag normalization rules on your ThreatConnect instance; rather, it will only return those main Tags that have been created in one of your owners.

Update Tags

The following example illustrates the basic format for updating a Tag:

PUT /v3/tags/{tagId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will rename the Tag whose ID is 1 from Ransomware to Ransomware Attack:

PUT /v3/tags/1
Content-Type: application/json

{
    "name": "Ransomware Attack"
}

JSON Response

{
    "data": {
        "id": 1,
        "name": "Ransomware Attack",
        "owner": "Demo Organization",
        "description": "Apply this Tag to objects related to ransomware attacks.",
        "lastUsed": "2021-11-08T18:01:36Z"
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a PUT request to the /v3/tags endpoint.

Delete Tags

Send a request in the following format to delete a Tag:

DELETE /v3/tags/{tagId}

For example, the following request will delete the Tag whose ID is 1:

DELETE /v3/tags/1

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

Attention

Deleting a Tag will also remove the Tag from any objects to which it was applied.

Note

You cannot delete ATT&CK Tags.

Assign Security Coverage to ATT&CK Tags

Attention

Only API users with an Organization role of Organization Administrator can assign security coverage to ATT&CK Tags.

Send a request in the following format to update the security coverage assigned to an ATT&CK Tag:

PUT /v3/tags/{att&ckTagId}
Content-Type: application/json

{
    "securityCoverage": {
        "value": "<securityCoverageLevel>"
    }
}

securityCoverage: <Object> The details of the security coverage level assigned to the ATT&CK Tag.
- value: <String> The security coverage level assigned to the ATT&CK Tag. (Accepted values: None, Weak, Moderate, Strong)

For example, the following request will assign Weak coverage to the ATT&CK Tag whose ID is 750:

PUT /v3/tags/750
Content-Type: application/json

 {
     "securityCoverage": {
         "value": "Weak"
     }
 }

JSON Response

{
    "data": {
        "id": 750,
        "name": "Data Obfuscation",
        "description": "Adversaries may obfuscate command and control traffic to make it more difficult to detect. Command and control (C2) communications are hidden (but not necessarily encrypted) in an attempt to make the content more difficult to discover or decipher and to make the communication less conspicuous and hide commands from being seen. This encompasses many methods, such as adding junk data to protocol traffic, using steganography, or impersonating legitimate protocols. ",
        "lastUsed": "2023-07-28T17:32:32Z",
        "techniqueId": "T1001",
        "platforms": {
            "data": [
                "Linux",
                "macOS",
                "Windows"
            ],
            "count": 3
        },
        "securityCoverage": {
            "value": "Weak"
        }
    },
    "message": "Updated",
    "status": "Success"
}

MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.