Getting Started with ThreatExchange

Create a Facebook App and Apply to ThreatExchange

Please follow the steps at Applying for ThreatExchange.

Choices: UI and API

ThreatExchange has a graphical user interface you can use to quickly and interactively do things like upload descriptors, run queries, create and assign tags, view/edit privacy groups, and so on.

There is also a powerful HTTP API which is more suited for non-interactive purposes.

For learning about ThreatExchange it's easiest to start with the UI, but making use of the API in your company's threat-processing system will yield greater opportunities for automation. This document helps you get started with the UI as well as the API.

Finding the UI

Visit https://developers.facebook.com/apps and select your app:


Then find the ThreatExchange product within the navbar on the left:

Searching Data Using the UI

A variety of search options is supported -- here we'll focus on the power-search option. (As of January 2020 multi-page search results are still in development.)


Here we search for all malicious URLs uploaded in the last week:

Publishing Data Using the UI

Please see the Submitting Data page for several examples.

Authenticate via an Access Token

The ThreatExchange APIs perform authentication via access tokens. After Facebook notifies you that your App can access ThreatExchange, use the access token tool to get an App Token. Please note, app tokens give access to sensitive details to your app and should be treated like a password.

With the access token, test your access to ThreatExchange by retrieving the list of members in the exchange:

https://graph.facebook.com/threat_exchange_members?access_token=<access_token>

If this request does not return an error, you are now ready to begin exploring the ThreatExchange API!

Searching Data Using the API

With your newly activated access token, perform a search for malicious URLs added in the last week:

https://graph.facebook.com/threat_descriptors?type=URI&amp;status=MALICIOUS&amp;since=a week ago&amp;access_token=<access_token>

Please note that not all fields are returned by default. Consult the reference documentation and specify the fields you are looking to read by appending the fields parameter. See the Graph API guide for more details.

Publishing Data Using the API

Test publish a domain, my-test-example.com, ensuring only you are able to see the data:

https://graph.facebook.com/threat_descriptors

POST DATA

type=DOMAIN
indicator=my-test-example.com
privacy_type=HAS_WHITELIST
status=UNKNOWN
description=Test data publishing
share_level=RED
privacy_members=<your_app_id>
access_token=555|1235

The return value will be a JSON map with a success or failure code and, if the call is successful, the unique ThreatExchange ID for the descriptor you published!

Publish a descriptor for your own domain, my-company-domain.com, and share it with Facebook's app ID, 820763734618599:

https://graph.facebook.com/threat_descriptors

POST DATA

type=DOMAIN
indicator=my-company-domain.com
privacy_type=HAS_WHITELIST
status=NON_MALICIOUS
description=The domain owned by <your_app_id>
share_level=WHITE
privacy_members=820763734618599
access_token=555|1235

More API Examples

Search for all compromised credentials found on the Internet within the last day:

https://graph.facebook.com/v2.8/threat_indicators?type=COMPROMISED_CREDENTIAL&amp;since=yesterday&amp;access_token=555|1235

Find the unique ThreatExchange ID for a specific indicator, such as facebook.com:

https://graph.facebook.com/v2.8/threat_indicators?text=facebook.com&amp;access_token=555|1235

Explore related indicators for a specific indicator with ThreatExchange ID 898557073557972:

https://graph.facebook.com/898557073557972/descriptors?access_token=555|1235

Explore all of the descriptors for a specific indicator with ThreatExchange ID 898557073557972:

https://graph.facebook.com/898557073557972/descriptors?access_token=555|1235

See more examples on our Github, or on the endpoint pages for threat indicators, threat descriptors, malware analyses, or malware families.