ThreatExchange

Changelog

Changes as of August 21, 2023

Malware Analyses Endpoint Removed

The /malware_analyses endpoint has been removed and is no longer available on any versions.

Changes as of May 23, 2023

Malware Analyses Endpoint Deprecated

  • The /malware_analyses endpoint is deprecated. It is not available on v17 or later and will be removed for all versions on August 21, 2023.

Changes as of January 9, 2023

Malware Endpoint Removal

  • Malware endpoints on threatexchange, such as /malware_analyses and /malware_families, as well as assoicated malware objects are being removed, and will soon be unavailable on all versions.
  • These endpoints and objects have not been in use for some time now, and removing them allows us to simplify the API.
  • If you still would like to exchange information about Malware, ThreatDescriptor objects can be used to upload malware hashes and other indicators.

Changes in API Version 10.0 (Feb 23 2021)

Permanent deletion of expired data

  • Beginning 90 days after the launch of Graph API version 10.0, all expired data will be deleted.
  • Data uploaded to ThreatExchange with a non-zero expire_time will be permanently deleted at the expiration time indicated and will no longer be visible.
  • If you wish to delete data that is no longer valid, set the expired_on field to the current time to have the data deleted immediately.
  • In the past, we used a ‘soft’ delete approach where we labeled expired content as expired. We no longer support soft deletes. Expired content will now be permanently deleted.
  • Additionally, all non-Facebook ThreatDescriptors will be permanently deleted once they reach the expiration date set by the creator.
  • If your application currently has expired ThreatDescriptors that you don’t want deleted, you must extend the expiration date or set it to ‘0’ to ensure that the data never expires.

Changes as of June 2, 2020

New tooling for a new generation

  • Our te-tag-query reference design now has Python and Ruby reference implementations in addition to the existing Java version. (In response to feedback we've also split out curl-only documentation for the tag-query recipe.)
  • The common context to all these is that for the last couple years ThreatExchange has moved beyond malware/phishing into cross-company integrity-signal sharing. This newer tooling largely overlaps the old (such as pytx), but with an added focus on
    • more interactive tooling for a broader, more diverse userbase;
    • a strong threat-descriptor focus (vs malware analyses);
    • enhanced support for cross-company feedback mechanisms.
  • While the Java version now has a little catch-up to do, the Python and Ruby reference designs encapsulate the same kinds of bulk-relate, bulk-react, copy-and-modify, and other workflows as already described for the UI in our May 28 update.
  • We find that for folks in some PM/DS/policy roles, the UI is the main interface; for engineers, the UI is a helpful tool but truly scalable processing implementations require the API -- as well as high-level-language support. Today's Python/Ruby releases are milestones for the latter.
  • These flows have been built due to demand from a cross-company userbase which is more engaged and feedback-focused than ever. Please keep the feedback coming at threatexchange@fb.com, and/or on Slack channels you may have open with us.

Changes as of May 28, 2020

This round of updates is all about bulk!

  • The new time-saving create-with-templates feature allows you to submit a batch of descriptors, identical in all but the hash/indicator values, without needing to import from CSV.
  • You can now do bulk relations and bulk reactions.
  • The bulk uploader used to be balky/laggy for uploads of more than a few hundred descriptors -- it's now performant and interactive for file sizes of up to 8,000 descriptors.
  • Similarly, search results now use a lighter-weight rendering (fewer click-to-copy, fewer colors, etc) for result-sizes over a thousand descriptors. (You can configure the simplified-render threshold in the Customization tab.) This helps you more comfortably navigate larger datasets.
  • You can now power-search for descriptors having an "and" of several tags, not just an "or" as before.
  • While true previous-page/next-page support is still in development, there is now a search-older button allowing you to traverse larger search-result sets.

Changes as of April 9th, 2020

In response to more great feedback on the ThreatExchange UI, we're proud to announce the following updates:

  • You can now submit connections in the UI, as well as the API. These help you trace connections between things like domains, URLs, and so on.
  • You can now broaden your searches by fanning out to more descriptors on the same objective data, or more descriptors that have connections to them.
  • We now have support for saved searches -- you can bookmark your searches, or share them with collaborators.

Changes as of January 8th, 2020

In response to lots of great feedback on the ThreatExchange UI, we're proud to announce the following updates:

  • Power-search: you can now do complex queries involving status, indicator type, owner-apps, tags, text, and more. (Next-page support is still under development.)
  • Bulk upload from CSV or JSON files.
  • Bulk edit: bulk updates for various metadata including status, severity, tags, and more.
  • Duplicate: add your own opinions to IOCs submitted to other companies; keystroke-saving for creating more of your own.
  • Click-to-sort on table-column headers for descriptors, tags, privacy groups, and TE members.
  • UI support for the source_uri threat-descriptor field.
  • Bug fix with review_status field not saved to downloaded CSV/JSON.
  • Tags, privacy groups, and apps on an allow list can now be comma-separated as well as semicolon-separated in CSV files.
  • More detailed documentation on threat-descriptor attributes.

Thanks for the great feedback, and please keep hitting the bugnub at the upper-right-hand corner of the UI and let us know how we can improve ThreatExchange!

Changes as of October 9th, 2019

  • We are proud to release a beta user interface at developers.facebook.com/apps: please see the UI docs for more information. Please contact us at threatexchange@fb.com with any and all feedback.
  • Thanks for your continued patience as we revamp our app-approval process. Stay tuned for updates coming soon!

Changes as of February 13th, 2017

New Features

  • You can now react to data you consume in ThreatExchange. Descriptors can be marked as 'HELPFUL', 'NOT_HELPFUL', 'OUTDATED', 'SAW_THIS_TOO', and 'WANT MORE INFO' by anyone who can see them.
  • A new edge, /similar_malware, can now be used to identify malware samples we believe are related.
  • We've also rolled out additional Webhooks support for ThreatIndicators and ThreatTags, so your servers can be notified in real-time when new threat intel is available.

Changes

  • Our strict_text search parameter now limits search result to exactly the search term you have submitted. For example, before this change, if you did a search for threat indicators with strict text enabled for 'google.com', you would get a lot of results, including things like “http://google[.]com/fusiontables” and ”http://google.com-136[.]net/DE/1/?subid=1485323323mb29920939890”. The new search will return results for only google.com, i.e. ID 826838047363868. When searching for threat descriptors, you can still use other parameters to limit the search results (e.g. owner or status). If you want to find www.google.com, you have to search for that separately. A strict-text search for google.com will not return www.google.com.

Changes in API Version 2.8 (Oct 5th 2016)

New Features

Deprecations

  • AttackType and ThreatType are being deprecated in favor of ThreatTags. If you publish or read threat data using these fields, you will need to change your code to use ThreatTags instead. Starting December 5th 2016 these fields will no longer be accessible on all versions of the Graph API. To ease the transition, during the interim you'll be able to continue the use of these types on previous versions of the Graph API, alongside tags. We are also making the existing threat_type or attack_type data values available through tags. More specifically, if existing or new threat data has value to these types, the object will automatically be tagged with the equivalent string value. By the end of this period, you'll need to fully transition to use tags instead of threat_type or attack_type.

Changes in API Version 2.4

There were a large number of changes made in Platform version 2.4. You may continue to use Platform version 2.3, without those changes, until 8 Dec 2015. On that day support for version 2.3 will be disabled.

The most important change in version 2.4 was was the introduction of the descriptor model. On version 2.3 and below, all data was stored on the indicator. Beginning with version 2.4, we split information into objective and subjective categories. Objective information is data which everybody can see and agree upon. It may change over time, but everybody sees the same data. For example, the WHOIS registration for a domain name is objective. Subjective information represents somebody's opinion on the data. Different people may have different opinions. For example, the status of a domain as being MALICIOUS or NON_MALICIOUS.

Objective information will remain stored on indicators. For the most part, Facebook will be the only party updating objective information. Subjective information is now stored on a new structure called a descriptor. We have added API calls to create, edit, and search for descriptors. Each AppID may have one descriptor per indicator. Each descriptor has an edge connecting it to a threat indicator. Each indicator has edges to one or more descriptors.

We currently do not support connections between descriptors. Connections between indicators will remain the only way to associate threat information for the time being.