Best Practices for Using ThreatExchange

As with any API, there are some ways of using ThreatExchange that will help improve throughput and usage.

Tagging Your Data

By tagging your data, it makes it easier for yourself and others to find the indicators they care most about. For example, by tagging descriptors with evil, this will allow others to filter descriptors searches by data with that tag. Another option is that you can then search the threat_tags endpoint by that tag and see all the tagged objects visible to you. The tagging endpoint also supports partial matches on tags, so a query for evil will surface any tags visible to you which are like evil*.

Be Descriptive with your Tag

ThreatTags do not contain a metadata field describing what they are. If you create the tag foo, no one will know what that tag means or why the data was tagged. Be descriptive instead, tags like campaign_zeusbotnet or malicious_ssl_cert are great examples.

Consider the Privacy Rules

ThreatTags are visible based on the PrivacyType of the tagged data. For example, if the tag public_tag is on ANY descriptor which is publically visible (privacy type of VISIBLE), then the tag is visible to all members. Conversely, if the tag nonpublic_tag is ONLY on tagged objects which shared to specific members (privacy types HAS_WHITELIST or HAS_PRIVACY_GROUP), then the tag will only be visible to those members. Tag your data accordingly. Please review the PrivacyType documentation for more information on privacy in ThreatExchange.

For more uses cases with ThreatTags, see the ThreatTag documentation.

Use tag-driven queries for bulk download

When you first onboard or first start downloading data for a particular problem domain, we recommend [this query structure](https://github.com/facebook/ThreatExchange/blob/master/hashing/te-tag-query-java/README.md) (reference design in Java) for the "get all the data" use-case.

Use Batch Requests For Improved Throughput

Batch requests allow you to make multiple requests to the Graph API using a single HTTP call. For more information on Graph API Batch Requests please review the following:

• Making multiple API requests
• Batch requests documentation

You can also query for multiple objects by ID using the following syntax.

https://graph.facebook.com/v2.8/?ids=[id1,id2]&amp;access_token=<access_token>

If you need to query for a specific field,

https://graph.facebook.com/v2.8/?ids=[id1,id2]&amp;fields=field1,field2&amp;access_token=<access_token>

Including nested fields and objects in result data

It can sometimes be more efficient to include various nested fields or related objects in your search results. The following syntax shows how, for the facebook.com indicator object, to pull all of its descriptors without issuing additional API calls:

https://graph.facebook.com/v2.8/788497497903212?fields=descriptors{owner,description,status,share_level},indicator,type&amp;access_token=<access_token>

RESULT:

{
   "descriptors": {
      "data": [
         {
            "owner": {
               "id": "820763734618599",
               "name": "Facebook Administrator"
            },
            "description": "Facebook",
            "status": "NON_MALICIOUS",
            "share_level": "GREEN",
            "id": "834469179976904"
         },
         {
            "owner": {
               "id": "588498724619612",
               "name": "Facebook CERT ThreatExchange"
            },
            "description": "Non malicious",
            "status": "NON_MALICIOUS",
            "share_level": "GREEN",
            "id": "1202389109786630"
         }
      ],
      "paging": {
         "cursors": {
            "before": "ODM0NDY5MTc5OTc2OTA0",
            "after": "MTIwMjM4OTEwOTc4NjYzMAZDZD"
         }
      }
   },
   "indicator": "facebook.com",
   "type": "DOMAIN",
   "id": "788497497903212"
}