Skip to main content

ThreatExchange v2

Supported versions

Supported Cortex XSOAR versions: 5.5.0 and later.

Receive threat intelligence about applications, IP addresses, URLs, and hashes. A service by Facebook This integration was integrated and tested with API version v3.2 of ThreatExchange

Authentication#

The ThreatExchange APIs perform authentication via access tokens consisting of App ID and App Secret.

In order to get your App ID and App Secret, Facebook must first confirm your App's access to ThreatExchange.

After Facebook notifies you that your App can access ThreatExchange, go to the App's Settings - Basic - and copy your App ID and App Secret.

When configuring ThreatExchange v2 on Cortex XSOAR, set the copied values in the App ID and App Secret fields.

For more information see the ThreatExchange API Overview

For Cortex XSOAR versions 6.0 and below, the App Secret should be set in the password field.

Configure ThreatExchange v2 on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for ThreatExchange v2.

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    App IDTrue
    App SecretTrue
    Source ReliabilityReliability of the source providing the intelligence dataTrue
    Use system proxy settingsFalse
    Trust any certificate (not secure)False
    Malicious ThresholdIf the percentage of 'Malicious' reported statuses is above this threshold the indicator will be defined as malicious, otherwise suspicious.False
    Suspicious ThresholdIf the number of 'Suspicious' reported statuses is above this threshold the indicator will be defined as suspicious.False
    Non Malicious ThresholdIf the percentage of 'Non Malicious' reported statuses is above this threshold the indicator will be defined as good, otherwise unknown.False
  4. Click Test to validate the URLs, token, and connection.

Changes compared to previous version#

  1. Dbot score calculation is different. See DBot Score / Reputation scores for details.

  2. The context output of the threatexchange-query command appears under ThreatExchange - Query instead of under queryResult.

  3. The output of reputation commands which was executed on an invalid input does not raise an exception, but provides an output that says no information was found for the given input. In addition a description of the error that occurred is added to the Cortex XSOAR server log.

DBot Score / Reputation scores#

The following information describes a DBot Score calculation logic which is new for this version:

If the percentage of 'Malicious' reported statuses is above the Malicious Threshold (50% by default), the indicator will be defined as malicious.

If the percentage of 'Malicious' reported statuses is below the Malicious Threshold, but there exists at least one 'Malicious' status, the indicator will be defined as suspicious.

If there are no 'Malicious' statuses, but the number of 'Suspicious' statuses is above the Suspicious Threshold (1 by default), the indicator will be defined as suspicious.

If there are no 'Malicious' statuses and the number of 'Suspicious' statuses is below the Suspicious Threshold, and the percentage of 'Non Malicious' reported statuses is above the Non Malicious Threshold (50% by default), the indicator will be defined as good.

Otherwise, the indicator will be defined as unknown.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

file#


Checks the file reputation of the given hash.

Base Command#

file

Input#

Argument NameDescriptionRequired
fileHash of the file to query. Supports MD5, SHA1, and SHA256 hashes.Required
limitThe maximum number of results per page. The maximum is 1000. Default is 20.Optional
headersA comma-separated list of headers to display in human-readable format. For example: header1,header2,header3.Optional
sinceThe start timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional
untilThe end timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional

Context Output#

PathTypeDescription
File.MD5StringThe MD5 hash of the file.
File.SHA1StringThe SHA1 hash of the file.
File.SHA256StringThe SHA256 hash of the file.
DBotScore.IndicatorStringThe indicator that was tested.
DBotScore.TypeStringThe indicator type.
DBotScore.VendorStringThe vendor used to calculate the score.
DBotScore.ScoreNumberThe actual score.
File.Malicious.VendorStringFor malicious files, the vendor that made the decision.
File.Malicious.DescriptionStringFor malicious files, the reason that the vendor made the decision.
File.Malicious.ScoreNumberFor malicious files, the score from the vendor.
ThreatExchange.File.share_levelStringA designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.
ThreatExchange.File.privacy_typeStringThe level of privacy applied to the descriptor. Also known as "visibility".
ThreatExchange.File.statusStringIf the indicator is known to be malicious.
ThreatExchange.File.review_statusStringDescribes how the indicator was vetted.
ThreatExchange.File.idStringUnique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.
ThreatExchange.File.descriptionStringA short summary of the indicator and threat.
ThreatExchange.File.added_onDateThe datetime this descriptor was first uploaded. Automatically computed; not directly editable.
ThreatExchange.File.sha1StringThe SHA1 hash of the file.
ThreatExchange.File.sha256StringThe SHA256 hash of the file.
ThreatExchange.File.sample_size_compressedNumberThe size of the compressed sample.
ThreatExchange.File.ssdeepStringThe SSDeep hash of the file.
ThreatExchange.File.sample_typeStringThe MIME type of the sample.
ThreatExchange.File.sample_sizeNumberThe size of the sample.
ThreatExchange.File.sha3_384StringThe SHA3-384 hash of the file.
ThreatExchange.File.victim_countNumberA count of known victims infected and/or spreading the malware.
ThreatExchange.File.passwordStringThe password required to decompress the sample.
ThreatExchange.File.md5StringThe MD5 hash of the file.

Command Example#

!file file=cb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54c

Context Example#

{
"DBotScore": {
"Indicator": "cb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54c",
"Reliability": "C - Fairly reliable",
"Score": 0,
"Type": "file",
"Vendor": "ThreatExchange v2"
},
"File": {
"MD5": "f5c3281ed489772c840a137011c76b58",
"SHA1": "2517620f427f0019e2eee3b36e206567b6e7a74a",
"SHA256": "cb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54c",
"SSDeep": "3:N8RdNcvALtGTmAS3gG9HV6qVJNerWl/DKKIFjnD0SrrVKmTQXQN/:27NFGi79es2TFjnDXrP0i/",
"Size": 142,
"Type": "application/octet-stream"
},
"ThreatExchange": {
"File": {
"added_on": "2014-02-08T10:45:09+0000",
"description": "New Kilim spam template",
"id": "760220740669930",
"md5": "f5c3281ed489772c840a137011c76b58",
"password": "infected",
"privacy_type": "VISIBLE",
"review_status": "REVIEWED_AUTOMATICALLY",
"sample_size": 142,
"sample_size_compressed": 142,
"sample_type": "application/octet-stream",
"sha1": "2517620f427f0019e2eee3b36e206567b6e7a74a",
"sha256": "cb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54c",
"sha3_384": "bc1ed0a4e634aaa784255bc50fa54fe41839c8763e797d083cefb87b87f7c743bc989c2c80bd6d72239fe86c489e802f",
"share_level": "GREEN",
"ssdeep": "3:N8RdNcvALtGTmAS3gG9HV6qVJNerWl/DKKIFjnD0SrrVKmTQXQN/:27NFGi79es2TFjnDXrP0i/",
"status": "UNKNOWN",
"victim_count": 0
}
}
}

Human Readable Output#

ThreatExchange Result for file hash cb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54c#

added_ondescriptionidmd5passwordprivacy_typereview_statussample_sizesample_size_compressedsample_typesha1sha256sha3_384share_levelssdeepstatusvictim_count
2014-02-08T10:45:09+0000New Kilim spam template760220740669930f5c3281ed489772c840a137011c76b58infectedVISIBLEREVIEWED_AUTOMATICALLY142142application/octet-stream2517620f427f0019e2eee3b36e206567b6e7a74acb57e263ab51f8e9b40d6f292bb17512cec0aa701bde14df33dfc06c815be54cbc1ed0a4e634aaa784255bc50fa54fe41839c8763e797d083cefb87b87f7c743bc989c2c80bd6d72239fe86c489e802fGREEN3:N8RdNcvALtGTmAS3gG9HV6qVJNerWl/DKKIFjnD0SrrVKmTQXQN/:27NFGi79es2TFjnDXrP0i/UNKNOWN0

ip#


Checks the reputation of the given IP address.

Base Command#

ip

Input#

Argument NameDescriptionRequired
ipIP address to check.Required
headersA comma-separated list of headers to display in human-readable format. For example: header1,header2,header3.Optional
sinceThe start timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional
untilThe end timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional
limitThe maximum number of results per page. The maximum is 1000.Optional

Context Output#

PathTypeDescription
IP.AddressStringThe IP address found.
IP.Malicious.VendorStringFor malicious IP addresses, the vendor that made the decision.
IP.Malicious.DescriptionStringFor malicious IP addresses, the reason that the vendor made the decision.
DBotScore.IndicatorStringThe indicator that was tested.
DBotScore.TypeStringThe indicator type.
DBotScore.VendorStringThe vendor used to calculate the score.
DBotScore.ScoreNumberThe actual score.
IP.Malicious.ScoreNumberFor malicious IP addresses, the score from the vendor.
ThreatExchange.IP.share_levelStringA designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.
ThreatExchange.IP.confidenceNumberA rating, from 0-100, on how confident the publisher is of the threat indicator's status. 0 is the least confident. 100 is the most confident.
ThreatExchange.IP.indicator.idStringThe ID of the threat indicator described by the descriptor.
ThreatExchange.IP.indicator.indicatorStringThe threat indicator described by the descriptor.
ThreatExchange.IP.indicator.typeStringThe type of the threat indicator described by the descriptor.
ThreatExchange.IP.privacy_typeStringThe level of privacy applied to the descriptor. Also known as "visibility".
ThreatExchange.IP.last_updatedDateDatetime the threat descriptor was last updated. Automatically computed; not directly editable.
ThreatExchange.IP.statusStringIf the indicator is known to be malicious.
ThreatExchange.IP.owner.emailStringThe email of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.IP.owner.idStringThe ID of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.IP.owner.nameStringThe name of the ThreatExchange member that submitted the descriptor. Non-editable
ThreatExchange.IP.raw_indicatorStringA raw, unsanitized string of the indicator being described.
ThreatExchange.IP.review_statusStringDescribes how the indicator was vetted.
ThreatExchange.IP.typeStringThe type of indicator.
ThreatExchange.IP.idStringUnique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.
ThreatExchange.IP.descriptionStringA short summary of the indicator and threat.
ThreatExchange.IP.severityStringSeverity of the threat associated with the indicator.
ThreatExchange.IP.added_onDateThe datetime this descriptor was first uploaded. Automatically computed; not directly editable.

Command Example#

!ip ip=8.8.8.8

Context Example#

{
"DBotScore": {
"Indicator": "8.8.8.8",
"Reliability": "C - Fairly reliable",
"Score": 1,
"Type": "ip",
"Vendor": "ThreatExchange v2"
},
"IP": {
"Address": "8.8.8.8",
"DetectionEngines": 2
},
"ThreatExchange": {
"IP": [
{
"added_on": "2015-07-07T22:36:04+0000",
"confidence": 50,
"description": "Known DNS server",
"id": "881335228606937",
"indicator": {
"id": "501655576609539",
"indicator": "8.8.8.8",
"type": "IP_ADDRESS"
},
"last_updated": "2020-07-24T05:25:48+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "588498724619612",
"name": "Facebook CERT ThreatExchange"
},
"privacy_type": "VISIBLE",
"raw_indicator": "8.8.8.8",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "INFO",
"share_level": "GREEN",
"status": "NON_MALICIOUS",
"type": "IP_ADDRESS"
}
]
}
}

Human Readable Output#

ThreatExchange Result for IP 8.8.8.8#

added_onconfidencedescriptionidindicatorlast_updatedownerprivacy_typeraw_indicatorreview_statusseverityshare_levelstatustype
2015-07-07T22:36:04+000050Known DNS server881335228606937id: 501655576609539
indicator: 8.8.8.8
type: IP_ADDRESS
2020-07-24T05:25:48+0000id: 588498724619612
email: threatexchange@support.facebook.com
name: Facebook CERT ThreatExchange
VISIBLE8.8.8.8REVIEWED_AUTOMATICALLYINFOGREENNON_MALICIOUSIP_ADDRESS

url#


Checks URL Reputation

Base Command#

url

Input#

Argument NameDescriptionRequired
urlURL to be checked.Required
limitThe maximum number of results per page. The maximum is 1000. Default is 20.Optional
headersA comma-separated list of headers to display in human-readable format. For example: header1,header2,header3.Optional
sinceThe start timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional
untilThe end timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional

Context Output#

PathTypeDescription
URL.DataStringThe URL found.
DBotScore.IndicatorStringThe indicator that was tested.
DBotScore.TypeStringThe indicator type.
DBotScore.VendorStringThe vendor used to calculate the score.
DBotScore.ScoreNumberThe actual score.
URL.Malicious.VendorStringFor malicious URLs, the vendor that made the decision.
URL.Malicious.DescriptionStringFor malicious URLs, the reason for the vendor to make the decision.
URL.Malicious.ScoreNumberFor malicious URLs, the score from the vendor.
ThreatExchange.URL.share_levelStringA designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.
ThreatExchange.URL.confidenceNumberA rating, from 0-100, on how confident the publisher is of the threat indicator's status. 0 is the least confident. 100 is the most confident.
ThreatExchange.URL.indicator.idStringThe ID of the threat indicator described by the descriptor.
ThreatExchange.URL.indicator.indicatorStringThe threat indicator described by the descriptor.
ThreatExchange.URL.indicator.typeStringThe type of the threat indicator described by the descriptor.
ThreatExchange.URL.privacy_typeStringThe level of privacy applied to the descriptor. Also known as "visibility".
ThreatExchange.URL.last_updatedDateDatetime the threat descriptor was last updated. Automatically computed; not directly editable.
ThreatExchange.URL.statusStringIf the indicator is known to be malicious.
ThreatExchange.URL.owner.emailStringThe email of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.URL.owner.idStringThe ID of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.URL.owner.nameStringThe name of the ThreatExchange member that submitted the descriptor. Non-editable
ThreatExchange.URL.raw_indicatorStringA raw, unsanitized string of the indicator being described.
ThreatExchange.URL.review_statusStringDescribes how the indicator was vetted.
ThreatExchange.URL.typeStringThe type of indicator.
ThreatExchange.URL.idStringUnique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.
ThreatExchange.URL.descriptionStringA short summary of the indicator and threat.
ThreatExchange.URL.severityStringSeverity of the threat associated with the indicator.
ThreatExchange.URL.added_onDateThe datetime this descriptor was first uploaded. Automatically computed; not directly editable.

Command Example#

!url url=https://www.test.com/

Context Example#

{
"DBotScore": {
"Indicator": "https://www.test.com/",
"Reliability": "C - Fairly reliable",
"Score": 0,
"Type": "url",
"Vendor": "ThreatExchange v2"
},
"ThreatExchange": {
"URL": [
{
"added_on": "2018-07-11T09:50:34+0000",
"confidence": 25,
"id": "1904903709602326",
"indicator": {
"id": "838258172933557",
"indicator": "https://www.test.com/",
"type": "URI"
},
"last_updated": "2020-07-24T19:24:35+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "210126779388350",
"name": "URLQueryThreatData Feed"
},
"privacy_type": "VISIBLE",
"raw_indicator": "https://www.test.com/",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "WARNING",
"share_level": "WHITE",
"status": "UNKNOWN",
"type": "URI"
},
{
"added_on": "2015-07-09T03:04:19+0000",
"confidence": 1,
"id": "835880593160550",
"indicator": {
"id": "838258172933557",
"indicator": "https://www.test.com/",
"type": "URI"
},
"last_updated": "2020-07-24T03:37:14+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "820763734618599",
"name": "Facebook Administrator"
},
"privacy_type": "HAS_PRIVACY_GROUP",
"raw_indicator": "https://www.test.com/",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "INFO",
"share_level": "RED",
"status": "UNKNOWN",
"type": "URI"
}
]
},
"URL": {
"Data": "https://www.test.com/",
"DetectionEngines": 2
}
}

Human Readable Output#

ThreatExchange Result for URL https://www.test.com/#

added_onconfidenceidindicatorlast_updatedownerprivacy_typeraw_indicatorreview_statusseverityshare_levelstatustype
2018-07-11T09:50:34+0000251904903709602326id: 838258172933557
indicator: https://www.test.com/
type: URI
2020-07-24T19:24:35+0000id: 210126779388350
email: threatexchange@support.facebook.com
name: URLQueryThreatData Feed
VISIBLEhttps://www.test.com/REVIEWED_AUTOMATICALLYWARNINGWHITEUNKNOWNURI
2015-07-09T03:04:19+00001835880593160550id: 838258172933557
indicator: https://www.test.com/
type: URI
2020-07-24T03:37:14+0000id: 820763734618599
email: threatexchange@support.facebook.com
name: Facebook Administrator
HAS_PRIVACY_GROUPhttps://www.test.com/REVIEWED_AUTOMATICALLYINFOREDUNKNOWNURI

domain#


Checks domain reputation.

Base Command#

domain

Input#

Argument NameDescriptionRequired
domainDomain name to check reputation.Required
limitThe maximum number of results per page. The maximum is 1000. Default is 20.Optional
headersA comma-separated list of headers to display in human-readable format. For example: header1,header2,header3.Optional
sinceThe start timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional
untilThe end timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00), and free text (e.g., 24 hours ago).Optional

Context Output#

PathTypeDescription
Domain.NameStringThe domain found.
DBotScore.IndicatorStringThe indicator that was tested.
DBotScore.TypeStringThe indicator type.
DBotScore.VendorStringThe vendor used to calculate the score.
DBotScore.ScoreNumberThe actual score.
Domain.Malicious.VendorStringFor malicious domains, the vendor that made the decision.
Domain.Malicious.DescriptionStringFor malicious domains, the reason that the vendor made the decision.
ThreatExchange.Domain.share_levelStringA designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.
ThreatExchange.Domain.confidenceNumberA rating, from 0-100, on how confident the publisher is of the threat indicator's status. 0 is the least confident. 100 is the most confident.
ThreatExchange.Domain.indicator.idStringThe ID of the threat indicator described by the descriptor.
ThreatExchange.Domain.indicator.indicatorStringThe threat indicator described by the descriptor.
ThreatExchange.Domain.indicator.typeStringThe type of the threat indicator described by the descriptor.
ThreatExchange.Domain.privacy_typeStringThe level of privacy applied to the descriptor. Also known as "visibility".
ThreatExchange.Domain.last_updatedDateDatetime the threat descriptor was last updated. Automatically computed; not directly editable.
ThreatExchange.Domain.statusStringIf the indicator is known to be malicious.
ThreatExchange.Domain.owner.emailStringThe email of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.Domain.owner.idStringThe ID of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.Domain.owner.nameStringThe name of the ThreatExchange member that submitted the descriptor. Non-editable
ThreatExchange.Domain.raw_indicatorStringA raw, unsanitized string of the indicator being described.
ThreatExchange.Domain.review_statusStringDescribes how the indicator was vetted.
ThreatExchange.Domain.typeStringThe type of indicator.
ThreatExchange.Domain.idStringUnique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.
ThreatExchange.Domain.descriptionStringA short summary of the indicator and threat.
ThreatExchange.Domain.severityStringSeverity of the threat associated with the indicator.
ThreatExchange.Domain.added_onDateDatetime the analysis was created.

Command Example#

!domain domain=google.com

Context Example#

{
"DBotScore": {
"Indicator": "google.com",
"Reliability": "C - Fairly reliable",
"Score": 0,
"Type": "domain",
"Vendor": "ThreatExchange v2"
},
"Domain": {
"DetectionEngines": 2,
"Name": "google.com"
},
"ThreatExchange": {
"Domain": [
{
"added_on": "2018-05-02T18:05:33+0000",
"confidence": 75,
"id": "1688788781168786",
"indicator": {
"id": "826838047363868",
"indicator": "google.com",
"type": "DOMAIN"
},
"last_updated": "2020-07-24T21:13:36+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "1656584897716085",
"name": "JoeSandbox Analysis"
},
"privacy_type": "HAS_PRIVACY_GROUP",
"raw_indicator": "google.com",
"review_status": "UNREVIEWED",
"severity": "INFO",
"share_level": "RED",
"status": "UNKNOWN",
"type": "DOMAIN"
}
]
}
}

Human Readable Output#

ThreatExchange Result for domain google.com#

added_onconfidenceidindicatorlast_updatedownerprivacy_typeraw_indicatorreview_statusseverityshare_levelstatustype
2018-05-02T18:05:33+0000751688788781168786id: 826838047363868
indicator: google.com
type: DOMAIN
2020-07-24T21:13:36+0000id: 1656584897716085
email: threatexchange@support.facebook.com
name: JoeSandbox Analysis
HAS_PRIVACY_GROUPgoogle.comUNREVIEWEDINFOREDUNKNOWNDOMAIN

threatexchange-query#


Searches for subjective opinions on indicators of compromise stored in ThreatExchange.

Base Command#

threatexchange-query

Input#

Argument NameDescriptionRequired
textFree-form text field with a value to search for. This can be a file hash or a string found in other fields of the objects.Required
typeThe type of descriptor to search for. Possible values are: ADJUST_TOKEN, API_KEY, AS_NUMBER, BANNER, CMD_LINE, COOKIE_NAME, CRX, DEBUG_STRING, DEST_PORT, DIRECTORY_QUERIED, DOMAIN, EMAIL_ADDRESS, FILE_CREATED, FILE_DELETED, FILE_MOVED, FILE_NAME, FILE_OPENED, FILE_READ, FILE_WRITTEN, GET_PARAM, HASH_IMPHASH, HASH_MD5, HASH_PDQ, HASH_TMK, HASH_SHA1, HASH_SHA256, HASH_SSDEEP, HASH_VIDEO_MD5, HTML_ID, HTTP_REQUEST, IP_ADDRESS, IP_SUBNET, ISP, LATITUDE, LATITUDE, LAUNCH_AGENT, LOCATION, LONGITUDE, MALWARE_NAME, MEMORY_ALLOC, MEMORY_PROTECT, MEMORY_WRITTEN, MUTANT_CREATED, MUTEX, NAME_SERVER, OTHER_FILE_OP, PASSWORD, PASSWORD_SALT, PAYLOAD_DATA, PAYLOAD_TYPE, POST_DATA, PROTOCOL, REFERER, REGISTRAR, REGISTRY_KEY, REG_KEY_CREATED, REG_KEY_DELETED, REG_KEY_ENUMERATED, REG_KEY_MONITORED, REG_KEY_OPENED, REG_KEY_VALUE_CREATED, REG_KEY_VALUE_DELETED, REG_KEY_VALUE_MODIFIED, REG_KEY_VALUE_QUERIED, SIGNATURE, SOURCE_PORT, TELEPHONE, TEXT_STRING, TREND_QUERY, URI, USER_AGENT, VOLUME_QUERIED, WEBSTORAGE_KEY, WEB_PAYLOAD, WHOIS_NAME, WHOIS_ADDR1, WHOIS_ADDR2, XPI.Required
limitThe maximum number of results per page. The maximum is 1000. Default is 20.Optional
headersA comma-separated list of headers to display in human-readable format. For example: header1,header2,header3.Optional
sinceThe start timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00). and free text (e.g., 24 hours ago).Optional
untilThe end timestamp for collecting malware. Supported time formats: epoch time (e.g., 1619870400), ISO 8601 (e.g., 2021-05-01T12:00:00). and free text (e.g., 24 hours ago).Optional
strict_textWhen set to 'true', the API will not do approximate matching on the value in the text. Default is false.Optional
beforeReturns results collected before this cursor.Optional
afterReturns results collected after this cursor.Optional

Context Output#

PathTypeDescription
ThreatExchange.Query.data.share_levelStringA designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.
ThreatExchange.Query.data.last_updatedDateDatetime the threat descriptor was last updated. Automatically computed; not directly editable.
ThreatExchange.Query.data.owner.emailStringThe email of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.Query.data.owner.idStringThe ID of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.Query.data.owner.nameStringThe name of the ThreatExchange member that submitted the descriptor. Non-editable.
ThreatExchange.Query.data.raw_indicatorStringA raw, unsanitized string of the indicator being described.
ThreatExchange.Query.data.typeStringThe type of indicator.
ThreatExchange.Query.data.idStringUnique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.
ThreatExchange.Query.data.added_onDateThe datetime this descriptor was first uploaded. Automatically computed; not directly editable.
ThreatExchange.Query.paging.beforeStringPaging before cursor.
ThreatExchange.Query.paging.afterStringPaging after cursor.

Command Example#

!threatexchange-query text=geektime type=URI limit=3

Context Example#

{
"ThreatExchange": {
"Query": {
"data": [
{
"added_on": "2018-08-30T07:12:28+0000",
"confidence": 50,
"id": "2036544083043163",
"indicator": {
"id": "2036543926376512",
"indicator": "http://www.geektime.co.il/wp-content/uploads/2016/09/",
"type": "URI"
},
"last_updated": "2021-03-03T02:41:06+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "820763734618599",
"name": "Facebook Administrator"
},
"privacy_type": "VISIBLE",
"raw_indicator": "http://www.geektime.co.il/wp-content/uploads/2016/09/",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "INFO",
"share_level": "GREEN",
"status": "UNKNOWN",
"type": "URI"
},
{
"added_on": "2018-08-28T14:59:24+0000",
"confidence": 50,
"id": "1799344580151062",
"indicator": {
"id": "1799344400151080",
"indicator": "http://www.geektime.co.il/wp-content/uploads/2016/05/",
"type": "URI"
},
"last_updated": "2020-07-24T20:12:26+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "820763734618599",
"name": "Facebook Administrator"
},
"privacy_type": "VISIBLE",
"raw_indicator": "http://www.geektime.co.il/wp-content/uploads/2016/05/",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "INFO",
"share_level": "GREEN",
"status": "UNKNOWN",
"type": "URI"
},
{
"added_on": "2018-08-24T20:16:16+0000",
"confidence": 50,
"id": "2265237266824665",
"indicator": {
"id": "2265236920158033",
"indicator": "http://www.geektime.co.il/wp-content/uploads/2016/07/",
"type": "URI"
},
"last_updated": "2020-07-24T18:45:09+0000",
"owner": {
"email": "threatexchange@support.facebook.com",
"id": "820763734618599",
"name": "Facebook Administrator"
},
"privacy_type": "VISIBLE",
"raw_indicator": "http://www.geektime.co.il/wp-content/uploads/2016/07/",
"review_status": "REVIEWED_AUTOMATICALLY",
"severity": "INFO",
"share_level": "GREEN",
"status": "UNKNOWN",
"type": "URI"
}
],
"paging": {
"after": "AcGbapTFY3H6ZCEZBYp5gdlibpIrqCJhOm4uk1YgoxkT8nJFgNZCDzzXF04S89kT5ZCPiUUZD",
"before": "AcFjybJa7Ba5DZBti3wUtysfdqtcOc6lezkjjhRJAMgvCok7nBQUB40uKU5K2xyZBYnF4ZD"
},
"text": "geektime",
"type": "URI"
}
}
}

Human Readable Output#

ThreatExchange Query Result:#

added_onconfidenceidindicatorlast_updatedownerprivacy_typeraw_indicatorreview_statusseverityshare_levelstatustype
2018-08-30T07:12:28+0000502036544083043163id: 2036543926376512
indicator: http://www.geektime.co.il/wp-content/uploads/2016/09/
type: URI
2021-03-03T02:41:06+0000id: 820763734618599
email: threatexchange@support.facebook.com
name: Facebook Administrator
VISIBLEhttp://www.geektime.co.il/wp-content/uploads/2016/09/REVIEWED_AUTOMATICALLYINFOGREENUNKNOWNURI
2018-08-28T14:59:24+0000501799344580151062id: 1799344400151080
indicator: http://www.geektime.co.il/wp-content/uploads/2016/05/
type: URI
2020-07-24T20:12:26+0000id: 820763734618599
email: threatexchange@support.facebook.com
name: Facebook Administrator
VISIBLEhttp://www.geektime.co.il/wp-content/uploads/2016/05/REVIEWED_AUTOMATICALLYINFOGREENUNKNOWNURI
2018-08-24T20:16:16+0000502265237266824665id: 2265236920158033
indicator: http://www.geektime.co.il/wp-content/uploads/2016/07/
type: URI
2020-07-24T18:45:09+0000id: 820763734618599
email: threatexchange@support.facebook.com
name: Facebook Administrator
VISIBLEhttp://www.geektime.co.il/wp-content/uploads/2016/07/REVIEWED_AUTOMATICALLYINFOGREENUNKNOWNURI

Pagination:#

afterbefore
AcGbapTFY3H6ZCEZBYp5gdlibpIrqCJhOm4uk1YgoxkT8nJFgNZCDzzXF04S89kT5ZCPiUUZDAcFjybJa7Ba5DZBti3wUtysfdqtcOc6lezkjjhRJAMgvCok7nBQUB40uKU5K2xyZBYnF4ZD

threatexchange-members#


Returns a list of current members of the ThreatExchange, alphabetized by application name. Each application may also include an optional contact email address. You can set this address, if desired, under the settings panel for your application.

Base Command#

threatexchange-members

Input#

There are no input arguments for this command.

Context Output#

PathTypeDescription
ThreatExchange.Member.idStringMember's ID.
ThreatExchange.Member.emailStringMember's email.
ThreatExchange.Member.nameStringMember's name.

Command Example#

!threatexchange-members

Context Example#

{
"ThreatExchange": {
"Member": [
{
"email": "user@example.com",
"id": "906975333085907",
"name": "2U ThreatExchange App"
}
]
}
}

Human Readable Output#

ThreatExchange Members:#

idnameemail
9069753330859072U ThreatExchange Appuser@example.com

threatexchange-tags-search#


Enables searching for tags in ThreatExchange. With this call you can search for ThreatTag objects by text.

Base Command#

threatexchange-tags-search

Input#

Argument NameDescriptionRequired
textFreeform text field with a value to search for.
This value should describe a broader type or class of attack you are interested in.
Required
beforeReturns results collected before this cursor.Optional
afterReturns results collected after this cursor.Optional

Context Output#

PathTypeDescription
ThreatExchange.Tag.data.idStringThe tag's ID.
ThreatExchange.Tag.data.textStringThe tag's text.
ThreatExchange.Tag.paging.beforeUnknownPaging before cursor.
ThreatExchange.Tag.paging.afterStringPaging after cursor.

Command Example#

!threatexchange-tags-search text=malware

Context Example#

{
"ThreatExchange": {
"Tag": {
"data": [
{
"id": "1318516441499594",
"text": "malware"
}
],
"paging": {
"after": "MAZDZD",
"before": "MAZDZD"
},
"text": "malware"
}
}
}

Human Readable Output#

ThreatExchange Tags:#

idtext
1318516441499594malware

Pagination:#

afterbefore
MAZDZDMAZDZD

threatexchange-tagged-objects-list#


Gets a list of tagged objects for a specific ThreatTag.

Base Command#

threatexchange-tagged-objects-list

Input#

Argument NameDescriptionRequired
tag_idThreatTag ID to get it's related tagged objects. ThreatTag ID can be retrieved by the threatexchange-tags-search command.Required
tagged_sinceFetches all objects that have been tagged since this time (inclusive).Optional
tagged_untilFetches all objects that have been tagged until this time (inclusive).Optional
beforeReturns results collected before this cursor.Optional
afterReturns results collected after this cursor.Optional

Context Output#

PathTypeDescription
ThreatExchange.TaggedObject.data.idStringThe ID of the tagged object.
ThreatExchange.TaggedObject.data.typeStringThe type of the tagged object.
ThreatExchange.TaggedObject.data.nameStringThe name of the tagged object.
ThreatExchange.TaggedObject.paging.beforeStringPaging before cursor.
ThreatExchange.TaggedObject.paging.afterStringPaging after cursor.

Command Example#

!threatexchange-tagged-objects-list tag_id=1318516441499594

Context Example#

{
"ThreatExchange": {
"TaggedObject": {
"data": [
{
"id": "1460089820713228",
"name": "cafece4c21572473fed821bb64381d0a",
"type": "MALWARE_DESCRIPTOR"
}
],
"paging": {
"after": "QVFIUmFFOERJZATZAmMW9wRnJwbjFiY2tTdFpHRk9PTVlIYm80bVREdXlIS1pWWmRrSU4zSHpYT2dXUTR0QW1HTkVWal9oalU5dGhyRlZA6U2ZAKWC04T0R0NXVR",
"before": "QVFIUlhyUENfX2U1UUkyOWxySlpEWVFveEJiM0twRVpGWkc2LWdLME1CU0hYS3hfVzFibjltSUdTYi1LdWlBNF8zenZADaUlZAWm1vQ1RkVm1zc3NnSllza2lB"
},
"tag_id": "1318516441499594"
}
}
}

Human Readable Output#

ThreatExchange Tagged Objects for ThreatTag: 1318516441499594#

idnametype
1460089820713228cafece4c21572473fed821bb64381d0aMALWARE_DESCRIPTOR

Pagination:#

afterbefore
QVFIUmFFOERJZATZAmMW9wRnJwbjFiY2tTdFpHRk9PTVlIYm80bVREdXlIS1pWWmRrSU4zSHpYT2dXUTR0QW1HTkVWal9oalU5dGhyRlZA6U2ZAKWC04T0R0NXVRQVFIUlhyUENfX2U1UUkyOWxySlpEWVFveEJiM0twRVpGWkc2LWdLME1CU0hYS3hfVzFibjltSUdTYi1LdWlBNF8zenZADaUlZAWm1vQ1RkVm1zc3NnSllza2lB

threatexchange-object-get-by-id#


Gets ThreatExchange object by ID.

Base Command#

threatexchange-object-get-by-id

Input#

Argument NameDescriptionRequired
object_idID of a ThreatExchange object. Can be retrieved by ThreatExchange reputation commands and threatexchange-tagged-objects-list command.Required

Context Output#

PathTypeDescription
ThreatExchange.Object.idStringID of a ThreatExchange object.

Command Example#

!threatexchange-object-get-by-id object_id=1318516441499594

Context Example#

{
"ThreatExchange": {
"Object": {
"id": "1318516441499594",
"text": "malware"
}
}
}

Human Readable Output#

ThreatExchange Object 1318516441499594:#

idtext
1318516441499594malware