Indicators

An Indicator represents an atomic piece of information that has some intelligence value. Indicators are guaranteed to be unique within an Owner. For example, a single Organization can have only one copy of the Indicator badguy@bad.com.

Endpoint: /api/v3/indicators

Note

You can retrieve, update, or delete a specific Indicator using its ID or summary. If using an Indicator’s summary, the API request will search for the Indicator in the Organization in which your API user account resides. To search for an Indicator by summary in a Community or Source to which your API user account has access, use the owner query parameter.

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/indicators endpoint:

OPTIONS /v3/indicators

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for all Indicator types.

Field

Description

Type

Required for Creation?

Updatable?

Example Value(s)

active

Indicates whether the Indicator is active

Boolean

FALSE

TRUE

true, false

activeLocked

Indicates whether the active Indicator Status is locked

Boolean

FALSE

TRUE

true, false

associatedArtifacts

A list of Artifacts associated to the Indicator

Artifact Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}

associatedCases

A list of Cases associated to the Indicator

Case Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}

associatedGroups

A list of Groups associated to the Indicator

Group Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}

associatedIndicators

A list of Indicators associated to the Indicator

Indicator Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“hostName”: “badguy.com”, “type”: “Host”}]}

attributes [1], [2]

A list of Attributes added to the Indicator

Indicator Attribute Object

FALSE

TRUE

{“data”: [{“type”: “Description”, “value”: “Malicious IOC”, “default”: true}]}

confidence

The Indicator’s Confidence Rating

Integer

FALSE

TRUE

1, 2, 3,…100

externalDateAdded

The date and time when the Indicator was created externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

externalDateExpires

The date and time when the Indicator expires externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

externalLastModified

The date and time when the Indicator was last modified externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

firstSeen

The date and time when the Indicator was first seen

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

lastSeen

The date and time when the Indicator was last seen

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

ownerId [3]

The ID of the owner to which the Indicator belongs

Integer

FALSE

FALSE

1, 2, 3,…100

ownerName [3]

The name of the owner to which the Indicator belongs

String

FALSE

FALSE

“Demo Community”

privateFlag

Indicates whether the Indicator is private

Boolean

FALSE

TRUE

true, false

rating

The Indicator’s Threat Rating

Big Decimal

FALSE

TRUE

1.0, 2.0, 3.0, 4.0, 5.0

securityLabels

A list of Security Labels applied to the Indicator

Security Label Object

FALSE

TRUE

{“data”: [{“name”: “TLP:AMBER”}]}

tags

A list of Tags applied to the Indicator

Tag Object

FALSE

TRUE

{“data”: [{“name”: “Targeted Attack”}]}

type [4]

The type of Indicator being created

String

TRUE

FALSE

“Address”, “Host”, “Registry Key”

Indicator-Specific Fields

Based on the type of Indicator being created, you may need to include additional fields in the body of a POST request. Similarly, some Indicator types include additional fields that may be updated via a PUT request.

The following tables list valid fields, some of which are required, that can be included in the body of a POST or PUT request for each Indicator type.

Address

Field

Description

Type

Required for Creation?

Updatable?

ip

The IP address associated with the Address Indicator

String

TRUE

FALSE

EmailAddress

Field

Description

Type

Required for Creation?

Updatable?

address

The email address associated with the Email Address Indicator

String

TRUE

FALSE

File

Field

Description

Type

Required for Creation?

Updatable?

fileActions

A list of File Actions associated with the File Indicator

File Action Object

FALSE

TRUE

fileOccurrences

A list of File Occurrences associated with the File Indicator

File Occurrence Object

FALSE

TRUE

md5

The MD5 hash associated with the File Indicator

String

TRUE [5]

FALSE

sha1

The SHA1 hash associated with the File Indicator

String

TRUE [5]

FALSE

sha256

The SHA256 hash associated with the File Indicator

String

TRUE [5]

FALSE

size

The size of the file associated with the File Indicator

String

FALSE

TRUE

Host

Field

Description

Type

Required for Creation?

Updatable?

dnsActive

Indicates whether the DNS feature is active for the Host Indicator

Boolean

FALSE

TRUE

hostName

The host name associated with the Host Indicator

String

TRUE

FALSE

whoisActive

Indicates whether the Whois feature is active for the Host Indicator

Boolean

FALSE

TRUE

URL

Field

Description

Type

Required for Creation?

Updatable?

text

The URL associated with the URL Indicator

String

TRUE

FALSE

ASN

Field

Description

Type

Required for Creation?

Updatable?

AS Number

The AS number associated with the ASN Indicator

String

TRUE

FALSE

CIDR

Field

Description

Type

Required for Creation?

Updatable?

Block

The block of network IP addresses associated with the CIDR Indicator

String

TRUE

FALSE

EmailSubject

Field

Description

Type

Required for Creation?

Updatable?

Subject

The subject line of the email associated with the Email Subject Indicator

String

TRUE

FALSE

Hashtag

Field

Description

Type

Required for Creation?

Updatable?

Hashtag

The hashtag term associated with the Hashtag Indicator

String

TRUE

FALSE

Mutex

Field

Description

Type

Required for Creation?

Updatable?

Mutex

The synchronization primitive used to identify malware files that is associated with the Mutex

String

TRUE

FALSE

Registry Key

Field

Description

Type

Required for Creation?

Updatable?

Key Name

The name of the registry key associated with the Registry Key Indicator

String

TRUE

FALSE

Value Name

The registry value associated with the Registry Key Indicator

String

TRUE

FALSE

Value Type [6]

The registry value type associated with the Registry Key Indicator

String

TRUE

FALSE

User Agent

Field

Description

Type

Required for Creation?

Updatable?

User Agent String

The characteristic identification string associated with the User Agent Indicator

String

TRUE

FALSE

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/indicators endpoint:

OPTIONS /v3/indicators/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/indicators endpoint:

OPTIONS /v3/indicators/tql

Create Indicators

The follow example illustrates the basic format for creating an Indicator:

POST /v3/indicators
Content-Type: application/json

{
    "type": "Indicator type goes here",
    //required fields for the selected Indicator type
}

Refer to the Available Fields and Indicator-Specific Fields sections for a list of available fields that can be included in the body of a POST request to the /v3/indicators endpoint.

Note

You can add multiple Attributes, Tags, and Security Labels to an Indicator in a single POST or PUT request.

Example POST Request

The following request will create an ultrabadguy.com Host Indicator. It will also complete the following actions for the Indicator:

  • Activate the DNS and Whois features for the Indicator

  • Set the Indicator Status for the Indicator to active

  • Associate the existing Group whose ID is 12 to the Indicator, and create a new Bad Guy Adversary Group in a Source and associate it to the Indicator

  • Add a Description (i.e., a default Description Attribute) to the Indicator

  • Set the Indicator’s Threat and Confidence Ratings

  • Apply the TLP:AMBER Security Label to the Indicator

  • Apply the Targeted Attack standard Tag and the T1566 - Phishing ATT&CK® Tag to the Indicator

Attention

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

Also, if you applied a new Tag to an Indicator and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to an Indicator and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Hint

To include the associatedGroups, attributes, securityLabels, and tags fields in the API response, append ?fields=associatedGroups&fields=attributes&fields=securityLabels&fields=tags to the end of the request URL.

POST /v3/indicators
Content-Type: application/json

{
    "type": "Host",
    "hostName": "ultrabadguy.com",
    "dnsActive": true,
    "whoisActive": true,
    "active": true,
    "associatedGroups": {
        "data": [
            {
                "id": 12
            },
            {
                "name": "Bad Guy",
                "type": "Adversary",
                "ownerName": "Demo Source"
            }
        ]
    },
    "attributes": {
        "data": [
            {
                "type": "Description",
                "value": "This host is very dangerous",
                "default": true
            }
        ]
    },
    "confidence": 85,
    "rating": 5,
    "securityLabels": {
        "data": [
            {
                "name": "TLP:AMBER"
            }
        ]
    },
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            },
            {
                "name": "Phishing"
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/4/overview",
        "type": "Host",
        "lastModified": "2021-11-05T16:43:17Z",
        "rating": 5.00,
        "confidence": 85,
        "description": "This host is very dangerous",
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "hostName": "ultrabadguy.com",
        "dnsActive": true,
        "whoisActive": true,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com&owner=Demo+Organization"
    },
    "message": "Created",
    "status": "Success"
}

Retrieve Indicators

Retrieve All Indicators

Send the following request to retrieve data for all Indicators:

GET /v3/indicators

JSON Response

{
    "data": [
        {
            "id": 10,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T13:07:08Z",
            "webLink": "https://app.threatconnect.com/#/details/indicators/10/overview",
            "type": "File",
            "lastModified": "2021-11-02T14:04:55Z",
            "summary": "F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "privateFlag": false,
            "active": true,
            "activeLocked": false,
            "md5": "F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "legacyLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=F5A2496CF66CB8CFFE66CB1B27D7DEDE&owner=Demo+Organization"
        },
        {
            "id": 9,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T12:34:03Z",
            "webLink": "https://app.threatconnect.com/#/details/indicators/9/overview",
            "type": "EmailAddress",
            "lastModified": "2021-11-02T12:48:51Z",
            "description": "A bad email address",
            "summary": "[email protected]",
            "privateFlag": false,
            "active": true,
            "activeLocked": false,
            "address": "[email protected]",
            "legacyLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=badguy%40bad.com&owner=Demo+Organization"
        },
        {...}
    ],
    "status": "Success"
}

Hint

Use the owner query parameter to limit the results to a specific owner.

Retrieve a Specific Indicator

Send a request in the following format to retrieve data for a specific Indicator:

GET /v3/indicators/{indicatorId or indicatorSummary}

For example, the following request will return data for the Indicator whose ID is 3:

GET /v3/indicators/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-10-26T12:40:00Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/3/overview",
        "type": "Host",
        "lastModified": "2021-11-02T14:58:55Z",
        "rating": 3.00,
        "confidence": 74,
        "description": "A bad host.",
        "summary": "badguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "hostName": "badguy.com",
        "dnsActive": true,
        "whoisActive": false,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=badguy.com&owner=Demo+Organization"
    },
    "status": "Success"
}

The same response will be returned for the following request was used, where the Indicator’s ID is replaced with its summary:

GET /v3/indicators/badguy.com

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-10-26T12:40:00Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/3/overview",
        "type": "Host",
        "lastModified": "2021-11-02T14:58:55Z",
        "rating": 3.00,
        "confidence": 74,
        "description": "A bad host.",
        "summary": "badguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "hostName": "badguy.com",
        "dnsActive": true,
        "whoisActive": false,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=badguy.com&owner=Demo+Organization"
    },
    "status": "Success"
}

Retrieve Deleted Indicators

Send the following request to retrieve data for all Indicators that have been deleted from your Organization recently:

GET /v3/indicators/deleted

JSON Response

{
    "data": [
        {
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T15:17:28Z",
            "type": "URL",
            "summary": "http://badsite.com"
        }
    ],
    "count": 1,
    "status": "Success"
}

To retrieve deleted Indicators from a Community or Source, use the owner query parameter. You can also use the type and deletedSince query parameters to limit the results by Indicator type and deletion date, respectively.

Note

The number of days for which deleted Indicators are retained is configured by your System Administrator.

Update Indicators

The following example illustrates the basic format for updating an Indicator:

PUT /v3/indicators/{indicatorId or indicatorSummary}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

Refer to the Available Fields and Indicator-Specific Fields sections for a list of available fields that can be included in the body of a PUT request to the /v3/indicators endpoint.

Hint

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

  • associatedArtifacts

  • associatedCases

  • associatedGroups

  • associatedIndicators

  • attributes

  • fileActions

  • fileOccurrences

  • securityLabels

  • tags

See Update an Object’s Metadata for instructions on using the mode field.

Example PUT Request

The following request will make the following updates to the ultrabadguy.com Host Indicator:

  • Disable the DNS feature for the Indicator

  • Dissociate the Bad Guy Adversary Group from the Indicator

  • Update the Indicator’s Confidence Rating

  • Replace any existing Security Labels applied to the Indicator with the TLP: RED Security Label

  • Apply a new Russia Tag to the Indicator without replacing any existing Tags applied to the Indicator.

Hint

To include the associatedGroups, securityLabels, and tags fields in the API response, append ?fields=associatedGroups&fields=securityLabels&fields=tags to the end of the request URL.

PUT /v3/indicators/ultrabadguy.com
Content-Type: application/json

{
    "dnsActive": false,
    "associatedGroups": {
        "data": [
            {
                "id": 15
            }
        ],
        "mode": "delete"
    },
    "confidence": 92,
    "securityLabels": {
        "data": [
            {
                "name": "TLP:RED"
            }
        ],
        "mode": "replace"
    },
    "tags": {
        "data": [
            {
                "name": "Russia"
            }
        ],
        "mode": "append"
    }
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/4/overview",
        "type": "Host",
        "lastModified": "2021-11-05T17:21:06Z",
        "rating": 5.00,
        "confidence": 92,
        "description": "This host is very dangerous",
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "hostName": "ultrabadguy.com",
        "dnsActive": false,
        "whoisActive": true,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com&owner=Demo+Organization"
    },
    "message": "Updated",
    "status": "Success"
}

Delete Indicators

Send a request in the following format to delete an Indicator:

DELETE /v3/indicators/{indicatorId or indicatorSummary}

For example, the following request will delete the Indicator whose ID is 3:

DELETE /v3/indicators/3

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

The same response will be returned for the following request, where the Indicator’s ID is replaced with its summary:

DELETE /v3/indicators/badguy.com

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

Associations

Create Associations

For instructions on associating Artifacts, Cases, and Groups to an Indicator, see Create and Manage Associations. For instructions on creating Indicator-to-Indicator associations, see the “Indicator-to-Indicator Associations” section.

Retrieve Custom Associations

When working with Indicators, you can retrieve data about an Indicator’s custom associations, including the name of the custom association and the Indicator involved in this association.

For example, the following request will retrieve data for the Indicator whose ID is 30, including information about its custom associations.

GET /v3/indicators/30?fields=customAssociations

JSON Response

{
    "data": {
        "id": 30,
        "dateAdded": "2023-06-26T15:23:28Z",
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/#/details/indicators/30/overview",
        "type": "Host",
        "lastModified": "2023-09-25T13:40:12Z",
        "confidence": 0,
        "summary": "zayla.co",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "customAssociations": {
            "data": [
                {
                    "id": 32,
                    "dateAdded": "2023-06-27T15:38:38Z",
                    "ownerId": 1,
                    "ownerName": "Demo Organization",
                    "webLink": "https://app.threatconnect.com/#/details/indicators/32/overview",
                    "type": "Address",
                    "lastModified": "2023-08-18T13:03:11Z",
                    "confidence": 0,
                    "summary": "107.180.48.66",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "customAssociationName": "DNS PTR Record",
                    "ip": "107.180.48.66",
                    "legacyLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=107.180.48.66&owner=Demo+Organization"
                },
                {
                    "id": 33,
                    "dateAdded": "2023-06-27T19:49:13Z",
                    "ownerId": 1,
                    "ownerName": "Demo Organization",
                    "webLink": "https://app.threatconnect.com/#/details/indicators/33/overview",
                    "type": "URL",
                    "lastModified": "2023-09-25T13:40:12Z",
                    "rating": 3.00,
                    "confidence": 0,
                    "summary": "http://www.badstuff.com",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "customAssociationName": "Host To All",
                    "text": "http://www.badstuff.com",
                    "legacyLink": "https://app.threatconnect.com/auth/indicators/details/url.xhtml?orgid=1&owner=Demo+Organization"
                }
            ],
            "count": 2
        },
        "hostName": "zayla.co",
        "dnsActive": false,
        "whoisActive": false,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=zayla.co&owner=Demo+Organization"
    },
    "status": "Success"
}

Indicator-to-Indicator Associations

In ThreatConnect, you can associate two Indicators of certain types to one another using the following methods:

  • Create an Indicator-to-Indicator Association

  • Create a File Action (for File Indicators)

Each type of Indicator-to-Indicator association contains one primary (or parent) Indicator type and at least one non-primary (or child) Indicator type, as defined on the Indicators tab of the System Settings screen in ThreatConnect. When creating Indicator-to-Indicator associations using the v3 API, you can only associate Indicators of the non-primary type(s) to Indicators of the primary type. For example, in an ASN to Address association, the ASN Indicator is the primary Indicator type and the Address Indicator is the non-primary Indicator type. This means you can associate an Address Indicator to an ASN Indicator, but you cannot associate an ASN Indicator to an Address Indicator.

When creating Indicator-to-Indicator associations using the ThreatConnect v3 API, follow these guidelines:

  • To create an association to a new Indicator of the non-primary type, include all fields required to create the type of Indicator when setting the associatedIndicators field. To create the Indicator in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting the associatedIndicators field.

  • To create an association to an existing Indicator of the non-primary type, use the Indicator’s ID, or use its type and summary type (e.g., "associatedIndicators": {"data": [{"type": "Host", "hostname": "badguy.com"}]}), when setting the associatedIndicators field. To create an association to an Indicator that exists in a Community or Source using the Indicator’s summary and type, include the ownerId or ownerName field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting the associatedIndicators field.

The following table outlines the default Indicator-to-Indicator associations in ThreatConnect and the Indicator types each association supports.

Association Name

Primary Indicator Type

Non-Primary Indicator Type(s)

Address to User Agent

Address

User Agent

ASN to Address

ASN

Address

ASN to CIDR

ASN

CIDR

CIDR to Address

CIDR

Address

DNS PTR Record

Address

Host

Domain Registrant Email

Host

EmailAddress

Domain Registrant Email

Host

EmailAddress

File Download

URL

File

URL Host

URL

Host, Address

Note

In addition to the association types listed in this table, customer-configured custom associations are also supported. Your System Administrator can retrieve information for these association types, including the primary and non-primary Indicator types the association supports, on the Indicators tab of the System Settings screen.

In the following example, the request will associate an existing Address Indicator to an existing ASN Indicator. Because the associatedIndicators field is not included in the API response by default, the fields query parameter is added to the request URL and assigned a value of associatedIndicators so that this field is included in the response.

PUT /v3/indicators/ASN204288?fields=associatedIndicators
Content-Type: application/json

{
    "associatedIndicators": {
        "data": [
            {
                "ip": "66.96.146.129",
                "type": "Address"
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 15,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-03-11T19:25:43Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/15/overview",
        "type": "ASN",
        "lastModified": "2022-06-13T18:25:30Z",
        "summary": "ASN204288",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedIndicators": {
            "data": [
                {
                    "id": 14,
                    "ownerId": 1,
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-10-08T13:48:05Z",
                    "webLink": "https://app.threatconnect.com/#/details/indicators/14/overview",
                    "type": "Address",
                    "lastModified": "2022-06-13T18:25:30Z",
                    "summary": "66.96.146.129",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "ip": "66.96.146.129",
                    "legacyLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=66.96.146.129&owner=Demo+Organization"
                }
            ]
        },
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=15&owner=Demo+Organization",
        "AS Number": "ASN204288"
    },
    "message": "Updated",
    "status": "Success"
}

If you try to associate an ASN Indicator to an Address Indicator, as in the following example, an error message will be returned stating that the association cannot be applied to the Indicator types.

PUT /v3/indicators/66.96.146.129
Content-Type: application/json

{
    "associatedIndicators": {
        "data": [
            {
                "AS Number": "ASN204288",
                "type": "ASN"
            }
        ]
    }
}

JSON Response

{
    "errCode": "0x1001",
    "message": "Association cannot be applied to the indicator types.",
    "status": "Error"
}

Note

In this example, the two Indicators would be associated and no error would be returned only if your System Administrator created a custom association where Address Indicators are the primary Indicator type and ASN Indicators are the non-primary Indicator type.

You can append, replace, and delete Indicator-to-Indicator associations via the mode field. See Update an Object’s Metadata for more information on using this field.

File Actions

File Indicators can model a special Indicator-to-Indicator association, which is based on their behavior once opened. These associations can be used to model the fact that malware may contain and create additional files or communicate with network devices. A File Action adds an Indicator to a File Indicator’s behavior model, which can be viewed on the Behavior tab of the File Indicator’s Details screen.

When creating File Actions using the v3 API, follow these guidelines:

  • To create an association to a new Indicator via a File Action, include all fields required to create the type of Indicator when setting the indicator field. To create the Indicator in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting the indicator field.

  • To create an association to an existing Indicator of the non-primary type, use the Indicator’s ID, or use its type and summary type (e.g., "indicator": {"data": [{"type": "Host", "hostname": "badguy.com"}]}), when setting the indicator field. To create an association to an Indicator that exists in a Community or Source using the Indicator’s summary and type, include the ownerId or ownerName field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting the indicator field.

The following table outlines the default File Actions available in ThreatConnect, along with the Indicator type(s) that can be associated to a File Indicator via each File Action.

File Action Name

Associable Indicator Type(s)

File Archive

File

File DNS Query

Host

File Drop

File

File Traffic

Address, Host, URL

File Mutex

Mutex

File Registry Key

Registry Key

File User Agent

User Agent

Note

In addition to the File Actions listed in this table, customer-configured custom File Actions are also supported. Your System Administrator can retrieve information for these File Actions, including the Indicator types the File Action supports, on the Indicators tab of the System Settings screen.

The following table outlines the fields you must include in your request when creating File Actions for a File Indicator.

Field

Description

Type

Required for Creation?

indicator

The Indicator being associated to the File Indicator via the specified File Action

Indicator Object

TRUE

relationship

The name of the File Action

String

TRUE

In the following example, the request will perform the following actions:

  • Create a new File Indicator based on an MD5 file hash

  • Create a new Address Indicator and associate it to the newly created File Indicator using the File Traffic File Action

  • Associate the existing File Indicator whose ID is 12 to the newly created File Indicator using the File Archive File Action

Because the fileActions field is not included in the API response by default, the fields query parameter is added to the request URL and assigned a value of fileActions so that this field is included in the response.

POST /v3/indicators?fields=fileActions
Content-Type: application/json

{
    "type": "File",
    "md5": "2ea0564f33e4cb67063c4a06734eb627",
    "fileActions": {
        "data": [
            {
                "relationship": "File Traffic",
                "indicator": {
                    "type": "Address",
                    "ip": "66.96.146.132"
                }
            },
            {
                "relationship": "File Archive",
                "indicator": {
                    "id": 12
                }
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 18,
        "ownerId": 18,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-06-14T12:57:53Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/18/overview",
        "type": "File",
        "lastModified": "2022-06-14T12:57:53Z",
        "summary": "2EA0564F33E4CB67063C4A06734EB627",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "fileActions": {
            "data": [
                {
                    "relationship": "File Archive",
                    "indicator": {
                        "id": 12,
                        "id": 1,
                        "ownerName": "Demo Organization",
                        "dateAdded": "2022-05-27T12:42:28Z ",
                        "webLink": "https://app.threatconnect.com/#/details/indicators/12/overview",
                        "type": "File",
                        "lastModified": "2022-05-27T12:42:28Z ",
                        "summary": "FB69E1273E7A53AD8E9BBE64B80859FC",
                        "privateFlag": false,
                        "active": true,
                        "activeLocked": false,
                        "fileActions": {
                            "count": 0
                        },
                        "md5": "FB69E1273E7A53AD8E9BBE64B80859FC",
                        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=FB69E1273E7A53AD8E9BBE64B80859FC&owner=Demo+Organization"
                    }
                },
                {
                    "relationship": "File Traffic",
                    "indicator": {
                        "id": 19,
                        "ownerId": 1,
                        "ownerName": "Demo Organization",
                        "dateAdded": "2022-06-14T12:57:53Z",
                        "webLink": "https://app.threatconnect.com/#/details/indicators/19/overview",
                        "type": "Address",
                        "lastModified": "2022-06-14T12:57:53Z",
                        "summary": "66.96.146.132",
                        "privateFlag": false,
                        "active": true,
                        "activeLocked": false,
                        "fileActions": {
                            "count": 0
                        },
                        "ip": "66.96.146.132",
                        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=66.96.146.132&owner=Demo+Organization"
                    }
                }
            ],
            "count": 2
        },
        "md5": "2EA0564F33E4CB67063C4A06734EB627",
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=2EA0564F33E4CB67063C4A06734EB627&owner=Demo+Organization"
    },
    "message": "Created",
    "status": "Success"
}

You can append, replace, and delete File Actions via the mode field. See Update an Object’s Metadata for more information on using this field.

File Occurrences

Create a File Occurrence

The following table outlines the fields available when creating File Occurrences for a File Indicator.

Field

Description

Type

Required for Creation?

date

The date and time of the File Occurrence

Date

FALSE*

fileName

The name of the file corresponding to the File Occurrence

String

FALSE*

path

The run path for the file corresponding to the File Occurrence

String

FALSE*

Note

*While none of these fields are required, you must include at least one of them to create a File Occurrence.

In the following example, the request will add a File Occurrence to the existing File Indicator whose ID is 20. Because the fileOccurrences field is not included in the API response by default, the fields query parameter is added to the request URL and assigned a value of fileOccurrences so that this field is included in the response.

PUT /v3/indicators/20?fields=fileOccurrences
Content-Type: application/json

{
    "fileOccurrences": {
        "data": [
            {
                "fileName": "win999301.dll",
                "path": "C:\\\\Windows\\System",
                "date": "2022-06-14T10:00:00Z"
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 20,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-06-14T13:59:54Z",
        "webLink": "https://appthreatconnect.com/#/details/indicators/20/overview",
        "type": "File",
        "lastModified": "2022-06-14T14:00:11Z",
        "summary": "9D67E81C18101FC266057CD7851604B8",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "fileOccurrences": {
            "data": [
                {
                    "id": 5,
                    "fileName": "win999301.dll",
                    "path": "C:\\\\Windows\\System",
                    "date": "2022-06-14T10:00:00Z"
                }
            ],
            "count": 1
        },
        "md5": "9D67E81C18101FC266057CD7851604B8",
        "legacyLink": "https://appthreatconnect.com/auth/indicators/details/file.xhtml?file=9D67E81C18101FC266057CD7851604B8&owner=Demo+Organization"
    },
    "message": "Updated",
    "status": "Success"
}

Manage an Indicator’s File Actions

You can append, replace, and delete File Occurrences via the mode field. If deleting a File Occurrence, use the File Occurrence’s ID when constructing your request. For example, the following request will delete the File Occurrence whose ID is 5 added to the File Indicator whose ID is 20:

PUT /v3/indicators/20
Content-Type: application/json

{
    "fileOccurrences": {
        "data": [
            {
                "id": 5
            }
        ],
        "mode": "delete"
    }
}

For more information on using the mode field, see Update an Object’s Metadata.

Hint

Send a request in the following format to retrieve a File Occurrence’s ID:

GET v3/indicators/{fileIndicatorId or fileIndicatorSummary}?fields=fileOccurrences

Merge File Hashes

If adding a new file hash to an existing File Indicator and a File Indicator containing that file hash exists in the same owner, you can merge the two File Indicators into a single File Indicator containing both file hashes and any Attributes, Security Labels, and Tags added to each Indicator.

You can merge only File Indicators containing different file hash types. For example, you can merge a File Indicator containing an MD5 file hash with a File Indicator containing a SHA1 file hash, but you cannot merge two File Indicators containing MD5 file hashes.

Attention

You cannot merge multiple hash values at once. For example, if you want to merge three separate File Indicators, each of which contains a unique file hash type, you must submit two separate requests: one to merge the first two file hash types (e.g., MD5 and SHA1) and another to merge the last file hash type (e.g., SHA256).

The following request will update an existing File Indicator containing an MD5 file hash (AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA) and add a SHA1 file hash (BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB) to it. Because another File Indicator containing this SHA1 file hash exists in the same owner as the File Indicator being updated, "mode": "merge" will be included in the body of the request to merge the two File Indicators into a single File Indicator.

PUT /v3/indicators/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Type: application/json

{
    "sha1": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "mode": "merge"
}

JSON Response

{
    "data": {
        "id": 28,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2023-01-27T17:03:38Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/28/overview",
        "type": "File",
        "lastModified": "2023-01-27T17:09:03Z",
        "summary": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA : BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "md5": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "sha1": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&owner=Demo+Organization"
    },
    "message": "Updated",
    "status": "Success"
}

To remove a single file hash from a File Indicator, include "mode": "delete" in the body of the request. For example, the following request will remove the SHA1 file hash (BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB) just added to the File Indicator containing an MD5 file hash (AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA). Note that the Indicator’s summary is encoded in the URL for this request.

PUT /v3/indicators/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%20%3A%20BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
Content-Type: application/json

{
    "sha1": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "mode": "delete"
}

JSON Response

{
    "data": {
        "id": 28,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2023-01-27T17:03:38Z",
        "webLink": "https://app.threatconnect.com/#/details/indicators/28/overview",
        "type": "File",
        "lastModified": "2023-01-27T17:15:42Z",
        "summary": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "md5": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&owner=Demo+Organization"
    },
    "message": "Updated",
    "status": "Success"
}

MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.