ThreatExchange FAQ

This FAQ covers many of the more common questions asked by prospective and existing ThreatExchange Members.

Basics

ThreatExchange is an API platform for security professionals to share threat intelligence more easily, learn from each other's discoveries, and make their own systems safer.

Permalink

ThreatExchange provides a set of APIs for pulling data into your existing clients and workflows. The platform supports easy-to-use privacy controls so you can specify who sees the information you publish and how it can be used.

Permalink

The ThreatExchange community includes companies from a variety of industries. You can share data with the entire exchange about specific attacks or campaigns; for example, phishing attempts, malware, or bad domains/IPs. Or, you can be more selective and only share information with specific members about threats that might impact them. You decide what to share and with whom. Most members start off by observing what's being shared by the community and then become active contributors in the exchange.

Permalink

ThreatExchange is currently in beta and new members must apply to join. Because we are focused on growing the platform to support high-value and applicable data, we look for credible companies that are able to contribute high-confidence information. Engineers and analysts with a technical background are best positioned to use the APIs and engage with the community in a meaningful way.

Permalink

How do I sign up?

Visit http://threatexchange.fb.com and follow the steps there. Learn more about how to create a Facebook developer app.

Permalink

Yes, a personal Facebook account is required to create a developer app, which you will use to connect to ThreatExchange.

Permalink

No, we do not support trial license keys or temporary access. All members of the exchange are required to accept the ThreatExchange Terms of Service agreement.

Permalink

Manage Permissions with the Developer App

ThreatExchange resides inside Facebook's Graph APIs used by third party developers to interact with our platform. ThreatExchange members interact with our platform in the same way. Existing member App ID's are viewable via the /threat_exchange_members edge. Community members will use your company's ThreatExchange App ID to share information with you and/or to add you to private groups.

Permalink

The app is owned by anyone with an administrative role for the application. We recommend adding multiple administrators to your app and including their removal as part of your team's exit process if they leave the company.

Permalink

Find and select your app within the Apps Dashboard. Locate the “Roles” tab on the left hand side. Here you can assign Administrators who will have complete control of the app as well as Developers, which includes all other ThreatExchange users within your company.

Permalink

Every call to ThreatExchange requires you to submit your App ID and your App secret. Your App ID is public, but should never share your App secret with anyone. For example, all ThreatExchange members can view other members' App IDs in the system via the /threat_exchange_members edge. App secrets, on the other hand, work like a password to authenticate you. Keep it private, rotate it regularly, and always store it encrypted.

To change your app secret:

  1. Visit the Apps Dashboard.
  2. After selecting the correct app, on the left side bar, select Settings. You'll see your App secret obfuscated in the top-right corner.
  3. Click Show and after entering your Facebook password, click Reset to change your App secrect.

Permalink

Privacy

You control the visibility of everything you share through the ThreatExchange API. The platform currently supports three levels of visibility: all members, ThreatPrivacyGroup, or allowlist of specific members. Learn more privacy controls.

Permalink

Privacy groups have convenient options to cover a wide variety of use cases. When creating a group, you have control over whether other members can see who’s in the group. You can also decide if other members can use your groups to share their own information; this is ideal when you need control over what data is shared within the group.

Permalink

You control how recipients can reshare any data you contribute through the ThreatExchange API. Resharing definitions used by the ThreatExchange community are derived from those defined in the US-CERT's Traffic Light Protocol.

Learn more about resharing controls.

Permalink

The ThreatExchange terms prohibit the sharing of Sensitive Personal Information, as defined in the terms. Outside of these terms, we encourage members to share information that is necessary to achieve their security goals while also setting the appropriate share level and privacy controls inline with the severity of the threat and the intended audience.

Permalink

When submitting Threat Data to ThreatExchange, we recommend that you review and confirm that you're using the correct share level, as outlined in the US-CERT's Traffic Light Protocol. Select a share level that reflects your desired audience, taking particular care when the Threat Data contains personal data, as defined under EU law.

Permalink

Technical Implementation

Once you've been approved for membership, view the Getting Started documentation to get detailed instructions on setup and initial use of the ThreatExchange API.

Permalink

Yes, to make data shared on ThreatExchange usable and actionable in existing workflows, several third parties have built direct integrations with the ThreatExchange platform:

Bit9 + CarbonBlack

RiskIq's PassiveTotal

Splunk Add-on

Permalink

ThreatExchange is based on the Facebook Graph API and provides easy interaction via RESTful API in JSON format. To speed up your integration process, you can find more tools including Pytx and bulk download scripts, in the ThreatExchange GitHub Repository. Additionally,a ThreatExchange service developed and managed by the CRITS community is available here.

Permalink

The Examples Documentation includes sample queries in Python, Java, and PHP, as well as some using cURL.

Permalink

New members are encouraged to share data that is both high-confidence and likely to benefit a wide audience of companies. Typically, this can be hashes for malware, phishing site URLs, malicious domains, or IP addresses. Some entities also use the exchange for sharing information on bad actors (e.g. email addresses used in phishing scams) or signatures for detecting threats (e.g. Yara or Snort formatted signatures).

In the end, you are free to decide what you think your company or organization is best positioned to share with the community.

Permalink

Tags are freeform, but tags already used by other members make it easier for others to find the data you share. To see commonly used tags, view the tags reference guide

Permalink

To indicate data is no longer valid, set the expired_on field for automatic soft-deletes and the status field to NON_MALICIOUS for handling false positive cases. You can also overwrite existing data.

Permalink

If your server is behind a firewall, you may need to allowlist Facebook server IPs to ensure we can send updates to your callback URLs. View the current list of Facebook Server IP addresses.

Permalink

Troubleshooting

Every member of ThreatExchange has the ability to mark data they publish as malicious or not. If you have questions related to a specific indicator or descriptor, please reach out directly to the member who shared it. You can find contact info for each member organization at the /threat_exchange_members endpoint.

Permalink

If you observe errors in your results or experience bugs in the ThreatExchange platform, please post in the ThreatExchange Facebook group for support.

Permalink

Facebook shares updates and new releases with the community in the ThreatExchange Facebook group. If you find a bug or want to provide feedback, please post in the group so other members can benefit from the discussion.

Permalink

You're welcome to mention your involvement as a member of ThreatExchange with media. As a reminder, discussing the data shared in ThreatExchange must comply with established share level attributes and the TE Terms and Conditions. To request a license to use the ThreatExchange logo on your website or any marketing materials, or to request permission to include ThreatExchange in a press release, please contact us at threatexchange@fb.com

Permalink