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.
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.
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.
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.
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.
Yes, a personal Facebook account is required to create a developer app, which you will use to connect to ThreatExchange.
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.
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.
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.
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.
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:
- Visit the Apps Dashboard.
- After selecting the correct app, on the left side bar, select Settings. You'll see your App secret obfuscated in the top-right corner.
- Click Show and after entering your Facebook password, click Reset to change your App secrect.
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.
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.
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.
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.
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.
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.
Yes, to make data shared on ThreatExchange usable and actionable in existing workflows, several third parties have built direct integrations with the ThreatExchange platform:
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.
The Examples Documentation includes sample queries in Python, Java, and PHP, as well as some using cURL.
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.
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
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.
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.
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.
If you observe errors in your results or experience bugs in the ThreatExchange platform, please post in the ThreatExchange Facebook group for support.
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.
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