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] A list of Attributes added to the Indicator Indicator Attribute Object FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”}]}
confidence The Indicator’s Confidence Rating Integer FALSE TRUE 1, 2, 3,…100
ownerId [2] The ID of the owner to which the Indicator belongs Integer FALSE FALSE 1, 2, 3,…100
ownerName [2] The name of the owner to which the Indicator belongs String FALSE FALSE “Demo Community”
privateFlag Indicates where 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 [3] The type of Indicator being created String TRUE FALSE “Address”, “Host”, “Registry Key”
[1]To retrieve a list of available Attribute Types, send the following request: GET /v3/attributeTypes.
[2](1, 2) By default, Indicators will be created in the Organization in which your API user account resides. To create an Indicator in a Community or Source, include the ownerId or ownerName field in your request. Alternatively, use the owner query parameter to specify the owner in which to create the Indicator.
[3]

The following are accepted values for the type field:

  • Address
  • EmailAddress
  • File
  • Host
  • URL
  • ASN
  • CIDR
  • EmailSubject
  • Hashtag
  • Mutex
  • Registry Key
  • User Agent

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 [4] FALSE
sha1 The SHA1 hash associated with the File Indicator String TRUE [4] FALSE
sha256 The SHA256 hash associated with the File Indicator String TRUE [4] FALSE
size The size of the file associated with the File Indicator String FALSE TRUE
[4](1, 2, 3) When creating a File Indicator, you must include at least one valid hash.

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 [5] The registry value type associated with the Registry Key Indicator String TRUE FALSE
[5]

The following are accepted values for a Registry Key Indicator’s Value Type field:

  • 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

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
{
    "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 an Additional Analysis and Context Attribute to the Indicator
  • Set the Indicator’s Threat and Confidence Ratings
  • Apply the TLP:AMBER Security Label to the Indicator
  • Apply Targeted Attack and Malicious Host Tags to the Indicator

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
{
    "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": "Additional Analysis and Context", "value": "This host is very dangerous", "source": "Phase of Intrusion"}]},
    "confidence": 85,
    "rating": 5,
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "tags": {"data": [{"name": "Targeted Attack"}, {"name": "Malicious Host"}]}
}

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

Create Associations

You can create associations between Indicators and Artifacts, Cases, Groups, and Indicators that exist in the same owner. If cross-owner associations are enabled on your ThreatConnect instance, you can also create associations between Indicators and Groups and other Indicators that exist in any owner to which you have access. When creating associations for Indicators using the ThreatConnect v3 API, follow these guidelines:

  • To create an association to a new Artifact, include all fields required to create an Artifact when setting the associatedArtifacts field.
  • To create an association to an existing Artifact, use the Artifact’s ID when setting the associatedArtifacts field (e.g., "associatedArtifacts": {"data": [{"id": 12345}]}).
  • To create an association to a new Case, include all fields required to create a Case when setting the associatedCases field.
  • To create an association to an existing Case, use the Case’s ID when setting the associatedCases field.
  • To create an association to a new Group, include all fields required to create the type of Group when setting the associatedGroups field. To create the Group 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 Group when setting the associatedGroups field.
  • To create an association to an existing Group, use the Group’s ID when setting the associatedGroups field.
  • If creating an Indicator-to-Indicator associations, see the “Indicator-to-Indicator Associations” section for further instruction.

Note

You can associate multiple Artifacts, Cases, Groups, and Indicators to an Indicator in a single POST or PUT request.

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

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)

Create an Indicator-to-Indicator Association

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
{
    "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
{
    "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.

Manage an Indicator’s Indicator-to-Indicator Associations

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.

Create a File Action

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

Manage an Indicator’s File Actions

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