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, an Organization can have only one copy of the badguy@bad.com Email Address Indicator.

Endpoint: /api/v3/indicators

Note

When retrieving, updating, and deleting Indicators, you can target a specific Indicator using its ID or summary. If targeting an Indicator by its summary, the API request will search for the Indicator in your Organization. To target an Indicator in one of your Communities or Sources by its summary, use the owner query parameter in your API request.

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

Note

Objects in the response for an OPTIONS /v3/indicators request that have a common field with a value of true correspond to API fields that can be updated by API users with read-only permissions (that is, API users with an Organization role of Read Only User or Read Only Commenter, as well as API users with a Community role of User, Commenter, or Subscriber in a given Community or Source) if the v3ApiReadOnlyReports system setting is turned on for your ThreatConnect instance.

Hint

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

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

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
active	Indicates whether the Indicator is active	Boolean	FALSE	TRUE	true, false
activeLocked	Indicates whether the active Indicator Status is locked	Boolean	FALSE	TRUE	true, false
associatedArtifacts	A list of Artifacts associated to the Indicator	Artifact Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}
associatedCases	A list of Cases associated to the Indicator	Case Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}
associatedGroups	A list of Groups associated to the Indicator	Group Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
associatedIndicators	A list of Indicators associated to the Indicator	Indicator Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“hostName”: “badguy.com”, “type”: “Host”}]}
attributes [1], [2]	A list of Attributes added to the Indicator	Indicator Attribute Object	FALSE	TRUE	{“data”: [{“type”: “Description”, “value”: “Malicious IOC”, “default”: true}]}
confidence	The Indicator’s Confidence Rating	Integer	FALSE	TRUE	1, 2, 3,…100
externalDateAdded	The date and time when the Indicator was created externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
externalDateExpires	The date and time when the Indicator expires externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
externalLastModified	The date and time when the Indicator was last modified externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
falsePositiveFlag	Indicates whether the Indicator is a false positive	Boolean	FALSE	TRUE	true, false
firstSeen	The date and time when the Indicator was first seen	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
lastSeen	The date and time when the Indicator was last seen	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
observations	The number of times the Indicator was observed	Integer	FALSE	TRUE	1, 2, 3,…
ownerId [3]	The ID of the owner to which the Indicator belongs	Integer	FALSE	FALSE	1, 2, 3,…100
ownerName [3]	The name of the owner to which the Indicator belongs	String	FALSE	FALSE	“Demo Community”
privateFlag	Indicates whether the Indicator is private	Boolean	FALSE	TRUE	true, false
rating	The Indicator’s Threat Rating	Big Decimal	FALSE	TRUE	1.0, 2.0, 3.0, 4.0, 5.0
securityLabels	A list of Security Labels applied to the Indicator	Security Label Object	FALSE	TRUE	{“data”: [{“name”: “TLP:AMBER”}]}
tags	A list of Tags applied to the Indicator	Tag Object	FALSE	TRUE	{“data”: [{“name”: “Targeted Attack”}]}
type [4]	The type of Indicator being created	String	TRUE	FALSE	“Address”, “Host”, “Registry Key”

Indicator-Specific Fields

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

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

Address

Field	Description	Type	Required for Creation?	Updatable?
ip	The IP address associated with the Address Indicator	String	TRUE	FALSE

EmailAddress

Field	Description	Type	Required for Creation?	Updatable?
address	The email address associated with the Email Address Indicator	String	TRUE	FALSE

File

Field	Description	Type	Required for Creation?	Updatable?
fileActions	A list of File Actions associated with the File Indicator	File Action Object	FALSE	TRUE
fileOccurrences	A list of File Occurrences associated with the File Indicator	File Occurrence Object	FALSE	TRUE
md5	The MD5 hash associated with the File Indicator	String	TRUE [5]	FALSE
sha1	The SHA1 hash associated with the File Indicator	String	TRUE [5]	FALSE
sha256	The SHA256 hash associated with the File Indicator	String	TRUE [5]	FALSE
size	The size of the file associated with the File Indicator	String	FALSE	TRUE

Host

Field	Description	Type	Required for Creation?	Updatable?
dnsActive	Indicates whether the DNS feature is active for the Host Indicator	Boolean	FALSE	TRUE
hostName	The host name associated with the Host Indicator	String	TRUE	FALSE
whoisActive	Indicates whether the Whois feature is active for the Host Indicator	Boolean	FALSE	TRUE

URL

Field	Description	Type	Required for Creation?	Updatable?
text	The URL associated with the URL Indicator	String	TRUE	FALSE

ASN

Field	Description	Type	Required for Creation?	Updatable?
AS Number	The AS number associated with the ASN Indicator	String	TRUE	FALSE

CIDR

Field	Description	Type	Required for Creation?	Updatable?
Block	The block of network IP addresses associated with the CIDR Indicator	String	TRUE	FALSE

Email Subject

Field	Description	Type	Required for Creation?	Updatable?
Subject	The subject line of the email associated with the Email Subject Indicator	String	TRUE	FALSE

Hashtag

Field	Description	Type	Required for Creation?	Updatable?
Hashtag	The hashtag term associated with the Hashtag Indicator	String	TRUE	FALSE

Mutex

Field	Description	Type	Required for Creation?	Updatable?
Mutex	The synchronization primitive used to identify malware files that is associated with the Mutex	String	TRUE	FALSE

Registry Key

Field	Description	Type	Required for Creation?	Updatable?
Key Name	The name of the registry key associated with the Registry Key Indicator	String	TRUE	FALSE
Value Name	The registry value associated with the Registry Key Indicator	String	TRUE	FALSE
Value Type [6]	The registry value type associated with the Registry Key Indicator	String	TRUE	FALSE

User Agent

Field	Description	Type	Required for Creation?	Updatable?
User Agent String	The characteristic identification string associated with the User Agent Indicator	String	TRUE	FALSE

Include Additional Fields in Responses

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

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

OPTIONS /v3/indicators/fields

Filter Results

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

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

OPTIONS /v3/indicators/tql

Create Indicators

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

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

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

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

Note

If you send a POST request to create an Indicator that already exists in the owner where the API request is creating data, the existing Indicator will be updated instead of a new one being created. This is because each owner can have only one copy of a given Indicator. For example, a single Organization can have only one copy of the Email Address Indicator badguy@bad.com.

Note

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

Example POST Request

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

Activate the DNS and Whois features for the Indicator
Set the Indicator Status for the Indicator to active
Associate the existing Group whose ID is 12 to the Indicator, and create a new Bad Guy Adversary Group in a Source and associate it to the Indicator
Add a Description (i.e., a default Description Attribute) to the Indicator
Set the Indicator’s Threat and Confidence Ratings
Apply the TLP:AMBER Security Label to the Indicator
Apply the Targeted Attack standard Tag and the T1566 - Phishing ATT&CK® Tag to the Indicator

Attention

To apply an ATT&CK Tag to an Indicator, use either the corresponding technique ID or name. For example, to apply the T1566 - Phishing ATT&CK Tag to an Indicator, either set name to "Phishing" or techniqueId to "T1566" when defining the ATT&CK Tag object in the request body.

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

Hint

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

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

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

JSON Response

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

Retrieve Indicators

Note

By default, only active Indicators will be included in responses for GET requests to the /v3/indicators endpoint.

Retrieve All Indicators

Send the following request to retrieve data for all Indicators:

GET /v3/indicators

JSON Response

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

Hint

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

Retrieve a Specific Indicator

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

GET /v3/indicators/{indicatorId or indicatorSummary}

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

GET /v3/indicators/3

JSON Response

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

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

GET /v3/indicators/badguy.com

JSON Response

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

Retrieve Deleted Indicators

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

GET /v3/indicators/deleted

JSON Response

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

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

Note

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

Update Indicators

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

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

{
    {updatedField}: {updatedValue}
}

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

Hint

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

associatedArtifacts
associatedCases
associatedGroups
associatedIndicators
attributes
fileActions
fileOccurrences
securityLabels
tags

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

Example PUT Request

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

Disable the DNS feature for the Indicator
Dissociate the Bad Guy Adversary Group from the Indicator
Update the Indicator’s Confidence Rating
Replace any existing Security Labels applied to the Indicator with the TLP: RED Security Label
Apply a new Russia Tag to the Indicator without replacing any existing Tags applied to the Indicator.

Hint

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

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

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

JSON Response

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

Delete Indicators

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

DELETE /v3/indicators/{indicatorId or indicatorSummary}

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

DELETE /v3/indicators/3

JSON Response

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

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

DELETE /v3/indicators/badguy.com

JSON Response

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

Associations

Create Associations

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

Retrieve Custom Associations

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

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

GET /v3/indicators/30?fields=customAssociations

JSON Response

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

Indicator-to-Indicator Associations

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

Create an Indicator-to-Indicator Association
Create a File Action (for File Indicators)

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

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

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

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

Association Name	Primary Indicator Type	Non-Primary Indicator Type(s)
Address to User Agent	Address	User Agent
ASN to Address	ASN	Address
ASN to CIDR	ASN	CIDR
CIDR to Address	CIDR	Address
DNS PTR Record	Address	Host
Domain Registrant Email	Host	EmailAddress
Domain Registrant Email	Host	EmailAddress
File Download	URL	File
URL Host	URL	Host, Address

Note

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

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

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

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

JSON Response

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

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

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

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

JSON Response

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

Note

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

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

File Actions

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

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

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

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

File Action Name	Associable Indicator Type(s)
File Archive	File
File DNS Query	Host
File Drop	File
File Traffic	Address, Host, URL
File Mutex	Mutex
File Registry Key	Registry Key
File User Agent	User Agent

Note

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

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

Field	Description	Type	Required for Creation?
indicator	The Indicator being associated to the File Indicator via the specified File Action	Indicator Object	TRUE
relationship	The name of the File Action	String	TRUE

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

Create a new File Indicator based on an MD5 file hash
Create a new Address Indicator and associate it to the newly created File Indicator using the File Traffic File Action
Associate the existing File Indicator whose ID is 12 to the newly created File Indicator using the File Archive File Action

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

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

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

JSON Response

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

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

File Occurrences

Create a File Occurrence

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

Field	Description	Type	Required for Creation?
date	The date and time of the File Occurrence	Date	FALSE*
fileName	The name of the file corresponding to the File Occurrence	String	FALSE*
path	The run path for the file corresponding to the File Occurrence	String	FALSE*

Note

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

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

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

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

JSON Response

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

Manage an Indicator’s File Actions

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

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

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

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

Hint

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

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

Merge File Hashes

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

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

Attention

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

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

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

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

JSON Response

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

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

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

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

JSON Response

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

False Positives and Observations

As of ThreatConnect 7.8, API users can report false positives and observations for an Indicator that belongs to their Organization, Communities, and Sources.

Requirements

To report false positives and observations for Indicators via the ThreatConnect v3 API, the Include in Observations and False Positives option must be selected for your API user account.
To report false positives and observations for Indicators in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer. Alternatively, if the v3ApiReadOnlyReports system setting is turned on for your ThreatConnect instance, your API user account can have any Organization role.
To report false positives and observations for Indicators in a Community or Source, your API user account must have a Community role of Contributor, Editor, or Director for the Community or Source. Alternatively, if the v3ApiReadOnlyReports system setting is turned on for your ThreatConnect instance, your API user account can have any Community role except Banned for the Community or Source.

Report an Indicator as False Positive

When creating a new Indicator or updating an existing one, you can report the Indicator as false positive. The following request demonstrates how to report an existing Indicator as false positive. Because false positive data are not included in the API response by default, the fields query parameter is used and assigned a value of falsePositives to include those data in the response.

PUT /v3/indicators/75?fields=falsePositives
{
    "falsePositiveFlag": true
}

JSON Response

{
    "data": {
        "id": 75,
        "dateAdded": "2024-11-07T12:55:33Z",
        "ownerId": 2,
        "ownerName": "Demo Source",
        "webLink": "https://app.threatconnect.com/#/details/indicators/75",
        "type": "Host",
        "lastModified": "2024-12-09T19:34:21Z",
        "summary": "nefarious.com",
        "falsePositives": 1,
        "falsePositiveReportedByUser": true,
        "privateFlag": false,
        "active": false,
        "activeLocked": false,
        "hostName": "nefarious.com",
        "dnsActive": false,
        "whoisActive": false,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=nefarious.com&owner=Demo+Source"
    },
    "message": "Updated",
    "status": "Success"
}

JSON Response (Read Only)

{
    "data": {
        "type": "Host",
        "threatAssessRating": 3.59,
        "threatAssessConfidence": 20.65,
        "threatAssessScore": 273,
        "threatAssessScoreObserved": 0,
        "threatAssessScoreFalsePositive": 0,
        "summary": "nefarious.com",
        "observations": 0,
        "falsePositives": 1,
        "lastFalsePositive": "2024-12-09T00:00:00Z",
        "falsePositiveReportedByUser": true,
        "trackedUsers": {
            "John Smith": {
                "observations": 0,
                "falsePositives": 1,
                "lastFalsePositive": "2024-12-09T00:00:00Z"
            },
            "Patrick Jones": {
                "observations": 0,
                "falsePositives": 0
            }
        }
    },
    "message": "Updated",
    "status": "Success"
}

Report Observations for an Indicator

When creating a new Indicator or updating an existing one, you can report observations for the Indicator. The following request demonstrates how to report observations for an existing Indicator. Because observation data are not included in the API response by default, the fields query parameter is used and assigned a value of observations to include those data in the response.

PUT /v3/indicators/75?fields=observations
{
    "observations": 1
}

JSON Response

{
    "data": {
        "id": 75,
        "dateAdded": "2024-11-07T12:55:33Z",
        "ownerId": 2,
        "ownerName": "Demo Source",
        "webLink": "https://app.threatconnect.com/#/details/indicators/75",
        "type": "Host",
        "lastModified": "2024-12-09T19:34:21Z",
        "summary": "nefarious.com",
        "observations": 1,
        "lastObserved": "2024-12-09T00:00:00Z",
        "privateFlag": false,
        "active": false,
        "activeLocked": false,
        "hostName": "nefarious.com",
        "dnsActive": false,
        "whoisActive": false,
        "legacyLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=nefarious.com&owner=Demo+Source"
    },
    "message": "Updated",
    "status": "Success"
}

JSON Response (Read Only)

{
    "data": {
        "type": "Host",
        "threatAssessRating": 3.59,
        "threatAssessConfidence": 20.65,
        "threatAssessScore": 273,
        "threatAssessScoreObserved": 0,
        "threatAssessScoreFalsePositive": 0,
        "summary": "nefarious.com",
        "observations": 1,
        "lastObserved": "2024-12-09T20:13:50Z",
        "falsePositives": 0,
        "falsePositiveReportedByUser": false,
        "trackedUsers": {
            "John Smith": {
                "observations": 1,
                "lastObserved": "2024-12-09T20:13:50Z",
                "falsePositives": 0
            },
            "Patrick Jones": {
                "observations": 0,
                "falsePositives": 0
            }
        }
    },
    "message": "Updated",
    "status": "Success"
}

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