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@example.com.

Note

When making requests for URL Indicators where the URL itself is included in the request (for example, when retrieving information about a specific URL), you will need to URL encode the Indicator. For example, the URL http://example.com/ must be encoded as http%3A%2F%2Fexample.com%2F before it is sent in a request.

Retrieve Indicators

Note

By default, all API branches return only active Indicators.

Filtering Indicators

Filter Parameters

When retrieving Indicators from ThreatConnect, it is possible to filter the results. Results can be filtered on the following data points:

Name

Data Type

Operator(s)

Indicator Common Filters

active

boolean

=

summary

string

=, ^

dateAdded

date

<, >

rating

bigdecimal

<, >

confidence

integer

=, <, >

threatAssessScore

integer

=, <, >

threatAssessRating

double

<, >

threatAssessConfidence

double

<, >

falsePositive

integer

=, <, >

Address Specific Filters

city

string

=

countryCode

string

=

countryName

string

=

organization

string

=

state

string

=

timezone

string

=

asn

integer

=

Host Specific Filters

whoisActive

boolean

=

dnsActive

boolean

=

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

Examples

The example below demonstrates the use of the active parameter, to retrieve both active and inactive indicators (with parameters OR’ed):

GET /v2/indicators?filters=active%3Dtrue,active%3Dfalse&orParams=true

The example below demonstrates usage of the summary parameter:

GET /v2/indicators?filters=summary%3Dexample.com

The example below demonstrates usage of the rating parameter:

GET /v2/indicators?filters=rating%3E3

The example below demonstrates usage of the threatAssessScore parameter:

GET /v2/indicators/?filters=threatAssessScore%3E450

The example below demonstrates usage of the threatAssessConfidence parameter:

GET /v2/indicators/urls?filters=threatAssessConfidence%3E50

The example below demonstrates usage of the organization parameter:

GET /v2/indicators/addresses?filters=organization%3Dmosso%20hosting

The example below demonstrates usage of the whoisActive parameter:

GET /v2/indicators/hosts?filters=whoisActive%3Dtrue

The example below demonstrates the use of multiple parameters (with implicit AND):

GET /v2/indicators?filters=summary%3Dexample.com,dateAdded%3C2015-10-15

The example below demonstrates the use of multiple parameters (with parameters OR’ed):

GET /v2/indicators?filters=summary%3Dexample.com,dateAdded%3E2015-10-15&orParams=true

The example below demonstrates how to filter based on the number of times an Indicator has been voted a False Positive:

GET /v2/indicators?filters=falsePositive%3E10

Owner Parameter

By default, all API calls will operate in the API user account’s default Organization. To specify a different Owner, use the owner URL parameter as in ?owner={ownerName}. For example, the following query will return all Host Indicators in the Common Community:

GET /v2/indicators/hosts/?owner=Common%20Community

Modified Since Parameter

To prevent the ThreatConnect API from returning an entire result set, limit the scope of the query based on the modifiedSince parameter. This query requires an ISO 8601 date-stamp (as shown in the examples below) and will only return Indicators whose lastModified field contains a value on or after the date specified.

The following actions update an Indicator’s lastModified field:

  • Creating the Indicator manually

  • Importing the Indicator via structured or unstructured import

  • Changing the Indicator’s threat rating

  • Changing the Indicator’s confidence rating.

The example below demonstrates the use of the modifiedSince parameter:

GET /v2/indicators?modifiedSince=2017-08-21T12:00:00Z

The example below demonstrates the use of the modifiedSince parameter and an additional parameter:

GET /v2/indicators?modifiedSince=2017-08-21T12:00:00Z&owner=Common%20Community

Retrieve Available Indicator Types

To find the available Indicator types on your instance of ThreatConnect, use the following query:

GET /v2/types/indicatorTypes

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 10,
    "indicatorType": [
      {
        "name": "Address",
        "custom": "false",
        "parsable": "true",
        "apiBranch": "addresses",
        "apiEntity": "address"
      },
      {
        "name": "EmailAddress",
        "custom": "false",
        "parsable": "true",
        "apiBranch": "emailAddresses",
        "apiEntity": "emailAddress"
      },
      {
        "name": "File",
        "custom": "false",
        "parsable": "true",
        "apiBranch": "files",
        "apiEntity": "file"
      },
      {
        "name": "Host",
        "custom": "false",
        "parsable": "true",
        "apiBranch": "hosts",
        "apiEntity": "host"
      },
      {
        "name": "URL",
        "custom": "false",
        "parsable": "true",
        "apiBranch": "urls",
        "apiEntity": "url"
      },
      {
        "name": "ASN",
        "custom": "true",
        "parsable": "true",
        "apiBranch": "asns",
        "apiEntity": "asn",
        "casePreference": "upper",
        "value1Label": "AS Number",
        "value1Type": "text",
        "value2Label": ""
      },
      {
        "name": "CIDR",
        "custom": "true",
        "parsable": "true",
        "apiBranch": "cidrBlocks",
        "apiEntity": "cidrBlock",
        "casePreference": "lower",
        "value1Label": "Block",
        "value1Type": "text",
        "value2Label": ""
      },
      {
        "name": "Mutex",
        "custom": "true",
        "parsable": "false",
        "apiBranch": "mutexes",
        "apiEntity": "mutex",
        "casePreference": "sensitive",
        "value1Label": "Mutex",
        "value1Type": "text",
        "value2Label": ""
      },
      {
        "name": "Registry Key",
        "custom": "true",
        "parsable": "false",
        "apiBranch": "registryKeys",
        "apiEntity": "registryKey",
        "casePreference": "sensitive",
        "value1Label": "Key Name",
        "value1Type": "text",
        "value2Label": "Value Name",
        "value2Type": "text"
      },
      {
        "name": "User Agent",
        "custom": "true",
        "parsable": "false",
        "apiBranch": "userAgents",
        "apiEntity": "userAgent",
        "casePreference": "sensitive",
        "value1Label": "User Agent String",
        "value1Type": "text",
        "value2Label": ""
      }
    ]
  }
}

XML Response:

<indicatorTypesResponse>
  <Status>Success</Status>
  <Data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="indicatorTypeListResponseData">
    <ResultCount>10</ResultCount>
    <IndicatorType>
      <Name>Address</Name>
      <Custom>false</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>addresses</ApiBranch>
      <ApiEntity>address</ApiEntity>
    </IndicatorType>
    <IndicatorType>
      <Name>EmailAddress</Name>
      <Custom>false</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>emailAddresses</ApiBranch>
      <ApiEntity>emailAddress</ApiEntity>
    </IndicatorType>
    <IndicatorType>
      <Name>File</Name>
      <Custom>false</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>files</ApiBranch>
      <ApiEntity>file</ApiEntity>
    </IndicatorType>
    <IndicatorType>
      <Name>Host</Name>
      <Custom>false</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>hosts</ApiBranch>
      <ApiEntity>host</ApiEntity>
    </IndicatorType>
    <IndicatorType>
      <Name>URL</Name>
      <Custom>false</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>urls</ApiBranch>
      <ApiEntity>url</ApiEntity>
    </IndicatorType>
    <IndicatorType>
      <Name>ASN</Name>
      <Custom>true</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>asns</ApiBranch>
      <ApiEntity>asn</ApiEntity>
      <casePreference>upper</casePreference>
      <value1Label>AS Number</value1Label>
      <value1Type>text</value1Type>
      <value2Label/>
    </IndicatorType>
    <IndicatorType>
      <Name>CIDR</Name>
      <Custom>true</Custom>
      <Parsable>true</Parsable>
      <ApiBranch>cidrBlocks</ApiBranch>
      <ApiEntity>cidrBlock</ApiEntity>
      <casePreference>lower</casePreference>
      <value1Label>Block</value1Label>
      <value1Type>text</value1Type>
      <value2Label/>
    </IndicatorType>
    <IndicatorType>
      <Name>Mutex</Name>
      <Custom>true</Custom>
      <Parsable>false</Parsable>
      <ApiBranch>mutexes</ApiBranch>
      <ApiEntity>mutex</ApiEntity>
      <casePreference>sensitive</casePreference>
      <value1Label>Mutex</value1Label>
      <value1Type>text</value1Type>
      <value2Label/>
    </IndicatorType>
    <IndicatorType>
      <Name>Registry Key</Name>
      <Custom>true</Custom>
      <Parsable>false</Parsable>
      <ApiBranch>registryKeys</ApiBranch>
      <ApiEntity>registryKey</ApiEntity>
      <casePreference>sensitive</casePreference>
      <value1Label>Key Name</value1Label>
      <value1Type>text</value1Type>
      <value2Label>Value Name</value2Label>
      <value2Type>text</value2Type>
    </IndicatorType>
    <IndicatorType>
      <Name>User Agent</Name>
      <Custom>true</Custom>
      <Parsable>false</Parsable>
      <ApiBranch>userAgents</ApiBranch>
      <ApiEntity>userAgent</ApiEntity>
      <casePreference>sensitive</casePreference>
      <value1Label>User Agent String</value1Label>
      <value1Type>text</value1Type>
      <value2Label/>
    </IndicatorType>
  </Data>
</indicatorTypesResponse>

Note

The responses above are taken from the ThreatConnect Public Cloud (https://app.threatconnect.com/).

To get information about a specific Indicator Type, you can use a query in the following format:

GET /v2/types/indicatorTypes/{indicatorType}

For example, to retrieve information for Mutexes, you would use the following query:

GET /v2/types/indicatorTypes/mutex

JSON Response:

{
  "status": "Success",
  "data": {
    "indicatorType": {
      "name": "Mutex",
      "custom": "true",
      "parsable": "false",
      "apiBranch": "mutexes",
      "apiEntity": "mutex",
      "casePreference": "sensitive",
      "value1Label": "Mutex",
      "value1Type": "text"
    }
  }
}

As of ThreatConnect version 5.2+, it is possible to retrieve the regular expression(s) (regex(es)) used to detect and validate any of the Indicator Types supplied by the platform. These regexes can be retrieved by adding the includeAdditional=true parameter as follows:

GET /v2/types/indicatorTypes/{indicatorType}?includeAdditional=true

The following example will return the regexes used to validate File Indicators:

GET /v2/types/indicatorTypes/file?includeAdditional=true

JSON Response:

{
  "status": "Success",
  "data": {
    "indicatorType": {
      "name": "File",
      "custom": "false",
      "parsable": "true",
      "apiBranch": "files",
      "apiEntity": "file",
      "value1Label": "MD5",
      "value1Type": "text",
      "value2Label": "SHA-1",
      "value2Type": "text",
      "value3Label": "SHA-256",
      "value3Type": "text",
      "regexes": [
        "\\b([a-fA-F\\d]{32})\\b",
        "\\b([a-fA-F\\d]{40})\\b",
        "\\b([a-fA-F\\d]{64})\\b"
      ]
    }
  }
}

Note that using the includes=additional parameter will also work. Likewise, includes=tags, includes=attributes, and includes=labels are permitted.

Indicator Keys

As of ThreatConnect version 5.8+, it is possible to retrieve the Indicator keys needed for pivoting to associated Indicators or Groups. These key values can be retrieved by adding the includeAdditional=true parameter. The indicatorTypes API endpoint will return key/values pair for each Indicator type, called key1 and, optionally, key2 and key3.

GET /v2/types/indicatorTypes?includeAdditional=true

JSON Response:

{
  "status": "Success",
  "data": {
      "resultCount": 10,
      "indicator": [
          {
            "name": "Address",
            "custom": "false",
            "parsable": "true",
            "apiBranch": "addresses",
            "apiEntity": "address",
            "keys": {
                "key1" : "ip"
            }
          },
          {
            "name": "EmailAddress",
            "custom": "false",
            "parsable": "true",
            "apiBranch": "emailAddresses",
            "apiEntity": "emailAddress",
            "keys": {
                "key1": "address"
            }
          },
          {
            "name": "File",
            "custom": "false",
            "parsable": "true",
            "apiBranch": "files",
            "apiEntity": "file",
            "value1Label": "MD5",
            "value1Type": "text",
            "value2Label": "SHA-1",
            "value2Type": "text",
            "value3Label": "SHA-256"
            "value3Type": "text",
            "keys": {
                "key1": "md5", "key2": "sha1", "key3": "sha256"
            }
          },
          {
            "name": "Host",
            "custom": "false",
            "parsable": "true",
            "apiBranch": "hosts",
            "apiEntity": "host",
            "keys": {
                "key1": "hostName"
            }
          },
          {
            "name": "URL",
            "custom": "false",
            "parsable": "true",
            "apiBranch": "urls",
            "apiEntity": "url",
            "keys": {
                "key1": "text"
            }
          },
          {
            "name": "ASN",
            "custom": "true",
            "parsable": "true",
            "apiBranch": "asns",
            "apiEntity": "asn",
            "casePreference": "upper",
            "value1Label": "AS Number",
            "value1Type": "text",
            "keys": {
                "key1": "AS Number"
            }
          },
          {
            "name": "CIDR",
            "custom": "true",
            "parsable": "true",
            "apiBranch": "cidrBlocks",
            "apiEntity": "cidrBlock",
            "casePreference": "lower",
            "value1Label": "Block",
            "value1Type": "text",
            "keys": {
                "key1": "Block"
            }
          },
          {
            "name": "Mutex",
            "custom": "true",
            "parsable": "false",
            "apiBranch: "mutexes",
            "apiEntity": "mutex",
            "casePreference": "sensitive",
            "value1Label": "Mutex",
            "value1Type": "text",
            "keys": {
                "key1": "Mutex"
            }
          },
          {
            "name": "Registry Key",
            "custom": "true",
            "parsable": "false",
            "apiBranch": "registryKeys",
            "apiEntity": "registryKey",
            "casePreference": "sensitive",
            "value1Label": "Key Name",
            "value1Type": "text",
            "value2Label": "Value Name",
            "value2Type": "text",
            "value3Label": "Value Type",
            "value3Type": "selectone",
            "value3Option": "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",
            "keys": {
                "key1": "Key Name", "key2": "Value Name", "key3": "Value Type"
            }
          },
          {
            "name": "User Agent",
            "custom": "true",
            "parsable": "false",
            "apiBranch": "userAgents",
            "apiEntity": "userAgent",
            "casePreference": "sensitive",
            "value1Label": "User Agent String",
            "value1Type": "text",
            "keys": {
                "key1" :"User Agent String"
        }
    ]
  }
}

Keys can also be retrieved for a single type by adding the indicatorType to the command as follows:

GET /v2/types/indicatorTypes/{indicatorType}?includeAdditional=true

For example, the following request will return the Indicator keys for Address Indicators. Note that using the includes=additional parameter will also work.

GET /v2/types/indicatorTypes/address?includeAdditional=true

Retrieve All Indicators

To retrieve Indicators of all types, use the following query:

GET /v2/indicators

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "indicator": [
      {
        "id": "54321",
        "ownerName": "Example Organization",
        "type": "URL",
        "dateAdded": "2017-07-13T17:50:17",
        "lastModified": "2017-07-19T17:35:31Z",
        "threatAssessRating": 3,
        "threatAssessConfidence": 50,
        "threatAssessScore": 281,
        "calScore": 173,
        "calIndicatorStatus": 2,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=54321&owner=Example+Organization",
        "summary": "http://example.com/login.php"
      },
      {
        "id": "54322",
        "ownerName": "Example Organization",
        "type": "EmailAddress",
        "dateAdded": "2017-07-13T17:51:17",
        "lastModified": "2017-07-19T17:35:29Z",
        "threatAssessRating": 4,
        "threatAssessConfidence": 75,
        "threatAssessScore": 408,
        "calScore": 426,
        "calIndicatorStatus": 1,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40gmail.com&owner=Example+Organization",
        "summary": "[email protected]"
      }
    ]
  }
}

Retrieve Multiple Indicators

To retrieve multiple Indicators of a certain type, use a query in the following format:

GET /v2/indicators/{indicatorType}

Replace {indicatorType} with any one of the following Indicator types or any of the custom Indicator Types available in your ThreatConnect instance:

  • addresses

  • asns

  • cidrBlocks

  • emailAddresses

  • files

  • hosts

  • mutexes

  • registryKeys

  • urls

  • userAgents

For example, the query below will retrieve a list of all Email Address Indicators in the default owner:

GET /v2/indicators/emailAddresses

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "emailAddress": [
      {
        "id": "54321",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:50:17",
        "lastModified": "2017-07-19T17:53:50Z",
        "threatAssessRating": 3,
        "threatAssessConfidence": 50,
        "threatAssessScore": 389,
        "calIndicatorStatus": 2,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=phish%40example.com&owner=Example+Organization",
        "address": "[email protected]"
      },
      {
        "id": "54322",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:51:17",
        "lastModified": "2017-07-19T17:53:49Z",
        "threatAssessRating": 3,
        "threatAssessConfidence": 50,
        "threatAssessScore": 363,
        "calScore": 173,
        "calIndicatorStatus": 2,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40gmail.com&owner=Example+Organization",
        "address": "[email protected]"
      }
    ]
  }
}

Retrieve a Single Indicator

To retrieve a single Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}

For example, if you wanted to retrieve the URL http://example.com/, you would use the following query:

GET /v2/indicators/urls/http%3A%2F%2Fexample.com%2F

JSON Response:

{
  "status": "Success",
  "data": {
    "url": {
      "id": "54321",
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-03-29T12:53:49Z",
      "threatAssessRating": 3.0,
      "threatAssessConfidence": 50.0,
      "threatAssessScore": 363,
      "calScore": 173,
      "calIndicatorStatus": 2,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=54321&owner=Example+Organization",
      "text": "http://example.com/"
    }
  }
}

Retrieve a Custom Indicator

To retrieve a Custom Indicator from ThreatConnect:

  1. Use the available Indicator Types to identify the apiBranch for the Indicator Type you would like to retrieve.

  2. Make a GET request in the format below.

GET /v2/indicators/{customIndicatorType}/{customIndicator}

For example, to retrieve the Mutex 8F6F00C4-B901-45fd-08CF-72FDEFF, you use the following query:

GET /v2/indicators/mutexes/8F6F00C4-B901-45fd-08CF-72FDEFF

JSON Response:

{
  "status": "Success",
  "data": {
    "mutex": {
      "id": 123456,
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "type": "Mutex",
      "dateAdded": "2017-05-19T15:40:28Z",
      "lastModified": "2017-05-19T15:43:49Z",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123456&owner=Example+Organization",
      "Mutex": "8F6F00C4-B901-45fd-08CF-72FDEFF",
      "rating": 4.00,
      "confidence": 85,
      "threatAssessRating": 4.0,
      "threatAssessConfidence": 85.0,
      "threatAssessScore": 536,
      "calScore": 218,
      "calIndicatorStatus": 2,
      "source": "https://heimdalsecurity.com/blog/bluedoom-worm-eternablue-nsa-exploits/",
      "description": "Mutex created by BlueDoom / EternalRocks malware to ensure first payload is not run more than once on a target system."
    }
  }
}

Retrieve the Owners in which an Indicator Exists

To retrieve all of the Owners in which an Indicator exists, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/owners

For example, if you wanted to retrieve all of the Owners in which the URL http://example.com/ exists, you would use the following query:

GET /v2/indicators/urls/http%3A%2F%2Fexample.com%2F/owners

JSON Response:

{
  "status": "Success",
  "data": {
    "owner": [
      {
        "id": 0,
        "name": "Example Organization",
        "type": "Organization"
      },
      {
        "id": 1,
        "name": "Common Community",
        "type": "Community"
      },
      {
        "id": 2,
        "name": "Example Community",
        "type": "Community"
      }
    ]
  }
}

To include the unique ID for each Indicator in its corresponding Owner, add the ?includes=additional parameter to the query. Including this parameter will return the itemId field in the response for each Owner, which will contain the ID for the Indicator in that Owner.

For example, the following query is the same as the preceding one, except it now includes the ?includes=additional parameter:

GET /v2/indicators/urls/http%3A%2F%2Fexample.com%2F/owners?includes=additional

JSON Response:

{
  "status": "Success",
  "data": {
    "owner": [
      {
        "id": 0,
        "name": "Example Organization",
        "type": "Organization",
        "itemId": "12241"
      },
      {
        "id": 1,
        "name": "Common Community",
        "type": "Community",
        "itemId": "12278"
      },
      {
        "id": 2,
        "name": "Example Community",
        "type": "Community",
        "itemId": "12301"
      }
    ]
  }
}

Hint

With an Indicator’s ID (i.e., the itemId), you can retrieve information about, update, and delete the Indicator when working with the ThreatConnect v3 API.

Retrieve Indicator Metadata

Retrieve Indicator Status

An active and an activeLocked field will be returned when retrieving Indicators by including the ?includeAdditional=true parameter in your request.

Retrieve Indicator Observations and False Positives

To find the number of times an Indicator has been observed or reported as a False Positive, use a request in the following format:

GET /v2/indicators/{indicatorType}/{indicator}?includeAdditional=true

For example, the query below will retrieve additional information about the Host example.com:

GET /v2/indicators/hosts/example.com?includeAdditional=true

JSON Response:

{
  "status": "Success",
  "data": {
    "host": {
      "id": 12345,
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-06-21T17:50:25-05:00",
      "lastModified": "2017-07-13T17:50:25-05:00",
      "threatAssessRating": 3.0,
      "threatAssessConfidence": 50.0,
      "threatAssessScore": 354,
      "calScore": 173,
      "calIndicatorStatus": 2,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=example.com&owner=Example%20Organization",
      "observationCount": 5,
      "lastObserved": "2016-07-13T17:50:25-05:00",
      "falsePositiveCount": 1,
      "falsePositiveLastReported": "2017-07-13T17:50:25-05:00",
      "privateFlag": false,
      "active": true,
      "activeLocked": false,
      "communityOrSource": false,
      "additionalOwners": [],
      "hostName": "example.com",
      "dnsActive": "false",
      "whoisActive": "false"
    }
  }
}

The observationCount field provides the total number of observations on the Indicator and the lastObserved field gives the date on which the Indicator was most recently observed. The falsePositiveCount field gives the total number times the Indicator has been reported as a False Positive, and the falsePositiveLastReported field gives the date on which the most recent False Positive was reported.

Retrieve Indicator Observations

Retrieving Recent Observations

As of ThreatConnect 6.5, the following API branch returns up to 20,000 Indicators with the most observations since a given date. System Administrators can adjust this limit via the System Settings screen for their ThreatConnect instance, if desired.

If no date is provided when submitting a request, the default query returns Indicators with the most observations over the past day. In this context, a “day” includes all of the previous day and all data from the current day up to the current moment in time.

GET /v2/indicators/observed

To view Indicators with the most observations since a specific date, use the dateObserved parameter, as demonstrated below:

GET /v2/indicators/observed?dateObserved=2022-04-05

This request will return the following data:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "indicator": [
      {
        "summary": "192.168.0.1",
        "observationCount": 12,
        "lastObserved": "2022-04-05T07:44:13Z",
        "userObservedList": [
          {
            "userName": "12345678901234567890",
            "userLastObservedDate": "2022-04-05T07:44:13Z",
            "count": 12
          }
        ]
      },
      {
        "summary": "example.com",
        "observationCount": 2,
        "lastObserved": "2022-04-04T21:17:06Z",
        "userObservedList": [
          {
            "userName": "12345678901234567890",
            "userLastObservedDate": "2022-04-04T21:17:06Z",
            "count": 2
          }
        ]
      }
    ]
  }
}

Note

Only observations reported using API accounts that are configured to be included in observations and false positive reports will show up in the list of recent observations. For more details on how to configure an API account in this way, see the Including False Positives Reported by API Users knowledge base article.

Retrieving Total Indicator Observations

To retrieve the total count of observations for an Indicator, use the following query:

GET /v2/indicators/{indicatorType}/{indicator}/observations

For example, the query below will retrieve the observations for the Host example.com:

GET /v2/indicators/hosts/example.com/observations

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "observation": [
      {
        "count": 5,
        "dateObserved": "2016-07-13T17:50:25-05:00Z"
      }
    ]
  }
}

Retrieving Observations from Your Organization

To view the number of an Indicator’s observations that came from your Organization, you can use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/observationCount

For example, the query below will retrieve the observation counts for the Host example.com:

GET /v2/indicators/hosts/example.com/observationCount

JSON Response:

{
  "status": "Success",
  "data": {
    "observationCount": {
      "count": 5,
      "lastObserved": "2016-07-13T17:50:25-05:00Z",
      "yourCount": 2,
      "yourLastObserved": "2016-07-13T17:50:25-05:00Z"
    }
  }
}

The yourCount field shows the total number of observations on the Indicator that came from your Organization (and yourLastObserved provides the date of the most recent observation). The count and lastObserved describe observations from any ThreatConnect user.

Retrieve Indicator Attributes

To retrieve an Indicator’s Attributes, use the following format:

GET /v2/indicators/{indicatorType}/{indicator}/attributes

For example, if you wanted to retrieve the Attributes on the Email Address bad@example.com, you would use the following query:

GET /v2/indicators/emailAddresses/bad@example.com/attributes

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "attribute": [
      {
        "id": "54321",
        "type": "Description",
        "dateAdded": "2016-07-13T17:50:17",
        "lastModified": "2017-05-02T18:40:22Z",
        "displayed": true,
        "value": "Description Example"
      },
      {
        "id": "54322",
        "type": "Source",
        "dateAdded": "2016-07-13T17:51:17",
        "lastModified": "2017-05-02T18:40:22Z",
        "displayed": true,
        "value": "Source Example"
      }
    ]
  }
}

To retrieve the Security Labels that are on an Attribute, use the following format:

GET /v2/indicators/{indicatorType}/{indicator}/attributes/{attributeId}/securityLabels

Here is an example query:

GET /v2/indicators/emailAddresses/bad@example.com/attributes/54321/securityLabels

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "securityLabel": [
      {
        "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. Information with this label can be shared with members of an organization and its clients.",
        "dateAdded": "2017-07-13T17:50:17"
      }
    ]
  }
}

Retrieve Indicator Security Labels

To retrieve the Security Labels for an Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/securityLabels

For example, the query below will retrieve all Security Labels for the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/securityLabels

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "securityLabel": [
      {
        "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. Information with this label can be shared with members of an organization and its clients.",
        "dateAdded": "2017-07-13T17:50:17"
      }
    ]
  }
}

Retrieve Indicator Tags

To retrieve the Tags for an Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/tags

For example, the query below will retrieve all Tags for the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/tags

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "tag": [
      {
        "name": "Nation State",
        "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=12&owner=Example+Organization"
      },
      {
        "name": "Phishing",
        "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=339"
      }
    ]
  }
}

Note

If a Tag object in the response represents an ATT&CK® Tag, then the &owner= portion of the URL will not be included in the webLink field. This is because ATT&CK Tags do not belong to an owner.

Retrieving Address DNS Resolutions

Example of DNS History request for an Address within an Organization:

GET /v2/indicators/addresses/192.168.0.1/dnsResolutions

Example of DNS History request for an Address within a Community:

GET /v2/indicators/addresses/192.168.0.1/dnsResolutions?owner=Common%20Community

JSON Response:

{
 "status": "Success",
 "data": {
  "resultCount": 1,
  "indicator": [{
   "id": 123456,
   "ownerName": "Organization Name",
   "type": "Host",
   "dateAdded": "2015-07-21T17:45:32Z",
   "lastModified": "2017-01-21T18:17:52Z",
   "rating": 5.00,
   "confidence": 85,
   "threatAssessRating": 4.36,
   "threatAssessConfidence": 80.67,
   "webLink": "https://demo.threatconnect.com/tc/auth/indicators/details/host.xhtml?host=example.com&owner=Organization+Name",
   "description": "Host retrieved from malware analysis.",
   "summary": "example.com"
   }
  ]
 }
}

XML Response:

<dnsResolutionsResponse>
 <Status>Success</Status>
 <Data xsi:type="dnsResolutionListResponseData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ResultCount>1</ResultCount>
  <Indicator>
    <Id>123456</Id>
    <OwnerName>Organization Name</OwnerName>
    <Type>Host</Type>
    <DateAdded>2015-07-21T17:45:32Z</DateAdded>
    <LastModified>2017-01-13T18:17:52Z</LastModified>
    <Rating>5.00</Rating>
    <Confidence>85</Confidence>
    <ThreatAssessRating>4.36</ThreatAssessRating>
    <ThreatAssessConfidence>80.67</ThreatAssessConfidence>
    <WebLink>https://demo.threatconnect.com/tc/auth/indicators/details/host.xhtml?host=example.com&amp;owner=Organization+Name</WebLink>
    <Summary>example.com</Summary>
  </Indicator>
 </Data>
</dnsResolutionsResponse>

Retrieving File Occurrences

To retrieve the File Occurrences of a File Indicator, use a query in the following format:

GET /v2/indicators/files/{fileHash}/fileOccurrences

For example, the query below will return all of the File Occurrences for the File Indicator represented by the hash aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:

GET /v2/indicators/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/fileOccurrences

JSON Response:

{
  "status": "Success",
  "data": {
    "fileOccurrence": {
      "id": 87534,
      "fileName": "win999301.dll",
      "path": "C:\\\\Windows\\System",
      "date": "2017-07-13T05:00:00Z"
    }
  }
}

To retrieve a specific File Occurrence, you can add the ID of the File Occurrence to the end of the query:

GET /v2/indicators/files/{fileHash}/fileOccurrences/{fileOccurrenceId}

Retrieving Host DNS Resolutions

Example of a DNS History request for a Host within an Organization:

GET /v2/indicators/hosts/example.com/dnsResolutions

Example of a DNS History request for a Host within a Community:

GET /v2/indicators/hosts/example.com/dnsResolutions?owner=Common%20Community

JSON Response:

{
 "status": "Success",
 "data": {
  "resultCount": 1,
  "dnsResolution": [{
   "resolutionDate": "2017-01-30T20:49:05Z",
   "addresses": [{
    "id": 123456,
    "ownerName": "Organization Name",
    "dateAdded": "2017-01-20T20:49:05Z",
    "lastModified": "2017-01-27T20:49:05Z",
    "threatAssessRating": 3.0,
    "threatAssessConfidence": 50.0,
    "webLink": "https://demo.threatconnect.com/tc/auth/indicators/details/address.xhtml?address=192.168.100.1&owner=Organization+Name",
    "ip": "192.168.100.1"
   }]
  }]
 }
}

XML Response:

<dnsResolutionsResponse>
 <Status>Success</Status>
 <Data xsi:type="dnsResolutionListResponseData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ResultCount>1</ResultCount>
  <DnsResolution>
   <ResolutionDate>2013-11-18T13:27:35Z</ResolutionDate>
   <Addresses>
    <Id>123456</Id>
    <OwnerName>Organization Name</OwnerName>
    <DateAdded>2017-01-20T20:49:05Z</DateAdded>
    <LastModified>2017-01-27T20:49:05Z</LastModified>
    <ThreatAssessRating>3.0</ThreatAssessRating>
    <ThreatAssessConfidence>50.0</ThreatAssessConfidence>
    <WebLink>https://demo.threatconnect.com/tc/auth/indicators/details/address.xhtml?address=192.168.100.1&amp;owner=Organization+Name</WebLink>
    <Ip>192.168.100.1</Ip>
   </Addresses>
  </DnsResolution>
 </Data>
</dnsResolutionsResponse>

Retrieve Indicator Associations

Group to Indicator Associations

To view Groups associated with a given Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/groups

For example, the query below will retrieve all of the Groups associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/groups

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "group": [
      {
        "id": "54321",
        "name": "New Incident",
        "type": "Incident",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:50:17",
        "lastModified": "2017-07-13T17:51:17",
        "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=54321"
      }
    ]
  }
}

You can also find associated Groups of a given type using the following format:

GET /v2/indicators/{indicatorType}/{indicator}/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, you could use the following query to find all Incidents associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/groups/incidents

You can delve further by adding the ID of an associated Group to the end of the query:

GET /v2/indicators/emailAddresses/bad@example.com/groups/incidents/54321

Where 54321 is the ID of an Incident associated with the Email Address bad@example.com.

Indicator to Indicator Association

To view Indicators associated with a given Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/indicators

For example, the query below will retrieve all of the Indicators associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/indicators

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "indicator": [
      {
        "id": "54321",
        "ownerName": "Example Organization",
        "type": "Address",
        "dateAdded": "2016-07-13T17:50:17",
        "lastModified": "2017-05-01T21:32:54Z",
        "rating": 3.0,
        "confidence": 55,
        "threatAssessRating": 3.0,
        "threatAssessConfidence": 55.0,
        "threatAssessScore": 281,
        "calScore": 173,
        "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/indicators/{indicatorType}/{indicator}/indicators/{associatedIndicatorType}

For example, you could use the following query to find all Address Indicators associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/indicators/addresses

Note

There is more documentation on retrieving Indicator-to-Indicator associations here.

Victim Assets to Indicator Associations

To view Victim Assets associated with a given Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/victimAssets

For example, the query below will retrieve all of the Victim Assets associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/victimAssets

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "victimAsset": [
      {
        "id": "54321",
        "name": "[email protected]",
        "type": "EmailAddress",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
      },
      {
        "id": "54322",
        "name": "[email protected]",
        "type": "EmailAddress",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
      }
    ]
  }
}

You can also find associated Victim Assets of a given type using the following format:

GET /v2/indicators/{indicatorType}/{indicator}/victimAssets/{victimAssetType}

The available Victim Asset types are:

  • emailAddresses

  • networkAccounts

  • phoneNumbers

  • socialNetworks

  • webSites

For example, we could use the following query to find all Victim Assets that are Email Addresses which are associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/victimAssets/emailAddresses

You can delve further by adding the ID of an associated Victim Asset to the end of the query:

GET /v2/indicators/emailAddresses/bad@example.com/victimAssets/emailAddresses/54321

Where 54321 is the ID of a Victim Asset associated with the Email Address bad@example.com.

Victim to Indicator Associations

To view Victims associated with a given Indicator, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/victims

For example, the query below will retrieve all of the Victims associated with the Email Address bad@example.com:

GET /v2/indicators/emailAddresses/bad@example.com/victims

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "victim": [
      {
        "id": "54321",
        "name": "Bad Guy",
        "org": "Example Organization",
        "suborg": "",
        "workLocation": "",
        "nationality": "",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
      }
    ]
  }
}

You can delve further by adding the ID of an associated Victim to the end of the query:

GET /v2/indicators/emailAddresses/bad@example.com/victims/54321

Where 54321 is the ID of a Victim associated with the Email Address bad@example.com.

Create Indicators

To create an Indicator, the most basic format is:

POST /v2/indicators/{indicatorType}
Content-type: application/json; charset=utf-8

{
  // required fields here...
}

The following are all considered valid paths for creating Indicators:

POST /v2/indicators/addresses
POST /v2/indicators/emailAddresses
POST /v2/indicators/files
POST /v2/indicators/hosts
POST /v2/indicators/urls

The table below illustrates valid fields for the body of the POST request when creating an Indicator.

Indicator Fields

Indicator Type

Valid Fields

Required

addresses

ip

TRUE

rating

FALSE

confidence

FALSE

active

FALSE

activeLocked

FALSE

emailAddresses

address

TRUE

rating

FALSE

confidence

FALSE

active

FALSE

activeLocked

FALSE

files

md5

TRUE*

sha1

TRUE*

sha256

TRUE*

size

FALSE

rating

FALSE

confidence

FALSE

active

FALSE

activeLocked

FALSE

hosts

hostName

TRUE

dnsActive

FALSE

whoisActive

FALSE

rating

FALSE

confidence

FALSE

active

FALSE

activeLocked

FALSE

urls

text

TRUE

rating

FALSE

confidence

FALSE

active

FALSE

activeLocked

FALSE

*Files are required to be submitted with at least one valid hash.

Note

The activeLocked field only prevents CAL from updating the status.

Hint

If you are unable to create an Indicator, view some Common Indicator Creation Errors.

Create Address Indicators

POST /v2/indicators/addresses
Content-type: application/json; charset=utf-8

{
  "ip": "192.168.0.1",
  "rating": 5.0,
  "confidence": 100
}

JSON Response:

{
  "status": "Success",
  "data": {
    "address": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-03T16:00:37Z",
      "rating": 5.0,
      "confidence": 100,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=192.168.0.1&owner=Example+Organization",
      "ip": "192.168.0.1"
    }
  }
}

Create Email Address Indicators

POST /v2/indicators/emailAddresses
Content-type: application/json; charset=utf-8

{
  "address": "[email protected]",
  "rating": 5.0,
  "confidence": 100
}

JSON Response:

{
  "status": "Success",
  "data": {
    "emailAddress": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-03T16:00:07Z",
      "rating": 5.0,
      "confidence": 100,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=badguy%40example.com&owner=Example+Organization",
      "address": "[email protected]"
    }
  }
}

Create File Indicators

POST /v2/indicators/files
Content-type: application/json; charset=utf-8

{
  "md5": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "sha1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "sha256": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "size": 5366,
  "rating": 5.0,
  "confidence": 100
}

JSON Response:

{
  "status": "Success",
  "data": {
    "file": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-03T15:59:19Z",
      "rating": 5.0,
      "confidence": 100,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&owner=Example+Organization",
      "md5": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "sha1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "sha256": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "size": 5366
    }
  }
}

Note

A File Indicator requires only one, valid hash. It can be an md5, sha1, or sha256 hash, or any combination thereof.

Create Host Indicators

POST /v2/indicators/hosts
Content-type: application/json; charset=utf-8

{
  "hostName": "example.com",
  "dnsActive": "false",
  "whoisActive": "true",
  "rating": 5.0,
  "confidence": 100
}

JSON Response:

{
  "status": "Success",
  "data": {
    "host": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-03T15:55:40Z",
      "rating": 5.0,
      "confidence": 100,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=example.com&owner=Example+Organization",
      "hostName": "example.com",
      "dnsActive": "false",
      "whoisActive": "true"
    }
  }
}

Create URL Indicators

POST /v2/indicators/urls
Content-type: application/json; charset=utf-8

{
  "text": "http://example.com/bad.php",
  "rating": 5.0,
  "confidence": 100
}

JSON Response:

{
  "status": "Success",
  "data": {
    "url": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-03T15:53:31Z",
      "rating": 5.0,
      "confidence": 100,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=54321&owner=Example+Organization",
      "text": "http://example.com/bad.php"
    }
  }
}

Create a Custom Indicator

To create a Custom Indicator in ThreatConnect:

  1. Use the available Indicator types to identify the apiBranch and required fields (usually titled value1Label, value2Label, etc) for the Indicator type you would like to create.

  2. Make a POST request in the format below with a body containing the required key-value pairs.

POST /v2/indicators/{indicatorApiBranch}
Content-type: application/json; charset=utf-8

{
  {value1Label}: {value1}
  {value2Label}: {value2}
  ...
}

For example, to create a Registry Key via API, you would first use the available Indicator types to identify the apiBranch and required values needed to create the Registry Key Indicator. To get this information, make the following request:

GET /v2/types/indicatorTypes

From this, find the entry for Registry Keys:

...
{
  "name": "Registry Key",
  "custom": "true",
  "parsable": "false",
  "apiBranch": "registryKeys",
  "apiEntity": "registryKey",
  "casePreference": "sensitive",
  "value1Label": "Key Name",
  "value1Type": "text",
  "value2Label": "Value Name",
  "value2Type": "text",
  "value3Label": "Value Type",
  "value3Type": "selectone",
  "value3Option": "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"
},
...

The apiBranch for Registry Keys is registryKeys and each Registry Key requires three values:

  • Key Name - text

  • Value Name - text

  • Value Type - One of the following: 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, or REG_SZ

This allows you to create the following POST request to create a new Registry Key:

POST /v2/indicators/registryKeys
Content-type: application/json; charset=utf-8

{
  "Key Name": "HKEY_LOCAL_MACHINE\\Software\\Microsoft\\DRM\\{cd704ff3-cd05-479e-acf7-6474908031dd}",
  "Value Name": "Example Value",
  "Value Type": "REG_NONE"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "registryKey": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Common Community",
        "type": "Community"
      },
      "type": "Registry Key",
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-08-09T13:29:51Z",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=25286094&owners=631&owner=Common%20Community",
      "Key Name": "HKEY_LOCAL_MACHINE\\Software\\Microsoft\\DRM\\{cd704ff3-cd05-479e-acf7-6474908031dd}",
      "Value Name": "Example Value",
      "Value Type": "REG_NONE"
    }
  }
}

Create Indicator Metadata

Add Indicator False Positive

To report a false positive for an Indicator, use a request in the following format:

POST /v2/indicators/{indicatorType}/{indicator}/falsePositive

For example, the following query will report a false positive for the Host Indicator example.com:

POST v2/indicators/hosts/example.com/falsePositive

JSON Response:

{
  "status": "Success",
  "data": {
    "falsePositive": {
      "count": 1,
      "lastReported": "2017-07-13T17:04:54Z"
    }
  }
}

Note

There can only be one false positive reported per user, per Indicator, per day. In other words, your API user can only report a false positive for a given Indicator once per day.

Add Indicator Observations

To add Observations to an Indicator, use a request in the following format:

POST /v2/indicators/{indicatorType}/{indicator}/observations
Content-type: application/json; charset=utf-8

{
  "count" : 10
}

For example, the following query will report two Observations for the File Indicator AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:

POST /v2/indicators/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/observations
Content-type: application/json; charset=utf-8

{
  "count" : 2
}

JSON Response:

{
  "status": "Success"
}

Create Indicator Attributes

To add an Attribute to an Indicator, use the following format:

POST /v2/indicators/{indicatorType}/{indicator}/attributes
Content-type: application/json; charset=utf-8

{
  "type" : {attributeType},
  "value" : "Test Attribute",
  "displayed" : true
}

For example, to add a Description Attribute to the Email Address bad@example.com, you would use the following query:

POST /v2/indicators/emailAddresses/bad@example.com/attributes
Content-type: application/json; charset=utf-8

{
  "type" : "Description",
  "value" : "Test Description",
  "displayed" : true
}

JSON Response:

{
  "status": "Success",
  "data": {
    "attribute": {
      "id": "54321",
      "type": "Description",
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-07-13T17:50:17",
      "displayed": true,
      "value": "Test Description"
    }
  }
}

To add a Security Label to an Attribute, use the following format, where {securityLabel} is replaced with the name of a Security Label that already exists in the Owner:

POST /v2/indicators/{indicatorType}/{indicator}/attributes/{attributeId}/securityLabels/{securityLabel}

For example, the query below will add a TLP:AMBER Security Label to the Attribute added to the Email Address bad@example.com:

POST /v2/indicators/emailAddresses/bad@example.com/attributes/54321/securityLabels/TLP%3AAMBER

Note

In order to add a Security Label to an Attribute, the Security Label must already exist. The query above will not create a new Security Label. If you specify a Security Label that does not exist, it will return an error.

Create Indicator Security Labels

To add a Security Label to an Indicator, use the following format, where {securityLabel} is replaced with the name of a Security Label that already exists in the Owner:

POST /v2/indicators/{indicatorType}/{indicator}/securityLabels/{securityLabel}

For example, the query below will add a TLP:AMBER Security Label to the Email Address bad@example.com:

POST /v2/indicators/emailAddresses/bad@example.com/securityLabels/TLP%3AAMBER

JSON Response:

{
  "status": "Success"
}

Note

In order to add a Security Label to an Indicator, the Security Label must already exist. The query above will not create a new Security Label. If you specify a Security Label that does not exist, it will return an error.

Create Indicator Tags

To add a Tag to an Indicator, use the following format, where {tagName} is replaced with the name of the Tag you want to add to the Indicator:

POST /v2/indicators/{indicatorType}/{indicator}/tags/{tagName}

For example, the query below will add the Nation State Tag to the Email Address bad@example.com:

POST /v2/indicators/emailAddresses/bad@example.com/tags/Nation%20State

JSON Response:

{
  "status": "Success"
}

Note

The length of a Tag is limited to 128 characters.

Attention

When applying ATT&CK Tags to an object, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to an object, use Phishing as the Tag name.

Also, if you applied a new Tag to an object and that Tag 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 applied a new Tag to an object and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Creating File Occurrences

To add a File Occurrence to a File Indicator, use a query in the following format:

POST /v2/indicators/files/{fileHash}/fileOccurrences
Content-type: application/json; charset=utf-8

{
  "fileName" : {fileName},
  "path" : {filePath},
  "date" : {date}
}

When adding a File Occurrence, the following fields are available:

Valid Fields

Required

fileName

FALSE*

path

FALSE*

date

FALSE*

* While none of the fields are required, at least one of them must be populated to create a File Occurrence.

For example, the following query will add a File Occurrence to the File Indicator represented by the hash aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:

POST /v2/indicators/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/fileOccurrences
Content-type: application/json; charset=utf-8

{
  "fileName" : "win999301.dll",
  "path" : "C:\\\\Windows\\System",
  "date" : "2017-07-13T00:00:00-05:00"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "fileOccurrence": {
      "id": 87534,
      "fileName": "win999301.dll",
      "path": "C:\\\\Windows\\System",
      "date": "2017-07-13T05:00:00Z"
    }
  }
}

Create Indicator Associations

Associate Group to Indicator

To associate an Indicator with a Group, use a query in the following format:

POST /v2/indicators/{indicatorType}/{indicator}/groups/{associatedGroupType}/{associatedGroupId}

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, the query below will associate the Email Address bad@example.com with an Incident with the ID 54321:

POST /v2/indicators/emailAddresses/bad@example.com/groups/incidents/54321

JSON Response:

{
  "status": "Success"
}

Associate Indicator to Indicator

The documentation for creating and retrieving Indicator-to-Indicator relationships has been moved here.

Associate Victim to Indicator

To associate an Indicator with a Victim, use a query in the following format:

POST /v2/indicators/{indicatorType}/{indicator}/victims/{victimId}

For example, the query below will associate the Email Address bad@example.com with the Victim with ID 54321:

POST /v2/indicators/emailAddresses/bad@example.com/victims/54321

JSON Response:

{
  "status": "Success"
}

Warning

In order to associate a Victim with any item, that Victim must have at least one Victim Asset.

Update Indicators

To update an Indicator, the basic format is:

PUT /v2/indicators/{indicatorType}/{indicator}
{
  {updatedField}: {updatedValue}
}

When updating the fields on an Indicator, you can change any of the fields available for the type of Indicator you are updating, except the field that sets the Indicator. Below is a table of available fields for each Indicator type:

Indicator Type

Valid Fields

Required

addresses

rating

FALSE

confidence

FALSE

emailAddresses

rating

FALSE

confidence

FALSE

files

size

FALSE

rating

FALSE

confidence

FALSE

hosts

dnsActive

FALSE

whoisActive

FALSE

rating

FALSE

confidence

FALSE

urls

rating

FALSE

confidence

FALSE

For example, the query below will update the Threat and Confidence Rating of the Email Address bad@example.com:

PUT /v2/indicators/emailAddresses/bad@example.com
{
  "rating": 4,
  "confidence": 80
}

JSON Response:

{
  "status": "Success",
  "data": {
    "emailAddress": {
      "id": "54321",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-07-19T20:34:23Z",
      "rating": 4.0,
      "confidence": 80,
      "threatAssessRating": 1.67,
      "threatAssessConfidence": 18.33,
      "threatAssessScore": 233,
      "calIndicatorStatus": 1,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40example.com&owner=Example+Organization",
      "address": "[email protected]"
    }
  }
}

Update Indicator Metadata

Update Indicator Attributes

To update an Indicator’s Attributes, use the following format:

PUT /v2/indicators/{indicatorType}/{indicator}/attributes/{attributeId}
{
  {updatedField}: {updatedValue}
}

When updating Attributes, you can change the following fields:

Updatable Attribute Fields

Required

value

TRUE

displayed

FALSE

source

FALSE

For example, if you want to update the value of an Attribute with ID 54321 on the Email Address bad@example.com, you would use the following query:

PUT /v2/indicators/emailAddresses/bad@example.com/attributes/54321
{
  "value": "Bad... Very bad."
}

JSON Response:

{
  "status": "Success",
  "data": {
    "attribute": {
      "id": "54321",
      "type": "Description",
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-07-19T15:54:12Z",
      "displayed": true,
      "value": "Bad... Very bad."
    }
  }
}

Updating File Occurrences

To update the File Occurrences on a File Indicator, use a query in the following format:

PUT /v2/indicators/files/{fileHash}/fileOccurrences/{fileOccurrenceId}
{
  "fileName" : {fileName},
  "path" : {filePath},
  "date" : {date}
}

When updating a File Occurrence, the following fields are available:

Valid Fields

Required

fileName

FALSE*

path

FALSE*

date

FALSE*

* While none of the fields are required, at least one of them must be populated to update a File Occurrence.

For example, the query below will update the File Occurrence with an ID of 54321 on the File Indicator represented by the hash aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:

PUT /v2/indicators/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/fileOccurrences/54321
{
  "fileName": "newFileName.exe",
  "path": "C:\\\\Windows\\User32",
  "date": "2017-07-14T05:00:00Z"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "fileOccurrence": {
      "id": 87534,
      "fileName": "newFileName.exe",
      "path": "C:\\\\Windows\\User32",
      "date": "2017-07-14T05:00:00Z"
    }
  }
}

Delete Indicators

To delete an Indicator, the most basic format is:

DELETE /v2/indicators/{indicatorType}/{indicator}?owner={ownerName}

For example, the query below will delete the Email Address bad@example.com in Example Community:

DELETE /v2/indicators/emailAddresses/[email protected]?owner=Example%20Community

JSON Response:

{
    "status": "Success"
}

Viewing Recently Deleted Indicators

As of ThreatConnect version 5.4, it is possible to view a list of Indicators that have been recently deleted from an Owner. The general format for this request is as follows:

GET /v2/indicators/deleted

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "indicator": [
      {
        "ownerName": "Example Org",
        "type": "File",
        "dateAdded": "2017-10-31T18:32:13Z",
        "summary": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      }
    ]
  }
}

By default, this will return all of the Indicators recently deleted in the API key’s default Organization. The number of days for which the Indicators will be listed on this API branch before being removed is specified by the indicatorDeleteRetentionTime system setting.

To view Indicators that have been recently deleted from a Community or Source that is not the default Owner, append the owner={ownerName} parameter to the query, as demonstrated below:

GET /v2/indicators/deleted?owner=Example%20Community

Delete Indicator Metadata

Delete Indicator Attributes

To delete an attribute from an Indicator, use the following format:

DELETE /v2/indicators/{indicatorType}/{indicator}/attributes/{attributeId}

For example, if you want to delete the Attribute with ID 54321 from the Email Address bad@example.com, you would use the following query:

DELETE /v2/indicators/emailAddresses/bad@example.com/attributes/54321

JSON Response:

{
  "status": "Success"
}

To delete a Security Label from an Attribute, use the following format, where {securityLabel} is replaced with the name of a Security Label that already exists in the Owner:

DELETE /v2/indicators/{indicatorType}/{indicator}/attributes/{attributeId}/securityLabels/{securityLabel}

For example, the query below will remove the TLP:AMBER Security Label from the Attribute with ID 54321 on the Email Address bad@example.com:

DELETE /v2/indicators/emailAddresses/bad@example.com/attributes/54321/securityLabels/TLP%3AAMBER

Delete Indicator Security Labels

To delete a Security Label from an Indicator, use the following format, where {securityLabel} is replaced with the name of a Security Label:

DELETE /v2/indicators/{indicatorType}/{indicator}/securityLabels/{securityLabel}

For example, the query below will delete the TLP:AMBER Security Label to the Email Address bad@example.com:

DELETE /v2/indicators/emailAddresses/bad@example.com/securityLabels/TLP%3AAMBER

JSON Response:

{
  "status": "Success"
}

Delete Indicator Tags

To delete a Tag from an Indicator, use the following format, where {tagName} is replaced with the name of the Tag you wish to remove from the Indicator:

DELETE /v2/indicators/{indicatorType}/{indicator}/tags/{tagName}

For example, the query below will delete the Nation State Tag to the Email Address bad@example.com:

DELETE /v2/indicators/emailAddresses/bad@example.com/tags/Nation%20State

JSON Response:

{
  "status": "Success"
}

Deleting File Occurrences

To delete a File Occurrence, use a query in the following format:

DELETE /v2/indicators/files/{fileHash}/fileOccurrences/{fileOccurrenceId}

For example, the query below will delete the File Occurrence with an ID of 54321 from the File Indicator represented by the hash aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:

DELETE /v2/indicators/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/fileOccurrences/54321

JSON Response:

{
  "status": "Success"
}

Delete/Disassociate Indicator Associations

Disassociate Group from Indicator

To disassociate an Indicator from a Group, use a query in the following format:

DELETE /v2/indicators/{indicatorType}/{indicator}/groups/{associatedGroupType}/{associatedGroupId}

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, the query below will disassociate the Email Address bad@example.com from an Incident with the ID 54321:

DELETE /v2/indicators/emailAddresses/bad@example.com/groups/incidents/54321

JSON Response:

{
  "status": "Success"
}

Disassociate Indicator from Indicator

To disassociate an Indicator from another Indicator, use a query in the following format:

DELETE /v2/indicators/{indicatorType}/{indicator}/indicators/{associatedIndicatorType}/{associatedIndicator}

For example, the query below will disassociate the Email Address bad@example.com from the IP Address 0.0.0.0:

DELETE /v2/indicators/emailAddresses/bad@example.com/indicators/addresses/0.0.0.0

JSON Response:

{
  "status": "Success"
}

Disassociate Victim Asset from Indicator

To disassociate an Indicator from a Victim Asset, use a query in the following format:

DELETE /v2/indicators/{indicatorType}/{indicator}/victimAssets/{victimAssetType}/{victimAssetId}

For example, the query below will disassociate the Email Address bad@example.com from the Victim Asset with ID 54321:

DELETE /v2/indicators/emailAddresses/bad@example.com/victimAssets/emailAddresses/54321

JSON Response:

{
  "status": "Success"
}

Disassociate Victim from Indicator

To disassociate an Indicator from a Victim, use a query in the following format:

DELETE /v2/indicators/{indicatorType}/{indicator}/victims/{victimId}

For example, the query below will disassociate the Email Address bad@example.com from the Victim with ID 54321:

DELETE /v2/indicators/emailAddresses/bad@example.com/victims/54321

JSON Response:

{
  "status": "Success"
}

Indicator to Indicator Associations

In ThreatConnect, some types of Indicators can be related with certain other types. At a high level, there are two ways to relate Indicators with one another:

  1. As an Association

  2. As a File Action

Association

An Association allows two Indicators of certain types to be related to one another in the manner that Indicators can be associated to Groups. Below is a list of the Indicator-to-Indicator Associations possible in the ThreatConnect Cloud, along with the Indicator types that can be associated with one another using each Association.

Name

API Branch

Indicators Associated

Address to User Agent

/addressToUserAgent

Address <-> User Agent

ASN to Address

/asnToAddress

ASN <-> Address

ASN to CIDR

/asnToCidr

ASN <-> CIDR

CIDR to Address

/cidrToAddress

CIDR <-> Address

DNS PTR Record

/dnsPtrRecord

Address <-> Host

Domain Registrant Email

/domainRegistrant

Host <-> EmailAddress

File Download

/fileDownload

URL <-> File

URL Host

/urlHost

URL <-> Address URL <-> Host

Note

In addition to the Associations in the preceding table, customer-configured custom Associations are also supported. Your System Administrator can retrieve the API branch for these Associations on the Indicators tab of the System Settings screen.

To retrieve Indicators associated with another Indicator using a custom Association, use a query in the following format:

GET /v2/indicators/{indicatorType}/{indicator}/associations/{associationType}/indicators

For example, the following query will retrieve all of the CIDR Indicators associated with an ASN:

GET /v2/indicators/asns/ASN12345/associations/asnToCidr/indicators

asnToCidr Associations retrieve JSON:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "indicator": [
      {
        "id": 123456,
        "ownerName": "Organization Name",
        "type": "CIDR",
        "dateAdded": "2016-11-22T00:38:03Z",
        "lastModified": "2016-11-22T01:50:53Z",
        "rating": 1.00,
        "confidence": 100,
        "threatAssessRating": 1.0,
        "threatAssessConfidence": 100.0,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123456&owner=Organization+Name",
        "summary": "192.168.0.1/24"
      }
    ]
  }
}

asnToCidr Associations retrieve XML:

<indicatorsResponse>
  <Status>Success</Status>
  <Data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="indicatorListResponseData">
    <ResultCount>1</ResultCount>
    <Indicator>
      <Id>123456</Id>
      <OwnerName>Organization Name</OwnerName>
      <Type>CIDR</Type>
      <DateAdded>2016-11-22T00:38:03Z</DateAdded>
      <LastModified>2016-11-22T01:50:53Z</LastModified>
      <Rating>1.00</Rating>
      <Confidence>100</Confidence>
      <ThreatAssessRating>1.0</ThreatAssessRating>
      <ThreatAssessConfidence>100.0</ThreatAssessConfidence>
      <WebLink>https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123456&amp;owner=Organization+Name</WebLink>
      <Summary>192.168.0.1/24</Summary>
    </Indicator>
  </Data>
</indicatorsResponse>

To create an Association between two Indicators, use the following POST request format:

POST /v2/indicators/{indicatorType}/{indicator}/associations/{associationType}/indicators/{indicatorType}/{indicator}

For example, the query below will associate the IP Address 192.168.0.1 with the CIDR Range 192.168.0.0/24.

POST /v2/indicators/addresses/192.168.0.1/associations/cidrToAddress/indicators/cidrBlocks/192.168.0.0%2F24

JSON Response:

{
  "status": "Success"
}

File Action

A file action adds one Indicator to the behavior graph of a File Indicator. Below is a list of the file actions available in the ThreatConnect Cloud, along with the Indicator type that can be related via each file action.

Name

API Branch

Indicator Type Associated with File

File Archive

/archive

File

File Drop

/drop

File

File Traffic

/traffic

Address, Host, URL

File Mutex

/mutex

Mutex

File Registry Key

/registryKey

Registry Key

File User Agent

/userAgent

User Agent

File DNS Query

/dnsQuery

Host

To retrieve Indicators associated with a file using a file action, use the following GET request format:

GET /v2/indicators/files/{fileHash}/actions/{fileAction}/indicators

For example, the query below retrieves all of the Mutex Indicators associated with the File Indicator represented by the hash 8743b52063cd84097a65d1633f5c74f5 using the File Mutex action:

GET /v2/indicators/files/8743b52063cd84097a65d1633f5c74f5/actions/mutex/indicators

Mutex file action retrieve JSON:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "indicator": [
      {
        "id": 123456,
        "ownerName": "Organization Name",
        "type": "Mutex",
        "dateAdded": "2016-11-23T16:21:53Z",
        "lastModified": "2016-11-23T16:21:53Z",
        "threatAssessRating": 3.0,
        "threatAssessConfidence": 50.0,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123456&owner=Organization+Name",
        "description": "Mutex for file with hash **8743b52063cd84097a65d1633f5c74f5**.",
        "summary": "50F163F13C2FF8FDB5262A672EB39B19"
      },
      {
        "id": 123457,
        "ownerName": "Organization Name",
        "type": "Mutex",
        "dateAdded": "2016-11-23T16:20:40Z",
        "lastModified": "2016-11-23T16:20:40Z",
        "threatAssessRating": 3.0,
        "threatAssessConfidence": 50.0,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123457&owner=Organization+Name",
        "description": "Mutex for file with hash **8743b52063cd84097a65d1633f5c74f5**.",
        "summary": "CTF.TimListCache.FMPDefaultS-1-5-21-1547161642-507921405-839522115-1004MUTEX.DefaultS-1-5-21-1547161642-507921405-839522115-1004"
      }
    ]
  }
}

Mutex file action retrieve XML:

<indicatorsResponse>
  <Status>Success</Status>
  <Data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="indicatorListResponseData">
    <ResultCount>2</ResultCount>
    <Indicator>
      <Id>123456</Id>
      <OwnerName>Organization Name</OwnerName>
      <Type>Mutex</Type>
      <DateAdded>2016-11-23T16:21:53Z</DateAdded>
      <LastModified>2016-11-23T16:21:53Z</LastModified>
      <ThreatAssessRating>3.0</ThreatAssessRating>
      <ThreatAssessConfidence>50.0</ThreatAssessConfidence>
      <WebLink>https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123456&amp;owner=Organization+Name</WebLink>
      <Description>Mutex for file with hash **8743b52063cd84097a65d1633f5c74f5**.</Description>
      <Summary>50F163F13C2FF8FDB5262A672EB39B19</Summary>
    </Indicator>
    <Indicator>
      <Id>123457</Id>
      <OwnerName>Organization Name</OwnerName>
      <Type>Mutex</Type>
      <DateAdded>2016-11-23T16:20:40Z</DateAdded>
      <LastModified>2016-11-23T16:20:40Z</LastModified>
      <ThreatAssessRating>3.0</ThreatAssessRating>
      <ThreatAssessConfidence>50.0</ThreatAssessConfidence>
      <WebLink>https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=123457&amp;owner=Organization+Name</WebLink>
      <Description>Mutex for file with hash **8743b52063cd84097a65d1633f5c74f5**.</Description>
      <Summary>CTF.TimListCache.FMPDefaultS-1-5-21-1547161642-507921405-839522115-1004MUTEX.DefaultS-1-5-21-1547161642-507921405-839522115-1004</Summary>
    </Indicator>
  </Data>
</indicatorsResponse>

To create an association between two Indicators using a file action, use the following POST request format:

POST /v2/indicators/files/{fileHash}/actions/{fileAction}/indicators/{indicatorType}/{indicator}

Private Indicators

Warning

In order to mark an Indicator as private, the ThreatConnect instance of ThreatConnect needs to have the privateIndicatorsEnabled configuration selected. This can be modified under System Settings.

Note

Custom Indicators cannot be marked as private. Only Address, Email Address, File, Host, and URL Indicators can be marked as private.

Retrieving Private Indicators

When retrieving an Indicator, it is possible to see if the Indicator is private by appending the includeAdditional=true parameter to the query, as demonstrated below:

GET /v2/indicators/hosts/example.org?includeAdditional=true

JSON Response:

{
  "status": "Success",
  "data": {
    "host": {
      "id": 123456,
      "owner": {
        "id": 2,
        "name": "Example Org",
        "type": "Organization"
      },
      "dateAdded": "2017-10-31T16:55:44Z",
      "lastModified": "2017-11-06T13:23:13Z",
      "rating": 4.00,
      "confidence": 85,
      "threatAssessRating": 4.37,
      "threatAssessConfidence": 72.91,
      "threatAssessScore": 650,
      "calScore": 552,
      "calIndicatorStatus": 1,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=example.org&owner=Example+Org",
      "source": "ThreatConnect Enrichment",
      "description": "Malicious domain.",
      "observationCount": 0,
      "falsePositiveCount": 0,
      "privateFlag": true,
      "hostName": "example.org",
      "dnsActive": "true",
      "whoisActive": "true"
    }
  }
}

Creating Private Indicators

To mark an Indicator as private when creating it, add the following key-value pair to the body of the POST query used to create the Indicator:

"privateFlag": "true"

For example, the following query will create a host Indicator that is marked as private:

POST /v2/indicators/hosts
{
    "hostName": "example.org",
    "privateFlag": "true"
}

Bulk Indicator Reports

If retrieving all of the Indicators and their entire context (i.e., Tags, Attributes, etc.) from a Source, then the above API calls can become unwieldy and require a high volume of successive calls. ThreatConnect can be configured to publish a daily bulk report of all Indicators per Owner for Sources and Communities within the Graphical User Interface (GUI). These reports can be accessed via the V2 API, and users should contact their ThreatConnect System Administrator to enable bulk reporting.

Checking the Status of Bulk Indicator Reports

Example of verifying that a Community or Source has bulk-reporting enabled:

GET /v2/indicators/bulk?owner=Demo+Customer+Community

Checking bulkStatus Object JSON Response:

{
 "bulkStatus": {
  "name": "Demo Customer Community",
  "csvEnabled": true,
  "jsonEnabled": true,
  "nextRun": "2015-03-27T05:00:00Z",
  "lastRun": "2015-03-26T19:06:53Z",
  "status": "Complete"
 }
}

Checking bulkStatus Object XML Response:

<BulkStatus>
 <Name>Demo Customer Community</Name>
 <CsvEnabled>true</CsvEnabled>
 <JsonEnabled>true</JsonEnabled>
 <NextRun>2015-03-27T05:00:00Z</NextRun>
 <LastRun>2015-03-26T19:06:53.344Z</LastRun>
 <Status>Complete</Status>
</BulkStatus>

The response body will contain a bulkStatus object, which provides details of the configuration for the bulk-reporting feature of this Community or Source:

  • “name”: The name of the Owner queried

  • “csvEnabled”: Whether the owner has enabled Comma Separated Values (CSV) reports to be generated (true/false), thus determining if the respective endpoint will yield data

  • “jsonEnabled”: Whether the owner has enabled JSON reports to be generated (true/false), thus determining if the respective endpoint will yield data

  • “nextRun”: The ISO 8601 time-stamp representing when the report generator will run next

  • “lastRun”: The ISO 8601 time-stamp representing when the report generator was last run

  • “status”: A string representing the status of the most-recent report job (Complete, Failure, etc.)

Retrieving Bulk Reports

Reports can be retrieved in JSON or CSV format. The JSON format will contain additional context in a new format, including Attributes and Tags, if relevant. CSV reports contain an Indicator, its Type, its Threat Rating, and its Confidence value.

JSON Bulk Reports

To retrieve a JSON report for an Owner, execute the query below, and include the Owner to be queried. The API will return the latest version of the JSON report with a content-type header of “application/json.” The output is very similar to that returned by the Indicators Collection (e.g., in /v2/indicators), with the addition of Attributes and Tags where relevant.

GET /v2/indicators/bulk/json?owner=Demo+Customer+Community

Note

In order to retrieve a JSON report for an Owner, the Owner must have JSON Report publication enabled.

Retrieving Bulk Reports JSON Response:

{
 "indicator": [{
    "id": 126650,
    "ownerName": "Demo Customer Community",
    "type": "Host",
    "dateAdded": "2013-11-15T21:32:39Z",
    "lastModified": "2015-03-13T06:22:03Z",
    "rating": 5.0,
    "confidence": 73,
    "threatAssessRating": 4.38,
    "threatAssessConfidence": 93.43,
    "webLink": "https://app.threatconnect.com/tc/auth/indicators/details/host.xhtml?host=example.com&owner=Demo+Customer+Community",
    "description": "This is probably a bad domain.",
    "summary": "example.com",
    "attribute": [{
     "id": 131253,
     "type": "Source",
     "dateAdded": "2013-11-15T21:32:40Z",
     "lastModified": "2013-11-15T21:32:40Z",
     "displayed": true,
     "value": "ThreatConnect Intelligence Research Team Enrichment"
    }, {
     "id": 149457,
     "type": "Description",
     "dateAdded": "2013-11-15T21:32:40Z",
     "lastModified": "2013-11-15T21:32:40Z",
     "displayed": true,
     "value": "This is probably a bad domain."
    }],
    "tag": [{
     "name": "China",
     "webLink": "https://app.threatconnect.com/tc/auth/tags/tag.xhtml?tag=China&owner=Demo Customer Community"
    }]
   }]
 }

An optional URL parameter runNow=true can be added (as shown below) to force the report to be recreated. By default, reports are created once a day.

GET /v2/indicators/bulk/json?owner=Demo+Customer+Community&runNow=true

CSV Bulk Reports

To retrieve a CSV report for an Owner, execute the query below, and include the Owner to be queried. The API will return the latest CSV report with a content-type header of “text/csv.” The report will contain all of the Indicators in that Owner and their Indicator Type. It will also include each Indicator’s Threat and Confidence ratings, if set, or null otherwise.

GET /v2/indicators/bulk/csv?owner=Demo+Customer+Community

Note

In order to retrieve a CSV report for an Owner, the Owner must have CSV Report publication enabled.

The example below displays the output from a CSV report:

Type,Value,Rating,Confidence
Host,example.com,null,null
Address,192.168.31.136,3.00,0
File,ABCDE123456804A61F2A704811F51BC,3.00,55
URL,http://www.example.com/malware.exe,null,0
EmailAddress,spearphisher@example.com,3.00,62

An optional URL parameter runNow=true can be added (as shown below) to force the report to be recreated. By default, reports are created once a day.

GET /v2/indicators/bulk/csv?owner=Demo+Customer+Community&runNow=true

Batch Upload: Indicators

You can use the V2 and V1 Batch APIs to create and modify Indicators in bulk. See Batch API for instructions on using the Batch API.