Submitting 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.

Creating

Using the Create button you can upload a new descriptor, with tooltips to provide context. Here's an example of submitting a malicious domain using the UI:

Note : 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.

Creating 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 we'll see immediately below, bulk-upload from CSV or JSON files solves this problem in a very 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, simply proceed as above by selecting the Create button -- then select the .

Since template mode is selected, once you hit OK you'll be taken to a commit screen (the same as for upload from file) where you can make any revisions, if any, then commit.

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

Uploading from CSV/JSON

Both CSV and JSON formats are supported.

Start by selecting the Bulk Upload button:

Select your file:

If you wish to revise your data before committing you can do so:

If there are errors detected before committing you'll be notified, and you can revise them. (Note that not all possible errors are surfaced here.)

Within the revision dialog you can fix the errors and hit OK to continue:

Once you hit the Confirm Upload button, your new descriptors are saved and their IDs are entered into the search bar. At that point, you can further revise them if you like.

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

حدث خطأ ما
لدينا مشكلة في تشغيل هذا الفيديو.

Uploading using the API

You may submit data using the ThreatExchange API via an HTTP POST to the following URL:

  • https://graph.facebook.com/v4.0/threat_descriptors

NOTE: 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 will create a threat descriptor and the associated threat indicator behind the scenes.

Example submission of a malicious domain using the API:

https://graph.facebook.com/v4.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

The key for authenticating to the API, in the format

your-app-id|your-app-secret

Please visit the

Access Token Tool

to find values for your app(s).

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

A short summary of the indicator and threat.

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

The indicator data being submitted.

type
URI
td_indicator_type
URI

The kind of indicator being described. See

IndicatorType

for the list of allowed values.

privacy_type
HAS_PRIVACY_GROUP
td_visibility
HAS_PRIVACY_GROUP

The kind 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 if you like. If visibility is HAS_WHITELIST, we will proceed as if your td_privacy_members column were named td_whitelist_apps; if visibility is HAS_PRIVACY_GROUP, we will proceed as if your td_privacy_members column were named td_privacy_groups.



See CSV examples and JSON examples 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: a comma-separated list of tags you want to publish. UI: a semicolon-separated list of tags you want to publish. This will replace any existing tags.
Tags are not strictly required but do note that 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
        

JSON examples

When you download as JSON, we put whitelist app, privacy groups, and tags in nested ID/name pairs:

{
  "id": "2699570156799349",
  "td_description": "Testing bulk upload",
  "td_status": "NON_MALICIOUS",
  "td_confidence": 100,
  "td_severity": "UNKNOWN",
  "td_share_level": "AMBER",
  "td_creation_time": 1575824153,
  "td_update_time": 1575824154,
  "td_expire_time": 0,
  "td_indicator_type": "HASH_MD5",
  "td_raw_indicator": "e8b19da37825a3056e84c522f05ed0c0",
  "td_owner": {
    "id": "1064060413755420",
    "name": "Media Hash Sharing Test"
  },
  "td_subjective_tags": [
    {
      "id": "2055943881194599",
      "td_name": "pwny"
    },
    {
      "id": "1977957082312815",
      "td_name": "testing"
    }
  ],
  "td_visibility": "HAS_WHITELIST",
  "td_whitelist_apps": [
    {
      "id": "1064060413755420",
      "name": "Media Hash Sharing Test"
    },
    {
      "id": "494491891138576",
      "name": "Media Hash Sharing RF Test"
    }
  ],
  "td_privacy_groups": []
}
        

When you upload from JSON, if you prefer, you can write whitelist apps and privacy groups as simply arrays of IDs, and tags as arrays of text:

{
  "td_description": "This is an example descriptor",
  "td_status": "UNKNOWN",
  "td_confidence": 0,
  "td_severity": "SEVERE",
  "td_share_level": "AMBER",
  "td_creation_time": 1573183500,
  "td_update_time": 1573183501,
  "td_expire_time": 0,
  "td_indicator_type": "URI",
  "td_raw_indicator": "https://evilevillabs.com/evil.php",
  "td_subjective_tags": ["testing", "pwny"],
  "td_visibility": "HAS_WHITELIST",
  "td_whitelist_apps": ["1064060413755420", "494491891138576"]
}
        

See also the Submitting Connections page for how to do related descriptors at bulk-upload.