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
|
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
|
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 theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting theassociatedGroups
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 theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting theassociatedIndicators
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 theassociatedIndicators
field. To create an association to an Indicator that exists in a Community or Source using the Indicator’s summary and type, include theownerId
orownerName
field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting theassociatedIndicators
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 theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting theindicator
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 theindicator
field. To create an association to an Indicator that exists in a Community or Source using the Indicator’s summary and type, include theownerId
orownerName
field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting theindicator
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"
}