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.

• See below for information on column/attribute names.
• Alternatively, you can simply save any descriptor-query result to CSV and use that as a template (and likewise for JSON).

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.

CSV examples

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
        

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

{
  "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": []
}
        

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