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

Available Fields

You can retrieve a list of available fields for the /v3/indicators endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/indicators

Hint

To view all fields, including read-only fields, include the ?show=readonly query parameter.

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 A list of Attributes corresponding 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 {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}}
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 The type of Indicator being created String TRUE FALSE “Address”, “Host”, “Registry Key”

Accepted values for the type field include:

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

Note

A list of available Attribute Types can be retrieved with the following query:

GET /v3/attributeTypes

Hint

To associate an existing Artifact, Case, or Group to an Indicator, use the object’s ID when setting the associatedArtifacts, associatedCases, or associatedGroups field, respectively (e.g., {"data": [{"id": 12345}]}).

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* FALSE
sha1 The SHA1 hash associated with the File Indicator String TRUE* FALSE
sha256 The SHA256 hash associated with the File Indicator String TRUE* FALSE
size The size of the file associated with the File Indicator String FALSE TRUE

Note

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

Accepted values for the Value Type field include:

  • 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

Create Indicators

The basic format for creating an Indicator is:

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 for the indicators object.

Note

You can add multiple Attributes, Tags, and Security Labels to the Indicator being created in a single POST request. Similarly, you can associate multiple Artifacts, Cases, and Groups to the Indicator being created in a single POST request.

Example POST Request

The following query will create a Host Indicator with a host name of ultrabadguy.com. Note that all optional fields available for the indicators object are included in this request.

POST /v3/indicators
{
    "type": "Host",
    "hostName": "ultrabadguy.com",
    "dnsActive": true,
    "whoisActive": true,
    "active": true,
    "activeLocked": false,
    "associatedGroups": {"data": [{"id": 12}, {"name": "Bad Guy", "type": "Adversary"}]},
    "attributes": {"data": [{"type": "Additional Analysis and Context", "value": "This host is very dangerous", "source": "Phase of Intrusion"}]},
    "confidence": 85,
    "privateFlag": false,
    "rating": 5,
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "tags": {"data": [{"name": "Targeted Attack"}, {"name": "Malicious Host"}]}
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
        "tags": {
            "data": [
                {
                    "id": 10,
                    "name": "Malicious Host",
                    "description": "A tag that can be applied to malicious Host Indicators.",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 11,
                    "name": "Targeted Attack",
                    "lastUsed": "2021-11-05T16:43:17Z"
                }
            ]
        },
        "securityLabels": {
            "data": [{
                "id": 3,
                "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.",
                "color": "FFC000",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "type": "Host",
        "lastModified": "2021-11-05T16:43:17Z",
        "rating": 5.0,
        "confidence": 85,
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {
            "data": [
                {
                    "id": 15,
                    "type": "Adversary",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-11-05T16:43:17Z",
                    "webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=15",
                    "name": "Bad Guy",
                    "createdBy": {
                        "id": 3,
                        "userName": "11112222333344445555",
                        "firstName": "John",
                        "lastName": "Smith",
                        "pseudonym": "jsmithAPI",
                        "role": "Api User"
                    }
                },
                {
                    "id": 12,
                    "type": "Incident",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-08-27T12:16:56Z",
                    "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12",
                    "name": "Dangerous Incident",
                    "createdBy": {
                        "id": 1,
                        "userName": "[email protected]",
                        "firstName": "John",
                        "lastName": "Smith",
                        "pseudonym": "JMS",
                        "role": "Administrator"
                    }
                }
            ]
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                "lastModified": "2021-11-05T16:43:17Z",
                "rating": 5.0,
                "confidence": 85,
                "source": "A Reliable Source",
                "description": "Potentially malicious host related to malware dissemination.",
                "summary": "ultrabadguy.com",
                "privateFlag": false,
                "active": true,
                "activeLocked": false,
                "hostName": "ultrabadguy.com",
                "dnsActive": true,
                "whoisActive": true
            }]
        },
        "fileActions": {
            "count": 0
        },
        "attributes": {
            "data": [{
                "id": 24,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }]
        },
        "associatedCases": {},
        "associatedArtifacts": {},
        "hostName": "ultrabadguy.com",
        "dnsActive": true,
        "whoisActive": true
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating or updating an Indicator, you can apply Tags that do not yet exist in ThreatConnect to it. To do so, fill out all required fields for each new Tag. Upon creation of the new Indicator, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Similarly, you can associate Artifacts, Cases, and Groups that do not yet exist in ThreatConnect to the Indicator. To do so, fill out all required fields for the type of object being associated to the Indicator. Upon creation of the new Indicator, any associated Artifacts, Cases, or Groups included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Retrieve Indicators

Retrieve All Indicators

To retrieve all Indicators, use the following query:

GET /v3/indicators

JSON Response

{
    "data": [
        {
            "id": 10,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T13:07:08Z",
            "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "type": "File",
            "lastModified": "2021-11-02T14:04:55Z",
            "summary": "F5A2496CF66CB8CFFE66CB1B27D7DEDE",
            "privateFlag": false,
            "active": true,
            "activeLocked": false,
            "md5": "F5A2496CF66CB8CFFE66CB1B27D7DEDE"
        },
        {
            "id": 9,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-11-02T12:34:03Z",
            "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=badguy%40bad.com",
            "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]"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Indicator

Specific Indicators can be retrieved by either their ID or summary. The basic format for retrieving an Indicator is:

GET /v3/indicators/{indicatorId or indicatorSummary}

For example, the following query will return information about the Indicator with ID 3:

GET /v3/indicators/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-10-26T12:40:00Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=badguy.com",
        "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
    },
    "status": "Success"
}

The same response would be returned if we used the following request, where the Indicator’s ID is replaced with its summary:

GET /v3/indicators/badguy.com

Retrieve Deleted Indicators

To retrieve Indicators that have been recently deleted from an owner, use the following query:

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

By default, this query will return all Indicators recently deleted in the API key’s default Organization. You can specify a different owner by including the ?owner= query parameter in your query.

Note

The indicatorDeleteRetentionTime system setting determines the number of days to retain deleted Indicators.

Request Additional Fields

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Indicators

The basic format for updating an Indicator is:

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 for the indicators object.

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 query will complete the following actions for 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 an existing Security Label applied to the Indicator with a TLP: Red Security Label
  • Apply a new Russia Tag to the Indicator without replacing any existing Tags applied to the Indicator.
PUT /v3/indicators/ultrabadguy.com
{
    "dnsActive": false,
    "associatedGroups": {"id": 15}], "mode": "delete"},
    "confidence": 92,
    "securityLabels": {"data": [{"name": "TLP:RED"}], "mode": "replace"},
    "tags": {"data": [{"name": "Russia"}], "mode": "append"}
}

JSON Response

{
    "data": {
        "id": 4,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-05T16:43:17Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
        "tags": {
            "data": [
                {
                    "id": 10,
                    "name": "Malicious Host",
                    "description": "A tag that can be applied to malicious Host Indicators.",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 11,
                    "name": "Targeted Attack",
                    "lastUsed": "2021-11-05T16:43:17Z"
                },
                {
                    "id": 12,
                    "name": "Russia",
                    "lastUsed": "2021-11-05T17:21:07Z"
                }
            ]
        },
        "securityLabels": {
            "data": [{
                "id": 4,
                "name": "TLP:RED",
                "description": "This security label is used for information that cannot be effectively acted upon by additional parties, and could lead to impacts on a party's privacy, reputation, or operations if misused.",
                "color": "FF0033",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "lastModified": "2021-11-05T17:21:06Z",
        "type": "Host",
        "rating": 5.0,
        "confidence": 92,
        "summary": "ultrabadguy.com",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {
            "data": [{
                "id": 12,
                "type": "Incident",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-08-27T12:16:56Z",
                "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12",
                "name": "Dangerous Incident",
                "createdBy": {
                    "id": 1,
                    "userName": "[email protected]",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "JMS",
                    "role": "Administrator"
                }
            }]
        },
        "associatedIndicators": {
            "data": [{
                "id": 4,
                "type": "Host",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-11-05T16:43:17Z",
                "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                "lastModified": "2021-11-05T17:21:07Z",
                "rating": 5.0,
                "confidence": 92,
                "source": "A Reliable Source",
                "description": "Potentially malicious host related to malware dissemination.",
                "summary": "ultrabadguy.com",
                "privateFlag": false,
                "active": true,
                "activeLocked": false,
                "hostName": "ultrabadguy.com",
                "dnsActive": false,
                "whoisActive": true
            }]
        },
        "fileActions": {
            "count": 0
        },
        "attributes": {
            "data": [{
                "id": 24,
                "type": "Additional Analysis and Context",
                "value": "This host is very dangerous",
                "source": "Phase of Intrusion",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T16:43:17Z",
                "lastModified": "2021-11-05T16:43:17Z",
                "default": false
            }]
        },
        "associatedCases": {},
        "associatedArtifacts": {},
        "hostName": "ultrabadguy.com",
        "dnsActive": false,
        "whoisActive": true
    },
    "message": "Updated",
    "status": "Success"
}

Delete Indicators

The basic format for deleting an Indicator is:

DELETE /v3/indicators/{indicatorId or indicatorSummary}

For example, the following query will delete the Indicator with ID 3:

DELETE /v3/indicators/3

JSON Response

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

The same response would be returned if we used the following request, where the Indicator ID is replaced with the Indicator’s summary:

DELETE /v3/indicators/badguy.com

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, you can only associate Indicators of the non-primary type(s) to Indicators of the primary type.

For example, when creating an ASN to Address association, you can associate an Address Indicator (the non-primary Indicator type) to an ASN Indicator (the primary Indicator type). If you try to associate an ASN Indicator (the primary Indicator type) to an Address Indicator (the non-primary Indicator type) when creating the association, an error will be returned.

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

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.

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

In the following example, the query will associate an Address Indicator to an existing ASN Indicator:

PUT /v3/indicators/ASN204288
{
    "associatedIndicators": {"data": [{"ip": "66.96.146.129", "type": "Address"}]}
}

JSON Response

{
    "data": {
        "id": 15,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-03-11T19:25:43Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/customIndicator.xhtml?id=15",
        "tags": {},
        "securityLabels": {},
        "type": "ASN",
        "lastModified": "2022-06-13T18:25:30Z",
        "summary": "ASN204288",
        "privateFlag": true,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {},
        "associatedIndicators": {
            "data": [
                {
                    "id": 14,
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-10-08T13:48:05Z",
                    "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=66.96.146.129",
                    "type": "Address",
                    "lastModified": "2022-06-13T18:22:47Z",
                    "summary": "66.96.146.129",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "ip": "66.96.146.129"
                }
            ]
        },
        "fileActions": {
            "count": 0
        },
        "attributes": {},
        "associatedCases": {},
        "associatedArtifacts": {},
        "AS Number": "ASN204288"
    },
    "message": "Updated",
    "status": "Success"
}

If you try to associate an ASN Indicator (i.e., the Indicator with ID 15) 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": [{"id": 15}]}
}

JSON Response

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

Note

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, then the two Indicators will be associated and no error will be returned.

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.

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.

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.

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

Create a File Action

The following table outlines the fields available 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 query will:

  • 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 an existing File Indicator to the newly created File Indicator using the File Archive File Action
POST /v3/indicators

{
    "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,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-06-14T12:57:53Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=2EA0564F33E4CB67063C4A06734EB627",
        "tags": {},
        "securityLabels": {},
        "type": "File",
        "lastModified": "2022-06-14T12:57:53Z",
        "summary": "2EA0564F33E4CB67063C4A06734EB627",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {},
        "associatedIndicators": {
            "data": [
                {
                    "id": 19,
                    "ownerName": "Demo Organization",
                    "dateAdded": "2022-06-14T12:57:53Z",
                    "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=66.96.146.132",
                    "type": "Address",
                    "lastModified": "2022-06-14T12:57:53Z",
                    "summary": "66.96.146.132",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "ip": "66.96.146.132"
                },
                {
                    "id": 12,
                    "ownerName": "Demo Organization",
                    "dateAdded": "2022-05-27T12:42:28Z",
                    "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=FB69E1273E7A53AD8E9BBE64B80859FC",
                    "type": "File",
                    "lastModified": "2022-05-27T12:42:28Z ",
                    "summary": "FB69E1273E7A53AD8E9BBE64B80859FC",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "md5": "FB69E1273E7A53AD8E9BBE64B80859FC"
                }
            ]
        },
        "fileActions": {
            "data": [
                {
                    "relationship": "File Archive",
                    "indicator": {
                        "id": 12,
                        "ownerName": "Demo Organization",
                        "dateAdded": "2022-05-27T12:42:28Z ",
                        "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=FB69E1273E7A53AD8E9BBE64B80859FC",
                        "tags": {},
                        "securityLabels": {},
                        "type": "File",
                        "lastModified": "2022-05-27T12:42:28Z ",
                        "summary": "FB69E1273E7A53AD8E9BBE64B80859FC",
                        "privateFlag": false,
                        "active": true,
                        "activeLocked": false,
                        "associatedGroups": {},
                        "associatedIndicators": {
                            "data": [
                                {
                                    "id": 18,
                                    "ownerName": "Demo Organization",
                                    "dateAdded": "2022-06-14T12:57:53Z",
                                    "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=2EA0564F33E4CB67063C4A06734EB627",
                                    "type": "File",
                                    "lastModified": "2022-06-14T12:57:53Z",
                                    "summary": "2EA0564F33E4CB67063C4A06734EB627",
                                    "privateFlag": false,
                                    "active": true,
                                    "activeLocked": false,
                                    "md5": "2EA0564F33E4CB67063C4A06734EB627"
                                }
                            ]
                        },
                        "fileActions": {
                            "count": 0
                        },
                        "attributes": {},
                        "associatedCases": {},
                        "associatedArtifacts": {},
                        "md5": "FB69E1273E7A53AD8E9BBE64B80859FC"
                    }
                },
                {
                    "relationship": "File Traffic",
                    "indicator": {
                        "id": 19,
                        "ownerName": "Demo Organization",
                        "dateAdded": "2022-06-14T12:57:53Z",
                        "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=66.96.146.132",
                        "tags": {},
                        "securityLabels": {},
                        "type": "Address",
                        "lastModified": "2022-06-14T12:57:53Z",
                        "summary": "66.96.146.132",
                        "privateFlag": false,
                        "active": true,
                        "activeLocked": false,
                        "associatedGroups": {},
                        "associatedIndicators": {
                            "data": [
                                {
                                    "id": 18,
                                    "ownerName": "Demo Organization",
                                    "dateAdded": "2022-06-14T12:57:53Z",
                                    "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=2EA0564F33E4CB67063C4A06734EB627",
                                    "type": "File",
                                    "lastModified": "2022-06-14T12:57:53Z",
                                    "summary": "2EA0564F33E4CB67063C4A06734EB627",
                                    "privateFlag": false,
                                    "active": true,
                                    "activeLocked": false,
                                    "md5": "2EA0564F33E4CB67063C4A06734EB627"
                                }
                            ]
                        },
                        "fileActions": {
                            "count": 0
                        },
                        "attributes": {},
                        "associatedCases": {},
                        "associatedArtifacts": {},
                        "ip": "66.96.146.132"
                    }
                }
            ],
            "count": 2
        },
        "attributes": {},
        "associatedCases": {},
        "associatedArtifacts": {},
        "md5": "2EA0564F33E4CB67063C4A06734EB627"
    },
    "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 query will add a File Occurrence to the existing File Indicator with ID 20:

PUT /v3/indicators/20

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

JSON Response

{
    "data": {
        "id": 20,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-06-14T13:59:54Z",
        "webLink": "https://app.threatconnect.com/auth/indicators/details/file.xhtml?file=9D67E81C18101FC266057CD7851604B8",
        "tags": {},
        "securityLabels": {},
        "type": "File",
        "lastModified": "2022-06-14T14:00:11Z",
        "summary": "9D67E81C18101FC266057CD7851604B8",
        "privateFlag": false,
        "active": true,
        "activeLocked": false,
        "associatedGroups": {},
        "associatedIndicators": {},
        "fileActions": {
            "count": 0
        },
        "attributes": {},
        "associatedCases": {},
        "associatedArtifacts": {},
        "md5": "9D67E81C18101FC266057CD7851604B8"
    },
    "message": "Updated",
    "status": "Success"
}

By default, the fileOccurrences field is not included in the response that is returned when retrieving, creating, and updating Indicators. To include this field in responses returned by the API, include the ?fields=fileOccurrences query parameter in your request.

For comparison, the following example uses the same request in the preceding example with the ?fields=fileOccurrences query parameter added to it:

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,
        "ownerName": "Demo Organization",
        "dateAdded": "2022-06-14T13:59:54Z",
        "webLink": "https://appthreatconnect.com/auth/indicators/details/file.xhtml?file=9D67E81C18101FC266057CD7851604B8",
        "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"
    },
    "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 query. For example, the following query will delete the File Occurrence with ID 5 added to the File Indicator with 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

You can retrieve a File Occurrence’s ID by submitting a request in the following format:

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