As with any API, there are some ways of using ThreatExchange that will help improve throughput and usage.
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*
.
Threat-tags (also known as "subjective tags") contain metadata fields describing what they are. If you create the tag foo
, others can inspect the metadata to see what means or why the data was tagged. But it's helpful to be more descriptive instead -- tags like campaign_zeusbotnet
or malicious_ssl_cert
are great examples.
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.
When you first onboard or first start downloading data for a particular problem domain, we recommend this reference design in Java for the "get all the data" use-case.
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:
You can also query for multiple objects by ID using the following syntax.
https://graph.facebook.com/v2.8/?ids=[id1,id2]&access_token=<access_token>
If you need to query for a specific field,
https://graph.facebook.com/v2.8/?ids=[id1,id2]&fields=field1,field2&access_token=<access_token>
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&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" }