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": 1,
    "tag": [
      {
        "name": "Nation State",
        "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=Nation+State&owner=Common+Community"
      }
    ]
  }
}

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 wish 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.

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

The Batch API allows you to create and delete Indicators in bulk via the HTTP POST method. After a batch entry is created, you can upload an Indicator file. The content of the file must be valid JSON and mimic the data structure of the Bulk JSON file download. Uploading a file instantly triggers a batch job to begin processing the data.

Attention

The Batch API is restricted to Indicators and will improve performance when importing large amounts of data.

Note

Document storage must be enabled on your ThreatConnect instance to use the Batch API.

The Batch Create resource creates a batch entry in the system. No batch processing is triggered until the batch input file is uploaded. The table below displays the fields required for the Batch Create message.

BatchConfig Parameter Required Applicable Batch Version(s) Value Description
version No N/A V1 (default)
Basic functionality
- Supports importing Indicators only
- Includes limited features and settings
      V2
Enhanced functionality
- Supports importing Indicators and Groups
- Supports creating Group-to-Group, Indicator-to-Group, and Group-to-Indicator associations
- Includes all features described in this table
owner Yes V1, V2 <name> The name of the Organization, Community or Source in which data will be imported or modified
haltOnError Yes V1, V2 TRUE The batch process will stop processing the entire batch the first time it encounters an error
      FALSE The batch process will attempt to continue processing the batch after encountering an error
action Yes V1, V2 Create Creates new, or modifies, existing, data in the specified owner
      Delete Deletes existing data in the specified owner that matches any of the incoming batch data
attributeWriteType Yes V1, V2 Append [1] Incoming Attributes will be added to those that may already be present on existing data (duplicates may occur, as redundancy checking is NOT performed)
      Replace Attributes will be removed from existing data before incoming Attributes are added
      Static Incoming Attributes will be ignored, and any that may already be present on existing data will not be changed
tagWriteType No V2 Append Incoming Tags will be added to those that may already be present on existing data
      Replace (default) Tags will be removed from existing data before incoming Tags are added
securityLabelWriteType No V2 Append Incoming Security Labels will be added to those that may already be present on existing data
      Replace (default) Security Labels will be removed from existing data before incoming Security Labels are added
fileMergeMode No V2 Distribute Metadata from incoming file hashes (e.g., Threat Rating, Confidence Rating, Tags, Attributes) are applied to all matching Indicators (up to 3 possible)
      Merge (default) Combines multiple existing Indicators (if present) into one if incoming File Indicators correlate two or more previously separate hashes
hashCollisionMode No V2 Split Inhibits a merge and, instead, splits the incoming data out across any offending Indicators
      IgnoreIncoming Drops incoming Indicator from the import, leaving pre-existing data the same as it was before importing offending Indicator
      IgnoreExisting If conflict exists between two or more existing Indicators, deleted existing File Indicators that caused conflict
      FavorIncoming (default) Favors hashes in incoming data, overwriting hashes that conflicted within existing data
      FavorExisting Favors hashes in existing data, ignoring hashes that conflicted from incoming data
[1]Denotes a setting applicable to Version V2 only

Note

If haltOnError is set to true and an error occurs, then the status will be set to Completed, and the value for errorCount will be greater than zero. The value for unprocessedCount will be greater than zero unless the uploaded file did not contain valid JSON.

Note

Occasionally, imported File Indicators may contain one or more hashes that other File Indicators in the same owner also contain. Specifically, either the incoming data or the existing data will contain additional hash type(s) that the other item did not have (e.g., the incoming data contains an MD5 and SHA1, while the existing data contains only the MD5, or vice versa). In this situation, the resulting File Indicator will end up with the “superset” of file hashes by either retaining the existing hash(es) or adding in the new hash(es). However, certain situations may arise that require special processing when incoming file hash(es) cause conflicts with existing data (e.g., the incoming data contains an MD5 and SHA1, while the existing data contains the same MD5 but a different SHA1). Use the fileMergeMode and hashCollisionMode parameters defined in the preceding table to handle such situations.

Batch Indicator Input File Formats

The Batch Upload feature expects to ingest a JSON file consisting of list(s) of dictionaries. As shown in the following examples, the V1 Batch operation expects a single list of Indicator objects only, whereas the enhanced V2 Batch operation expects Indicator and Group objects to be contained within its own indicator and group array definition, respectively. The list of fields expected within each Indicator or Group item parallels those described in the Indicator and Group creation operations. Additionally, you must include a type field within each item that defines the particular Indicator or Group type the item represents.

Batch Indicator Input File Format (V1)

[{
       "rating": 3,
       "confidence": 60,
       "description": "a malicious domain",
       "summary": "super-malicious.ru",
       "type": "Host",
       "attribute": [{
              "type": "AttributeName",
              "value": "MyAttribute"
       }],
       "tag": [{
              "name": "MyTag"
       }]
}]

Batch Indicator Input File Format (V2)

Indicator-to-Group Association

{
      "indicator": [{
              "rating": 3,
              "confidence": 60,
              "summary": "super-malicious.ru",
              "type": "Host",
              "associatedGroups": [{"groupXid":"00000000-0000-0000-0000-000000000000:1234"}],
              "attribute": [{
                              "type": "Description",
                              "value": "a malicious domain"
                      }
              ],
              "tag": [{
                      "name": "MyTag"
              }]
      }],
      "group": [{
              "name": "New Incident",
              "type": "Incident",
              "xid": "00000000-0000-0000-0000-000000000000:1234",
              "eventDate": "2019-11-26T00:00:00Z",
              "attribute": [{
                      "type": "Description",
                      "displayed": true,
                      "value": "Ryuk C2"
              }],
              "tag": [{
                      "name": "MyOtherTag"
              }]
      }]
}

Group-to-Indicator Association (New Indicator)

{
      "indicator": [{
              "rating": 3,
              "confidence": 0,
              "summary": "host123.com",
              "type": "Host",
              "attribute": [{
                              "type": "Description",
                              "value": "a malicious domain"
                      }
              ],
              "tag": [{
                      "name": "MyTag"
              }]
      }],
      "group": [{
              "name": "New Incident with Indicator 1",
              "type": "Incident",
              "xid": "00000000-0000-0000-0000-000000000000:0001",
              "eventDate": "2019-11-26T00:00:00Z",
              "attribute": [{
                      "type": "Description",
                      "displayed": true,
                      "value": "Ryuk C2"
              }],
              "tag": [{
                      "name": "MyOtherTag"
              }],
        "associatedIndicators": [
          {
            "summary":"host123.com",
            "indicatorType":"Host"
          }
        ]

      }]
}

Group-to-Indicator Association (Existing Indicator)

{
      "group": [{
              "name": "New Incident with Existing Indicator 1",
              "type": "Incident",
              "xid": "00000000-0000-0000-0000-000000000000:0003",
              "eventDate": "2019-11-26T00:00:00Z",
              "attribute": [{
                      "type": "Description",
                      "displayed": true,
                      "value": "Ryuk C2"
              }],
              "tag": [{
                      "name": "MyOtherTag"
              }],
        "associatedIndicators": [
          {
            "summary":"host123.com",
            "indicatorType":"Host"
          }
        ]

      }]
}

Note

When creating Group-to-Indicator associations, including the Indicator(s) in the JSON file will improve the efficiency of the batch job. Otherwise, a lookup will need to be made for each Indicator not included in the JSON file.

Group-to-Group Association

{
      "group": [{
              "name": "New Incident 2",
              "type": "Incident",
              "xid": "00000000-0000-0000-0000-000000000000:0001",
        "associatedGroupXid": ["00000000-0000-0000-0000-000000000000:0002"],
              "eventDate": "2019-11-26T00:00:00Z",
              "attribute": [{
                      "type": "Description",
                      "displayed": true,
                      "value": "Ryuk C2"
              }],
              "tag": [{
                      "name": "MyOtherTag"
              }]
      },
    {
              "name": "New Incident 3",
              "type": "Incident",
              "xid": "00000000-0000-0000-0000-000000000000:0002",
              "eventDate": "2019-11-26T00:00:00Z",
              "attribute": [{
                      "type": "Description",
                      "displayed": true,
                      "value": "Ryuk C2"
              }],
              "tag": [{
                      "name": "MyOtherTag"
              }]
      }]
}

Note

File Indicators may have any or all of MD5, SHA1, and/or SHA256 hash values. The hashes may be provided in either of two ways: (1) concatenated using ‘space-colon-space’ in the Indicator’s summary field, or; (2) presented as individual md5, sha1, and sha256 hash values. The presence of any hashes using this second method will cause the summary field to be ignored during import. For example, you could import a File Indicator with the MD5 hash 905ad8176a569a36421bf54c04ba7f95, SHA1 hash a52b6986d68cdfac53aa740566cbeade4452124e and SHA256 hash 25bdabd23e349f5e5ea7890795b06d15d842bde1d43135c361e755f748ca05d0 using either of the following:

Option 1

{
“summary”: “905ad8176a569a36421bf54c04ba7f95: a52b6986d68cdfac53aa740566cbeade4452124e: 25bdabd23e349f5e5ea7890795b06d15d842bde1d43135c361e755f748ca05d0”, “type”: “File”, …

}

Option 2

{
“md5”: “905ad8176a569a36421bf54c04ba7f95”, “sha1”: “a52b6986d68cdfac53aa740566cbeade4452124e”, “sha256”: “25bdabd23e349f5e5ea7890795b06d15d842bde1d43135c361e755f748ca05d0”, “type”: “File”, …

}

Note

Exporting indicators via the JSON Bulk Reports endpoint will create a file in this format.

Warning

The maximum number of Indicators that can be created in one batch job is 25,000. If you need to create more Indicators, you will have to use multiple batch jobs.

Sample Batch Create request

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

{
  "haltOnError": "false",
  "attributeWriteType": "Replace",
  "action": "Create",
  "owner": "Common Community"
  "version": "V2"
}

Server Response on Success

HTTP/1.1 201 Created
{
  batchId: "123"
}

Server Response on Insufficient Privileges

HTTP/1.1 403 Forbidden
{
  status: "Not Authorized",
  description: "Organization not authorized for batch"
}

Server Response on Incorrect Settings

HTTP/1.1 403 Forbidden
{
  status: "Not Authorized",
  description: "Document storage not enabled for this instance"
}

Sample Batch Upload Input File request

Batch files should be sent as HTTP POST data to a REST endpoint, including the relevant batchId, as shown in the format below.

POST /v2/batch/{batchId}

For example:

POST /v2/batch/123

Content-Type: application/octet-stream
Body: The JSON payload goes here.

Server Response on Success

HTTP/1.1 202 Accepted
{
  status: "Queued"
}

Server Response on Overlarge Input File

HTTP/1.1 400 Bad Request
{
  status: "Invalid",
  description: "File size greater than allowable limit of 2000000"
}

Sample Batch Status Check request

Use this request to check the status of a running batch-upload job. Possible GET response statuses are:

  • Created
  • Queued
  • Running
  • Completed
GET /v2/batch/123

Server Response on Success (job still running)

HTTP/1.1 200 OK
{
  status: "Running"
}

Server Response on Success (job finished)

HTTP/1.1 200 OK
{
  status: "Completed",
  errorCount: 3420,
  successCount: 405432,
  unprocessCount: 0
}

Sample Batch Error Message request

GET /v2/batch/123/errors

Server Response on Success (job still running)

HTTP/1.1 400 Bad Request
{
  status: "Invalid",
  description: "Batch still in Running state"
}

Server Response on Success (job finished)

HTTP/1.1 200 OK
Content-Type: application/octet-stream ; boundary=
Content-Length:
Content-Encoding: gzip

Note

Batch jobs that end in partial failures will have an error file with a response having a ‘reason text’, which includes Tag, Attribute, or Indicator errors (fail on first).