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 the field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/indicators

Note

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

Alternatively, refer to the following tables 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
associatedGroups A list of Groups associated to the Indicator String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
attributes A list of Attributes corresponding to the Indicator String 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”]}}
description The Indicator’s Description String FALSE TRUE “Potentially malicious host related to malware dissemination.”
ownerName The name of the Organization, Community, or Source to which the Indicator belongs String FALSE FALSE “Demo Community”
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 String FALSE TRUE {“data”: [{“name”: “TLP:AMBER”}]}
source The Indicator’s Source String FALSE TRUE “Host used by hacker conglomerate tracked to Iran”
tags A list of Tags applied to the Indicator String FALSE TRUE {“data”: [{“name”: “Targeted Attack”}]}
type The type of Indicator being created String TRUE FALSE “Address”, “Host”, “Registry Key”

Available 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

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?
hostName The host name associated with the Host Indicator String TRUE FALSE
dnsActive Indicates whether the DNS feature is active for the Host Indicator Boolean FALSE TRUE
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

Available 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 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 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,
    "description": "Potentially malicious host related to malware dissemination.",
    "privateFlag": false,
    "rating": 5,
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "source": "A Reliable Source",
    "tags": {"data": [{"name": "Targeted Attack"}, {"name": "Malicious Host"}]}
}

JSON Response

{
    "data": {
        "id": 4,
        "type": "Host",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "/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"
            }],
            "count": 2
        },
        "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"
            }],
            "count": 1
        },
        "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,
        "associatedGroups": {
            "data": [{
                "id": 15,
                "type": "Adversary",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "/auth/adversary/adversary.xhtml?adversary=15",
                "name": "Bad Guy",
                "createdBy": "John Smith"
            }, {
                "id": 12,
                "type": "Incident",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-08-27T12:16:56Z",
                "webLink": "/auth/incident/incident.xhtml?incident=12",
                "name": "Dangerous Incident",
                "createdBy": "Pat Jones"
            }],
            "count": 2
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "/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
            }],
            "count": 1
        },
        "attributes": {
            "data": [{
                "id": 88842457,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 371,
                    "userName": "89474115115672885137",
                    "firstName": "j",
                    "lastName": "smith",
                    "pseudonym": "APIUsergj03B"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }],
            "count": 1
        },
        "hostName": "ultrabadguy.com",
        "dnsActive": true,
        "whoisActive": true
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating an Indicator, you can apply Tags that do not yet exist in ThreatConnect to it. In this scenario, you would need to 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 Groups that do not yet exist in ThreatConnect to the Indicator. In this scenario, you would need to fill out all required fields for the type of Group being associated to the Indicator. Upon creation of the new Indicator, any associated 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,
        "type": "File",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-02T13:07:08Z",
        "webLink": "/auth/indicators/details/file.xhtml?file=F5A2496CF66CB8CFFE66CB1B27D7DEDE",
        "lastModified": "2021-11-02T14:04:55Z",
        "summary": "F5A2496CF66CB8CFFE66CB1B27D7DEDE",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "md5": "F5A2496CF66CB8CFFE66CB1B27D7DEDE"
    },
    {
        "id": 9,
        "type": "EmailAddress",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-02T12:34:03Z",
        "webLink": "/auth/indicators/details/emailaddress.xhtml?emailaddress=badguy%40bad.com",
        "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,
        "type": "Host",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-10-26T12:40:00Z",
        "webLink": "/auth/indicators/details/host.xhtml?host=badguy.com",
        "lastModified": "2021-11-02T14:58:55Z",
        "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": [{
        "type": "URL",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-02T15:17:28Z",
        "summary": "http://badsite.com"
    }],
    "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 provided 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 included in the body of a PUT request for the indicators object.

Note

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

  • 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
  • Disassociate the Bad Guy Adversary Group from the Indicator
  • Update the Indicator’s Confidence Rating
  • Replace a TLP: AMBER Security Label that is 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"},
    "attributes": {"data": [{"type": "Additional Analysis and Context", "value": "This host is very dangerous", "source": "Phase of Intrusion"}]},
    "confidence": 92,
    "securityLabels": {"data": [{"name": "TLP:RED"}], "mode": "replace"},
    "tags": {"data": [{"name": "Russia"}], "mode": "append"}
}

JSON Response

{
    "data": {
        "id": 4,
        "type": "Host",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "/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"
            }],
            "count": 3
        },
        "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"
            }],
            "count": 1
        },
        "lastModified": "2021-11-05T17:21:06Z",
        "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,
        "associatedGroups": {
            "data": [{
                "id": 12,
                "type": "Incident",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-08-27T12:16:56Z",
                "webLink": "/auth/incident/incident.xhtml?incident=12",
                "name": "Dangerous Incident",
                "createdBy": "Pat Jones"
            }],
            "count": 1
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "/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
            }],
            "count": 1
        },
        "attributes": {
            "data": [{
                "id": 88842457,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 371,
                    "userName": "89474115115672885137",
                    "firstName": "j",
                    "lastName": "smith",
                    "pseudonym": "APIUsergj03B"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }],
            "count": 1
        },
        "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