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 like http%3A%2F%2Fexample.com%2F before it is sent in a request.

Retrieve Indicators

Filtering Indicators

Filters Parameter

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    
summary string =, ^
modifiedSince string =, ^
dateAdded date <, >
rating bigdecimal <, >
confidence integer =, <, >
threatAssessRating double <, >
threatAssessConfidence double <, >
falsePositive integer =, <, >
Address Specific Filters    
countryCode string =
organization string =
asn integer =
Host Specific Filters    
whoisActive boolean =
dnsActive boolean =

Note

=, <, >, and ^ operators need to be escaped in the API query URL as: %3D, %3C, %3E, and %5E respectively.

Examples

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 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 usage multiple parameters (with implicit AND):

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

The example below demonstrates usage 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

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 usage of the modifiedSince parameter:

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

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

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

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 like ?owner={ownerName}. For example, the following query will return all Host Indicators in the Common Community:

GET /v2/indicators/hosts/?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"
    }
  }
}

In ThreatConnect version 5.2+, it is possible to retrieve the regular expression(s) (regex(es)) used to detect and validate an Indicator of a given type. 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"
      ]
    }
  }
}

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,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=54321&owner=Research+Labs",
        "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,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40gmail.com&owner=Research+Labs",
        "summary": "bad@gmail.com"
      }
    ]
  }
}

Retrieve Multiple Indicators

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

GET /v2/indicators/{indicatorType}

The {indicatorType} can be any one of the available Indicator types below or any of the custom Indicator types available in your instance of threatconnect:

  • addresses
  • emailAddresses
  • files
  • hosts
  • urls

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,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=phish%40example.com&owner=Research+Labs",
        "address": "phish@example.com"
      },
      {
        "id": "54322",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:51:17",
        "lastModified": "2017-07-19T17:53:49Z",
        "threatAssessRating": 3,
        "threatAssessConfidence": 50,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40gmail.com&owner=Research+Labs",
        "address": "bad@gmail.com"
      }
    ]
  }
}

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": 1.67,
      "threatAssessConfidence": 18.33,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=54321&owner=Example+Organization",
      "text": "http://example.com/"
    }
  }
}

Retrieving 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,
      "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"
      }
    ]
  }
}

Retrieve Indicator Metadata

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",
      "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",
      "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 5.0, the API branch below provides the ten Indicators with the most observations since a given date. If no date is given, the default query returns the ten Indicators which have had 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=2017-01-13

This request will return the following data:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "indicator": [
      {
        "summary": "192.168.0.1",
        "userObservedList": [
          {
            "userName": "12345678901234567890",
            "count": 12
          }
        ]
      },
      {
        "summary": "example.com",
        "userObservedList": [
          {
            "userName": "12345678901234567890",
            "count": 2
          }
        ]
      }
    ]
  }
}

Note

Only observations reported using API accounts that are configured to be included in Observations and False Positives will show up in the list of recent observations. For more details on how to configure an API account in this way, refer to the knowledge base article here.

Retrieving Total Indicator Observations

To retrieve the total count of observations for an Indicator, you can 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 how many of an Indicator’s observations 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 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": "TLP Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
        "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": "TLP Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
        "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 like:

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

Retrieving Host DNS Resolutions

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

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

Example of 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",
        "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
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

For example, we 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

We can also drill down even further by adding the ID of an associated Group to the end of the query like:

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,
        "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, we 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": "bad@badguys.com",
        "type": "EmailAddress",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
      },
      {
        "id": "54322",
        "name": "nobody@gmail.com",
        "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

We can also drill down even further by adding the ID of an associated Victim Asset to the end of the query like:

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",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
      }
    ]
  }
}

We can also drill down even further by adding the ID of an associated Victim to the end of the query like:

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 Type Valid Fields Required
addresses ip TRUE
  rating FALSE
  confidence FALSE
emailAddresses address TRUE
  rating FALSE
  confidence FALSE
files md5 TRUE*
  sha1 TRUE*
  sha256 TRUE*
  size FALSE
  rating FALSE
  confidence FALSE
hosts hostName TRUE
  dnsActive FALSE
  whoisActive FALSE
  rating FALSE
  confidence FALSE
urls text TRUE
  rating FALSE
  confidence FALSE

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

Hint

If you are unable to create an Indicator, check out 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": "badguy@example.com",
  "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": "badguy@example.com"
    }
  }
}

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 (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 like 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, let’s walk through the process of creating a Registry Key via API. Step one is use the available Indicator types to identify the apiBranch and required values we need to create the Registry Key Indicator. To get this information, we will make the following request:

GET /v2/types/indicatorTypes

From this, we 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 us 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, you can only use your API user to 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, if you wanted 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 on the Threat:

POST /v2/indicators/emailAddresses/bad@example.com/attributes/54321/securityLabels/TLP%20Amber

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%20Amber

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

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
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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 itself, you can change any of the fields available for the type of Indicator you are updating except the field that sets the indicator itself. 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

By way of 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,
      "confidence": 80,
      "threatAssessRating": 1.67,
      "threatAssessConfidence": 18.33,
      "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=bad%40example.com&owner=Example+Organization",
      "address": "bad@example.com"
    }
  }
}

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 wanted 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}

By way of example, the query below will delete the Email Address bad@example.com:

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

JSON Response:

{
    "apiCalls": 1,
    "resultCount": 0,
    "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",
        "lastModified": null,
        "summary": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      }
    ]
  }
}

By default, this will return all of the Indicators recently deleted in the API key’s default org. 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 wanted 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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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%20Amber

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%20Amber

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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. 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

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"
}
  1. 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,
      "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

Sample Batch Create request

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

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

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"
}

The following is an example of a Batch Indicator Input file:

{
  "ownerName": "<String>",
  "type": "<String>",
  "rating": "<BigDecimal>",
  "confidence": "<Short>",
  "description": "<String>",
  "summary": "<String>",
  "tag": [
    {
      "name": "<String>"
    }
  ]
}

Sample Batch Upload Input File request

POST /v2/batch/123

Content-Type: application/octet-stream; boundary=[boundary-text]
Content-Length: <data_size>
Content-Encoding: gzip
[boundary-text]
<uploaded_data>

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

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

Create Batch Endpoint

The Batch API allows bulk Indicator creation and deletion via the HTTP POST method. After creating a batch, an Indicator file is uploaded. The content of the file must be valid JSON, with content and format mimicking the data structure of the Bulk JSON file download. A file upload instantly triggers a batch job to begin processing the data. The Batch API is restricted to Indicators and will improve performance when importing large amounts of data.

Note

Document Storage is required 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 Message Values Description
haltOnError true The batch process will stop processing the entire batch the first time it reaches an error during processing.
  false (default) If this field is not provided, the default behavior is to continue processing further entities in the input file.
attributeWriteType Append Append: Add attributes (allow duplicates)
  Replace Replace: Delete current attributes; Add/Validate new
action Create Create: Create Indicator
  Delete Delete: Delete Indicator (only the ‘summary’ and ‘type’ field are required)

Batch Indicator Input File Format

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

The batch upload feature expects to ingest a JSON file consisting of a list of dictionaries

Field Data type Required?
rating integer Required
confidence float Required
description string Required
summary string Required
type string Required
tag list of dictionaries Optional
attribute list of dictionaries Optional
associatedGroup list of integers Optional

Supported type values for Indicators:

  • Host
  • Address
  • EmailAddress
  • URL
  • File

Note

Exporting indicators via the JSON Export feature in ThreatConnect will create a file in this format

Upload Batch Input File Endpoint

Batch files should be sent as HTTP POST data to a REST endpoint, including the relevant batchId

Check Batch Status Endpoint

You may also check the status of a running batch upload job

The server can be configured to restrict the file size. Clients can submit multiple batches for larger files.

Possible GET response status includes:

  • Created
  • Queued
  • Running
  • Completed

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

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