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