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:
addressesasnscidrBlocksemailAddressesfileshostsmutexesregistryKeysurlsuserAgents
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:
- Use the available Indicator Types to identify the
apiBranchfor the Indicator Type you would like to retrieve. - 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&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&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:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
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:
emailAddressesnetworkAccountsphoneNumberssocialNetworkswebSites
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:
- Use the available Indicator types to identify the
apiBranchand required fields (usually titledvalue1Label,value2Label, etc) for the Indicator type you would like to create. - 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- textValue Name- textValue 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:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
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:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
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:
- As an Association
- 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&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&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&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).