ThreatExchange

Submit New Data

Visit the descriptors-tab page to see more things you can do with threat descriptors within the ThreatExchange UI, including searching, bulk download, and more.

Create

Click Create to upload a new descriptor with tooltips to provide context. See the example below on how to submit a malicious domain using the UI:

If you set a descriptor's privacy to has-whitelist and include no whitelist apps, the owner's app is automatically included. This is a "visible to self" or "storage mode" option.

Create with Templates

Using the Create button is fine for sharing a single threat descriptor, but what if you have a hundred or a thousand? As the example shows below, bulk-upload from a CSV file solves this problem in a general way.

But there's a common case that's simpler—when you don't really need a CSV file. ThreatExchange users often find they're submitting a number of threat descriptors which have all the same metadata, except for the indicator value. The create-with-templates feature fits the bill.

To use templates, click Create, then select the .


Because template mode is selected, once you click OK, you're redirected to a commit screen (the same as for upload from file) where you can make any revisions, if any, then commit.

The same process works for the Copy button as for the Create button. You can easily make "more of the same" as your organization has more data to share on a given topic.

Upload from CSV

To upload from CSV:

  1. Click Bulk Uploads.

  2. Select your file:

  3. Revise your data before committing:

  4. If there are errors detected before committing, you'll be notified, and you can revise them.

    5. Not all possible errors are surfaced here.

  5. Within the revision dialog, you can fix the errors and click OK to continue:

  6. Once you click Confirm Upload, your new descriptors are saved and their IDs are entered into the search bar. At that point, you can further revise them, as necesary.

    7. The following screen recording shows the revise-before-upload feature in more detail:

    Something Went Wrong
    We're having trouble playing this video.
    Learn more

Upload Using the API

You can submit data using the ThreatExchange API via an HTTP POST to https://graph.facebook.com/v22.0/threat_descriptors.

The call to /threat_indicators is deprecated as of v2.4 of the ThreatExchange API. If you attempt to access this endpoint in v2.4+, it creates a threat descriptor and the associated threat indicator behind the scenes.

Example: Submission of a malicious domain using the API

https://graph.facebook.com/v22.0/threat_descriptors?access_token=555|aSdF123GhK

POST DATA:
indicator=evil-domain.biz
&type=DOMAIN
&tags=testingtags
&status=MALICIOUS
&description=This%20domain%20was%20hosting%20malware
&privacy_type=VISIBLE

Data returned:

{
"id": "853037291373757",
"success": true
}

Field Names for Upload

Bold parameters are required.

API Name and ExampleUI CSV Name and ExampleDescription
access_token
555|aSdF123GhK		Not used for the UI

Key for authenticating to the API, in this format:

your-app-id|your-app-secret

See the

Access Token Tool

to find values for your apps.

description
This%20domain%20was%20hosting%20malware		td_description
This domain was hosting malware

Short summary of the indicator and threat.

indicator
evil-domain.biz		td_raw_indicator
evil-domain.biz

Indicator data being submitted.

type
URI		td_indicator_type
URI

Type of indicator being described. See

IndicatorType

for the list of allowed values.

privacy_type
HAS_PRIVACY_GROUP		td_visibility
HAS_PRIVACY_GROUP

Type of privacy for the indicator. See

PrivacyType

for the list of allowed values.

privacy_members
1064060413755420,494491891138576		td_whitelist_apps
1064060413755420,494491891138576

td_privacy_groups
438835087026293,468692780520730

Or, for compatibility, you can use a column name of

td_privacy_members

for upload, as necessary. If visibility is

HAS_WHITELIST

, proceed as if your

td_privacy_members

column were named

td_whitelist_apps

. If visibility is

HAS_PRIVACY_GROUP

, proceed as if your

td_privacy_members

column were named

td_privacy_groups

.



See CSV examples example below.

A list of

ThreatExchangeMembers

allowed to see the indicator, and only applies when

privacy_type

is set to

HAS_WHITELIST

or

HAS_PRIVACY_GROUP

. Delimiters are comma for the API and semicolon for the UI.

share_level
AMBER		td_share_level
AMBER

A designation of how the indicator may be shared based on the

US-CERT's Traffic Light Protocol

. See

ShareLevelType

for the list of allowed values. Note: GREEN/WHITE requires VISIBLE, and AMBER/RED requires HAS_WHITELIST or HAS_PRIVACY_GROUP.

status
MALICIOUS		td_status
MALICIOUS

Indicates if the indicator is labeled as malicious. See

StatusType

for the list of allowed values.

tags
testing,pwny		td_subjective_tags
testing;pwny

API: Comma-separated list of tags you want to publish. UI: Semicolon-separated list of tags you want to publish. This replaces any existing tags.
Tags are not strictly required, but they are essential for your collaborators to discover data you contribute.

add_tags
pwny,testing		Not used for the UI

To add tags to an object without overwriting existing tags.

remove_tags
pwny,testing		Not used for the UI

Remove tags associated with an object.

confidence
100		td_confidence
100

A score for how likely the indicator's

status

is accurate, ranging from 0 to 100.

expired_ontd_expire_time
2019-11-07T22:25:00-05:00

Time the indicator is no longer considered a threat, in ISO 8601 date format.

first_activetd_first_active
2019-11-07T22:25:00-05:00

Time when the opinion first became valid.

last_activetd_last_active
2019-11-07T22:25:00-05:00

Time when the opinion stopped being valid.

review_status
PENDING		td_review_status
PENDING

Describes how the indicator was vetted. See

ReviewStatusType

for the list of allowed values.

severity
SEVERE		td_severity
SEVERE

A rating of how severe the indicator is when found in an incident. See

SeverityType

for the list of allowed values.

N/A

td_related_ids_for_upload

For submitting relations in bulk. Please see the

Submitting Connections page

for more information.

N/A

td_related_triples_for_upload

For submitting relations in bulk. Please see the

Submitting Connections page

for more information.

CSV Examples

When you download as CSV, we put whitelist apps and privacy groups in the format id1:name1;id2:name2. Tags are always text-only, delimited by semicolons:

id                 2494923897281868
td_description     This is an example descriptor
td_status          UNKNOWN
td_confidence      0
td_severity        SEVERE
td_share_level     AMBER
td_indicator_type  URI
td_raw_indicator   https://evilevillabs.com/evil.php
td_visibility      HAS_WHITELIST
td_creation_time   2019-11-07T22:25:00-05:00
td_update_time     2019-11-07T22:25:01-05:00
td_expire_time
td_owner_id        494491891138576
td_owner_name      Media Hash Sharing RF Test
td_subjective_tags testing;pwny
td_whitelist_apps  1064060413755420:Media Hash Sharing Test;494491891138576:Media Hash Sharing RF Test

When upload from CSV, you may specify whitelist apps and privacy groups in the format id1;id2 if you prefer:

td_description     This is an example descriptor
td_status          UNKNOWN
td_confidence      0
td_severity        SEVERE
td_share_level     AMBER
td_indicator_type  URI
td_raw_indicator   https://evilevillabs.com/evil.php
td_visibility      HAS_WHITELIST
td_creation_time   2019-11-07T22:25:00-05:00
td_update_time     2019-11-07T22:25:01-05:00
td_expire_time
td_owner_id        494491891138576
td_owner_name      Media Hash Sharing RF Test
td_subjective_tags testing;pwny
td_whitelist_apps  1064060413755420;494491891138576