Indicators

An Indicator represents an atomic piece of information that has some intelligence value. Indicators are guaranteed to be unique within an Owner. For example, a single Organization can have only one copy of the Indicator badguy@bad.com.

Endpoint: /api/v3/indicators

Available Fields

You can retrieve a list of available fields for the /v3/indicators endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/indicators

Hint

To view all fields, including read-only fields, include the ?show=readonly query parameter.

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 for all Indicator types.

Field Description Type Required for Creation? Updatable? Example Value(s)
active Indicates whether the Indicator is active Boolean FALSE TRUE true, false
activeLocked Indicates whether the active Indicator Status is locked Boolean FALSE TRUE true, false
associatedArtifacts A list of Artifacts associated to the Indicator Artifact Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}
associatedCases A list of Cases associated to the Indicator Case Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}}
associatedGroups A list of Groups associated to the Indicator Group Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
attributes A list of Attributes corresponding to the Indicator Indicator Attribute Object FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}}
confidence The Indicator’s Confidence Rating Integer FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}}
privateFlag Indicates where the Indicator is private Boolean FALSE TRUE true, false
rating The Indicator’s Threat Rating Big Decimal FALSE TRUE 1.0, 2.0, 3.0, 4.0, 5.0
securityLabels A list of Security Labels applied to the Indicator Security Label Object FALSE TRUE {“data”: [{“name”: “TLP:AMBER”}]}
tags A list of Tags applied to the Indicator Tag Object FALSE TRUE {“data”: [{“name”: “Targeted Attack”}]}
type The type of Indicator being created String TRUE FALSE “Address”, “Host”, “Registry Key”

Accepted values for the type field include:

  • Address
  • EmailAddress
  • File
  • Host
  • URL
  • ASN
  • CIDR
  • EmailSubject
  • Hashtag
  • Mutex
  • Registry Key
  • User Agent

Note

A list of available Attribute Types can be retrieved with the following query:

GET /v3/attributeTypes

Hint

To associate an existing Artifact, Case, or Group to an Indicator, use the object’s ID when setting the associatedArtifacts, associatedCases, or associatedGroups field, respectively (e.g., {"data": [{"id": 12345}]}).

Indicator-Specific Fields

Based on the type of Indicator being created, you may need to include additional fields in the body of a POST request. Similarly, some Indicator types include additional fields that may be updated via a PUT request.

The following tables list valid fields, some of which are required, that can be included in the body of a POST or PUT request for each Indicator type.

Address

Field Description Type Required for Creation? Updatable?
ip The IP address associated with the Address Indicator String TRUE FALSE

EmailAddress

Field Description Type Required for Creation? Updatable?
address The email address associated with the Email Address Indicator String TRUE FALSE

File

Field Description Type Required for Creation? Updatable?
md5 The MD5 hash associated with the File Indicator String TRUE* FALSE
sha1 The SHA1 hash associated with the File Indicator String TRUE* FALSE
sha256 The SHA256 hash associated with the File Indicator String TRUE* FALSE
size The size of the file associated with the File Indicator String FALSE TRUE

Note

*When creating a File Indicator, you must include at least one valid hash.

Host

Field Description Type Required for Creation? Updatable?
dnsActive Indicates whether the DNS feature is active for the Host Indicator Boolean FALSE TRUE
hostName The host name associated with the Host Indicator String TRUE FALSE
whoisActive Indicates whether the Whois feature is active for the Host Indicator Boolean FALSE TRUE

URL

Field Description Type Required for Creation? Updatable?
text The URL associated with the URL Indicator String TRUE FALSE

ASN

Field Description Type Required for Creation? Updatable?
AS Number The AS number associated with the ASN Indicator String TRUE FALSE

CIDR

Field Description Type Required for Creation? Updatable?
Block The block of network IP addresses associated with the CIDR Indicator String TRUE FALSE

EmailSubject

Field Description Type Required for Creation? Updatable?
Subject The subject line of the email associated with the Email Subject Indicator String TRUE FALSE

Hashtag

Field Description Type Required for Creation? Updatable?
Hashtag The hashtag term associated with the Hashtag Indicator String TRUE FALSE

Mutex

Field Description Type Required for Creation? Updatable?
Mutex The synchronization primitive used to identify malware files that is associated with the Mutex String TRUE FALSE

Registry Key

Field Description Type Required for Creation? Updatable?
Key Name The name of the registry key associated with the Registry Key Indicator String TRUE FALSE
Value Name The registry value associated with the Registry Key Indicator String TRUE FALSE
Value Type The registry value type associated with the Registry Key Indicator String TRUE FALSE

Accepted values for the Value Type field include:

  • REG_NONE
  • REG_BINARY
  • REG_DWORD
  • REG_DWORD_LITTLE_ENDIAN
  • REG_DWORD_BIG_ENDIAN
  • REG_EXPAND_SZ
  • REG_LINK
  • REG_MULTI_SZ
  • REG_QWORD
  • REG_QWORD_LITTLE_ENDIAN
  • REG_SZ

User Agent

Field Description Type Required for Creation? Updatable?
User Agent String The characteristic identification string associated with the User Agent Indicator String TRUE FALSE

Create Indicators

The basic format for creating an Indicator is:

POST /v3/indicators
{
    "type": "Indicator type goes here",
    //required fields for the selected Indicator type
}

Refer to the Available Fields and Indicator-Specific Fields sections for a list of available fields that can be included in the body of a POST request for the indicators object.

Note

You can add multiple Attributes, Tags, and Security Labels to the Indicator being created in a single POST request. Similarly, you can associate multiple Artifacts, Cases, and Groups to the Indicator being created in a single POST request.

Example POST Request

The following query will create a Host Indicator with a host name of ultrabadguy.com. Note that all optional fields available for the indicators object are included in this request.

POST /v3/indicators
{
    "type": "Host",
    "hostName": "ultrabadguy.com",
    "dnsActive": true,
    "whoisActive": true,
    "active": true,
    "activeLocked": false,
    "associatedGroups": {"data": [{"id": 12}, {"name": "Bad Guy", "type": "Adversary"}]},
    "attributes": {"data": [{"type": "Additional Analysis and Context", "value": "This host is very dangerous", "source": "Phase of Intrusion"}]},
    "confidence": 85,
    "privateFlag": false,
    "rating": 5,
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "tags": {"data": [{"name": "Targeted Attack"}, {"name": "Malicious Host"}]}
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
        "tags": {
            "data": [
                {
                    "id": 10,
                    "name": "Malicious Host",
                    "description": "A tag that can be applied to malicious Host Indicators.",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 11,
                    "name": "Targeted Attack",
                    "lastUsed": "2021-11-05T16:43:17Z"
                }
            ]
        },
        "securityLabels": {
            "data": [{
                "id": 3,
                "name": "TLP:AMBER",
                "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
                "color": "FFC000",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "type": "Host",
        "lastModified": "2021-11-05T16:43:17Z",
        "rating": 5.0,
        "confidence": 85,
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {
            "data": [
                {
                    "id": 15,
                    "type": "Adversary",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-11-05T16:43:17Z",
                    "webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=15",
                    "name": "Bad Guy",
                    "createdBy": {
                        "id": 3,
                        "userName": "11112222333344445555",
                        "firstName": "John",
                        "lastName": "Smith",
                        "pseudonym": "jsmithAPI",
                        "role": "Api User"
                    }
                },
                {
                    "id": 12,
                    "type": "Incident",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-08-27T12:16:56Z",
                    "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12",
                    "name": "Dangerous Incident",
                    "createdBy": {
                        "id": 1,
                        "userName": "[email protected]",
                        "firstName": "John",
                        "lastName": "Smith",
                        "pseudonym": "JMS",
                        "role": "Administrator"
                    }
                }
            ]
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                "lastModified": "2021-11-05T16:43:17Z",
                "rating": 5.0,
                "confidence": 85,
                "source": "A Reliable Source",
                "description": "Potentially malicious host related to malware dissemination.",
                "summary": "ultrabadguy.com",
                "privateFlag": false,
                "active": true,
                "activeLocked": false,
                "hostName": "ultrabadguy.com",
                "dnsActive": true,
                "whoisActive": true
            }]
        },
        "attributes": {
            "data": [{
                "id": 24,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }]
        },
        "associatedCases": {},
        "associatedArtifacts": {},
        "hostName": "ultrabadguy.com",
        "dnsActive": true,
        "whoisActive": true
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating or updating an Indicator, you can apply Tags that do not yet exist in ThreatConnect to it. To do so, fill out all required fields for each new Tag. Upon creation of the new Indicator, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Similarly, you can associate Artifacts, Cases, and Groups that do not yet exist in ThreatConnect to the Indicator. To do so, fill out all required fields for the type of object being associated to the Indicator. Upon creation of the new Indicator, any associated Artifacts, Cases, or Groups included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Retrieve Indicators

Retrieve All Indicators

To retrieve all Indicators, use the following query:

GET /v3/indicators

JSON Response

{
    "data": [
        {
            "id": 10,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T13:07:08Z",
            "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "type": "File",
            "lastModified": "2021-11-02T14:04:55Z",
            "summary": "F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "privateFlag": false,
            "active": true,
            "activeLocked": false,
            "md5": "F5A2496CF66CB8CFFE66CB1B27D7DEDE"
        },
        {
            "id": 9,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T12:34:03Z",
            "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=badguy%40bad.com",
            "type": "EmailAddress",
            "lastModified": "2021-11-02T12:48:51Z",
            "description": "A bad email address",
            "summary": "[email protected]",
            "privateFlag": false,
            "active": true,
            "activeLocked": false,
            "address": "[email protected]"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Indicator

Specific Indicators can be retrieved by either their ID or summary. The basic format for retrieving an Indicator is:

GET /v3/indicators/{indicatorId or indicatorSummary}

For example, the following query will return information about the Indicator with ID 3:

GET /v3/indicators/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-10-26T12:40:00Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=badguy.com",
        "type": "Host",
        "lastModified": "2021-11-02T14:58:55Z",
        "rating": 3.00,
        "confidence": 74,
        "description": "A bad host.",
        "summary": "badguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "hostName": "badguy.com",
        "dnsActive": true,
        "whoisActive": false
    },
    "status": "Success"
}

The same response would be returned if we used the following request, where the Indicator’s ID is replaced with its summary:

GET /v3/indicators/badguy.com

Retrieve Deleted Indicators

To retrieve Indicators that have been recently deleted from an owner, use the following query:

GET /v3/indicators/deleted

JSON Response

{
    "data": [
        {
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T15:17:28Z",
            "type": "URL",
            "summary": "http://badsite.com"
        }
    ],
    "count": 1,
    "status": "Success"
}

By default, this query will return all Indicators recently deleted in the API key’s default Organization. You can specify a different owner by including the ?owner= query parameter in your query.

Note

The indicatorDeleteRetentionTime system setting determines the number of days to retain deleted Indicators.

Request Additional Fields

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Indicators

The basic format for updating an Indicator is:

PUT /v3/indicators/{indicatorId or indicatorSummary}
{
    {updatedField}: {updatedValue}
}

Refer to the Available Fields and Indicator-Specific Fields sections for a list of available fields that can be included in the body of a PUT request for the indicators object.

Hint

When updating an Indicator, you can use the mode field to add or remove the following metadata:

  • associatedArtifacts
  • associatedCases
  • associatedGroups
  • attributes
  • securityLabels
  • tags

See Update an Object’s Metadata for instructions on using the mode field.

Example PUT Request

The following query will complete the following actions for the ultrabadguy.com Host Indicator:

  • Disable the DNS feature for the Indicator
  • Dissociate the Bad Guy Adversary Group from the Indicator
  • Update the Indicator’s Confidence Rating
  • Replace an existing Security Label applied to the Indicator with a TLP: Red Security Label
  • Apply a new Russia Tag to the Indicator without replacing any existing Tags applied to the Indicator.
PUT /v3/indicators/ultrabadguy.com
{
    "dnsActive": false,
    "associatedGroups": {"id": 15}], "mode": "delete"},
    "confidence": 92,
    "securityLabels": {"data": [{"name": "TLP:RED"}], "mode": "replace"},
    "tags": {"data": [{"name": "Russia"}], "mode": "append"}
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
        "tags": {
            "data": [
                {
                    "id": 10,
                    "name": "Malicious Host",
                    "description": "A tag that can be applied to malicious Host Indicators.",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 11,
                    "name": "Targeted Attack",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 12,
                    "name": "Russia",
                    "lastUsed": "2021-11-05T17:21:07Z"
                }
            ]
        },
        "securityLabels": {
            "data": [{
                "id": 4,
                "name": "TLP:RED",
                "description": "This security label is used for information that cannot be effectively acted upon by additional parties, and could lead to impacts on a party's privacy, reputation, or operations if misused.",
                "color": "FF0033",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "lastModified": "2021-11-05T17:21:06Z",
        "type": "Host",
        "rating": 5.0,
        "confidence": 92,
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {
            "data": [{
                "id": 12,
                "type": "Incident",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-08-27T12:16:56Z",
                "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12",
                "name": "Dangerous Incident",
                "createdBy": {
                    "id": 1,
                    "userName": "[email protected]",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "JMS",
                    "role": "Administrator"
                }
            }]
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                "lastModified": "2021-11-05T17:21:07Z",
                "rating": 5.0,
                "confidence": 92,
                "source": "A Reliable Source",
                "description": "Potentially malicious host related to malware dissemination.",
                "summary": "ultrabadguy.com",
                "privateFlag": false,
                "active": true,
                "activeLocked": false,
                "hostName": "ultrabadguy.com",
                "dnsActive": false,
                "whoisActive": true
            }]
        },
        "attributes": {
            "data": [{
                "id": 24,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }]
        },
        "associatedCases": {},
        "associatedArtifacts": {},
        "hostName": "ultrabadguy.com",
        "dnsActive": false,
        "whoisActive": true
    },
    "message": "Updated",
    "status": "Success"
}

Delete Indicators

The basic format for deleting an Indicator is:

DELETE /v3/indicators/{indicatorId or indicatorSummary}

For example, the following query will delete the Indicator with ID 3:

DELETE /v3/indicators/3

JSON Response

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

The same response would be returned if we used the following request, where the Indicator ID is replaced with the Indicator’s summary:

DELETE /v3/indicators/badguy.com