ThreatFox API

ThreatFox offers the following APIs for sharing and cobtaining IOCs.

Auth-Key (Required) Query recent IOCs Submission Policy Query an IOC by ID Search an IOC Search for IOCs by file hash Query tag Query malware family Share (submit) an IOC Identify malware name (label) Get malware list Get IOC / threat types Get tag list Example python3 scripts Terms of Services (ToS)

Obtain an Auth-Key (Required)

In order to interact with the ThreatFox API, you need to obtain an Auth-Key first. If you don't have one you can get one for free here:

abuse.ch Authentication Portal

Whenever you interact with the ThreatFox API, you must include the HTTP header Auth-Key with your Auth-Key. Example curl command:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "get_iocs", "days": 1 }'

Query recent IOCs

You can obtain a copy of the current IOC dataset from ThreatFox by sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `get_iocs`	get_iocs
`days`	No	Number of days to filter IOCs for (based on `first_seen`) Min: 1, Max: 7. Default: 3	1

Here's a sample curl command that describes how to query the API for a get_iocs:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "get_iocs", "days": 7 }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "id": "41",
            "ioc": "gaga.com",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "domain",
            "ioc_type_desc": "Domain that is used for botnet Command&control (C&C)",
            "malware": "win.dridex",
            "malware_printable": "Dridex",
            "malware_alias": null,
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.dridex",
            "confidence_level": 50,
            "first_seen": "2020-12-08 13:36:27 UTC",
            "last_seen": null,
            "reporter": "abuse_ch",
            "reference": "https:\/\/twitter.com\/JAMESWT_MHT\/status\/1336229725082177536",
            "tags": [
                "exe",
                "test"
            ]
        },
        {
            "id": "40",
            "ioc": "susu.com",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "domain",
            "ioc_type_desc": "Domain that is used for botnet Command&control (C&C)",
            "malware": "win.dridex",
            "malware_printable": "Dridex",
            "malware_alias": null,
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.dridex",
            "confidence_level": 50,
            "first_seen": "2020-12-08 13:36:27 UTC",
            "last_seen": null,
            "reporter": "abuse_ch",
            "reference": null,
            "tags": [
                "exe",
                "test"
            ]
        },
        [...]
}

Data exports

You may have noticed that this API endpoint does not return IOCs that are older than 7 days. This is for performance reasons. If you would like to get data export of all IOCs known to ThreatFox, please have a look at the ThreatFox data export:

Submission Policy

Before you start to indicators of compromise (IOCs) to ThreatFox, please read the following submission policy:

Confirmed IOCs only: Please do only submit confirmed / vetted IOCs to ThreatFox.

Note: Should you repeatedly violate the submission policy documented above, your account may get banned from contributing to ThreatFox.

Query an IOC by ID

You can obtain query ThreatFox for a particulaar IOC id sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `ioc`	ioc
`id`	No	ThreatFox IOC ID of the IOC you would like to query	41

Here's a sample curl command that describes how to query the API for a ioc:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "ioc", "id": 41 }'

A response from this API look like this:

  {
      "id": "41",
      "ioc": "gaga.com",
      "threat_type": "botnet_cc",
      "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
      "ioc_type": "domain",
      "ioc_type_desc": "Domain that is used for botnet Command&control (C&C)",
      "malware": "win.dridex",
      "malware_printable": "Dridex",
      "malware_alias": null,
      "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.dridex",
      "confidence_level": 50,
      "first_seen": "2020-12-08 13:36:27 UTC",
      "last_seen": null,
      "reference": "https:\/\/twitter.com\/JAMESWT_MHT\/status\/1336229725082177536",
      "reporter": "abuse_ch",
      "comment": "These domains are too bad!",
      "tags": [
          "exe",
          "test"
      ],
      "credits": [
          {
              "credits_from": "ThreatFox",
              "credits_amount": 5
          }
      ],
      "malware_samples": [
       {
           "time_stamp": "2021-03-23 08:18:06 UTC",
           "md5_hash": "5b7e82e051ade4b14d163eea2a17bf8b",
           "sha256_hash": "b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7\/"
       },
       {
           "time_stamp": "2021-03-23 08:18:08 UTC",
           "md5_hash": "694bf1540ff9d86851adbe15e9568d13",
           "sha256_hash": "05a7bd44b039d1c1b0eb7ed12d2266ca341ba63d66084e151cfef5649c52ef08",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/05a7bd44b039d1c1b0eb7ed12d2266ca341ba63d66084e151cfef5649c52ef08\/"
       },
       {
           "time_stamp": "2021-03-23 08:18:09 UTC",
           "md5_hash": "9024c9672b189faa5880a47031397350",
           "sha256_hash": "b4f33452f07d0b284df64219b015c331b87faad62c11bfcc246513d06c101f6e",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/b4f33452f07d0b284df64219b015c331b87faad62c11bfcc246513d06c101f6e\/"
       },
       {
           "time_stamp": "2021-03-23 08:18:11 UTC",
           "md5_hash": "938bf3f035fbf95144ec5493ef1920af",
           "sha256_hash": "7c1648815aa70e879d1f6f542ae8c41ba912305fe8adc70f5970026adc2e46a6",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/7c1648815aa70e879d1f6f542ae8c41ba912305fe8adc70f5970026adc2e46a6\/"
       },
       {
           "time_stamp": "2021-03-23 08:18:12 UTC",
           "md5_hash": "aadaa91ca106e59aa1e4e59f8f956c23",
           "sha256_hash": "cca1a1f85ee5c99d124bd9df98342eae40343b8757838bb7f1e1385fe8b836d8",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/cca1a1f85ee5c99d124bd9df98342eae40343b8757838bb7f1e1385fe8b836d8\/"
       },
       {
           "time_stamp": "2021-03-23 08:18:14 UTC",
           "md5_hash": "ad721c851b6eca529ed7054fb3d51723",
           "sha256_hash": "40ae56610e25e1b7dbe5e0c69bd432fbcb4ebe014cd3e0ca66b5dcf98ed34602",
           "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/40ae56610e25e1b7dbe5e0c69bd432fbcb4ebe014cd3e0ca66b5dcf98ed34602\/"
       }
   ]
}

Search an IOC

You can search for an IOC on ThreatFox by sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `search_ioc`	search_ioc
`search_term`	Yes	IOC you want to search for	94.103.84.81

Here's a sample curl command that describes how to query the API for a search_ioc:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "search_ioc", "search_term": "139.180.203.104" }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "id": "12",
            "ioc": "139.180.203.104:443",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "ip:port",
            "ioc_type_desc": "ip:port combination that is used for botnet Command&control (C&C)",
            "malware": "win.cobalt_strike",
            "malware_printable": "Cobalt Strike",
            "malware_alias": "Agentemis,BEACON,CobaltStrike",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.cobalt_strike",
            "confidence_level": 75,
            "first_seen": "2020-12-06 09:10:23 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": null,
            "malware_samples": [
                {
                    "time_stamp": "2021-03-23 08:18:06 UTC",
                    "md5_hash": "5b7e82e051ade4b14d163eea2a17bf8b",
                    "sha256_hash": "b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7\/"
                },
                {
                    "time_stamp": "2021-03-23 08:18:08 UTC",
                    "md5_hash": "694bf1540ff9d86851adbe15e9568d13",
                    "sha256_hash": "05a7bd44b039d1c1b0eb7ed12d2266ca341ba63d66084e151cfef5649c52ef08",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/05a7bd44b039d1c1b0eb7ed12d2266ca341ba63d66084e151cfef5649c52ef08\/"
                },
                {
                    "time_stamp": "2021-03-23 08:18:09 UTC",
                    "md5_hash": "9024c9672b189faa5880a47031397350",
                    "sha256_hash": "b4f33452f07d0b284df64219b015c331b87faad62c11bfcc246513d06c101f6e",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/b4f33452f07d0b284df64219b015c331b87faad62c11bfcc246513d06c101f6e\/"
                },
                {
                    "time_stamp": "2021-03-23 08:18:11 UTC",
                    "md5_hash": "938bf3f035fbf95144ec5493ef1920af",
                    "sha256_hash": "7c1648815aa70e879d1f6f542ae8c41ba912305fe8adc70f5970026adc2e46a6",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/7c1648815aa70e879d1f6f542ae8c41ba912305fe8adc70f5970026adc2e46a6\/"
                },
                {
                    "time_stamp": "2021-03-23 08:18:12 UTC",
                    "md5_hash": "aadaa91ca106e59aa1e4e59f8f956c23",
                    "sha256_hash": "cca1a1f85ee5c99d124bd9df98342eae40343b8757838bb7f1e1385fe8b836d8",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/cca1a1f85ee5c99d124bd9df98342eae40343b8757838bb7f1e1385fe8b836d8\/"
                },
                {
                    "time_stamp": "2021-03-23 08:18:14 UTC",
                    "md5_hash": "ad721c851b6eca529ed7054fb3d51723",
                    "sha256_hash": "40ae56610e25e1b7dbe5e0c69bd432fbcb4ebe014cd3e0ca66b5dcf98ed34602",
                    "malware_bazaar": "https:\/\/bazaar.abuse.ch\/sample\/40ae56610e25e1b7dbe5e0c69bd432fbcb4ebe014cd3e0ca66b5dcf98ed34602\/"
                }
            ]

        }
    ]
}

Search for IOCs by file hash

You can search for IOCs associated with a certain file hash (MD5 hash or SHA256 hash) by sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `search_hash`	search_hash
`hash`	Yes	`MD5 hash` or `SHA256 hash`	2151c4b970eff0071948dbbc19066aa4

Here's a sample curl command that describes how to query the API for a search_ioc:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "search_hash", "hash": "2151c4b970eff0071948dbbc19066aa4" }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "id": "4726",
            "ioc": "http:\/\/harold.jetos.com:3606\/is-ready",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "url",
            "ioc_type_desc": "URL that is used for botnet Command&control (C&C)",
            "malware": "win.houdini",
            "malware_printable": "Houdini",
            "malware_alias": "Hworm,Jenxcus,Kognito,Njw0rm,WSHRAT,dinihou,dunihi",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.houdini",
            "confidence_level": 100,
            "first_seen": "2021-03-23 14:50:33 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": [
                "WSHRAT"
            ]
        },
        {
            "id": "4727",
            "ioc": "http:\/\/harold.jetos.com:3606\/moz-sdk",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "url",
            "ioc_type_desc": "URL that is used for botnet Command&control (C&C)",
            "malware": "win.houdini",
            "malware_printable": "Houdini",
            "malware_alias": "Hworm,Jenxcus,Kognito,Njw0rm,WSHRAT,dinihou,dunihi",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.houdini",
            "confidence_level": 100,
            "first_seen": "2021-03-23 14:50:35 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": [
                "WSHRAT"
            ]
        },
        {
            "id": "4728",
            "ioc": "http:\/\/harold.jetos.com:3606\/show-toast",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "url",
            "ioc_type_desc": "URL that is used for botnet Command&control (C&C)",
            "malware": "win.houdini",
            "malware_printable": "Houdini",
            "malware_alias": "Hworm,Jenxcus,Kognito,Njw0rm,WSHRAT,dinihou,dunihi",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.houdini",
            "confidence_level": 100,
            "first_seen": "2021-03-23 14:50:35 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": [
                "WSHRAT"
            ]
        },
        {
            "id": "4729",
            "ioc": "http:\/\/harold.jetos.com:3606\/ie",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "url",
            "ioc_type_desc": "URL that is used for botnet Command&control (C&C)",
            "malware": "win.houdini",
            "malware_printable": "Houdini",
            "malware_alias": "Hworm,Jenxcus,Kognito,Njw0rm,WSHRAT,dinihou,dunihi",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.houdini",
            "confidence_level": 100,
            "first_seen": "2021-03-23 14:50:36 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": [
                "WSHRAT"
            ]
        }
    ]
}

Query tag

You can search for IOCs on ThreatFox that are associated with a certain tag by sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `taginfo`	taginfo
`tag`	Yes	Tag you want to query	Magecart
`limit`	No	Max number of results (default: 100, max: 1'000)	10

Here's a sample curl command that describes how to query the API for a taginfo:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "taginfo", "tag": "Magecart", "limit": 10 }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "id": "29",
            "ioc": "jquery.su",
            "threat_type": "cc_skimming",
            "threat_type_desc": "Indicator that identifies credit card skimming infrastructure (NOT phishing)",
            "ioc_type": "domain",
            "ioc_type_desc": "Domain used for credit card skimming (usually related to Magecart attacks)",
            "malware": "js.magecart",
            "malware_printable": "magecart",
            "malware_alias": null,
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/js.magecart",
            "confidence_level": 50,
            "first_seen": "2020-12-06 15:04:03 UTC",
            "last_seen": null,
            "reference": "https:\/\/twitter.com\/AffableKraut\/status\/1335501765031174145",
            "reporter": "abuse_ch",
            "tags": [
                "Magecart"
            ]
        },
        {
            "id": "28",
            "ioc": "jquerysapi.com",
            "threat_type": "cc_skimming",
            "threat_type_desc": "Indicator that identifies credit card skimming infrastructure (NOT phishing)",
            "ioc_type": "domain",
            "ioc_type_desc": "Domain used for credit card skimming (usually related to Magecart attacks)",
            "malware": "js.magecart",
            "malware_printable": "magecart",
            "malware_alias": null,
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/js.magecart",
            "confidence_level": 50,
            "first_seen": "2020-12-06 15:04:03 UTC",
            "last_seen": null,
            "reference": "https:\/\/twitter.com\/AffableKraut\/status\/1335501765031174145",
            "reporter": "abuse_ch",
            "tags": [
                "Magecart"
            ]
        }
    ]
}

Query malware

You can search for IOCs on ThreatFox that are associated with a certain malware family by sending an HTTP POST request to the Threatfox API as documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `malwareinfo`	malwareinfo
`malware`	Yes	Malware family you want to query	Cobalt Strike
`limit`	No	Max number of results (default: 100, max: 1'000)	10

Note

When you search for a particular malware family on Threatfox, please make sure that you use the correct malware family name. A list of supported malware family names is available through the API endpoint "Get malware list" and through the web portal of Malpedia.

Here's a sample curl command that describes how to query the API for a taginfo:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "malwareinfo", "malware": "Cobalt Strike", "limit": 10 }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "id": "21",
            "ioc": "43.255.30.192:8848",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "ip:port",
            "ioc_type_desc": "ip:port combination that is used for botnet Command&control (C&C)",
            "malware": "win.cobalt_strike",
            "malware_printable": "Cobalt Strike",
            "malware_alias": "Agentemis,BEACON,CobaltStrike",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.cobalt_strike",
            "confidence_level": 50,
            "first_seen": "2020-12-06 09:47:30 UTC",
            "last_seen": null,
            "reference": null,
            "reporter": "abuse_ch",
            "tags": null
        },
        {
            "id": "13",
            "ioc": "http:\/\/94.103.84.81\/",
            "threat_type": "botnet_cc",
            "threat_type_desc": "Indicator that identifies a botnet command&control server (C&C)",
            "ioc_type": "url",
            "ioc_type_desc": "URL that is used for botnet Command&control (C&C)",
            "malware": "win.cobalt_strike",
            "malware_printable": "Cobalt Strike",
            "malware_alias": "Agentemis,BEACON,CobaltStrike",
            "malware_malpedia": "https:\/\/malpedia.caad.fkie.fraunhofer.de\/details\/win.cobalt_strike",
            "confidence_level": 50,
            "first_seen": "2020-12-06 09:16:18 UTC",
            "last_seen": null,
            "reference": "https:\/\/twitter.com\/d4rksystem\/status\/1333848341239582721",
            "reporter": "abuse_ch",
            "tags": [
                "CobaltStrike",
                "exe"
            ]
        }
    ]
}

Share (submit) an IOC

You can share (submit) indicators of compromise (IOCs) to ThreatFox by using the API documented below:

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `submit_ioc`	submit_ioc
`threat_type`	Yes	Threat type (see API types)	botnet_cc
`ioc_type`	Yes	IOC type (see API types)	domain
`malware`	Yes	malpedia malware name (see API malware list)	win.zloader
`confidence_level`	No	Confidence level 0-100. Default: 50	75
`reference`	No	Reference (url)	https://twitter.com/JAMESWT_MHT/status/1336229725082177536
`tags`	No	List of tags. Allowed characters: [A-Za-z0-9.- ]	TA505
`iocs`	Yes	List of IOCs you want to submit	tooeviltoexist.com
`comment`	No	Your comment on these IOCs	This is a very evil IOC!
`anonymous`	No	If set to 1, your submission will be anonymous. Default: 0	0

To authenticate your request, you must send the HTTP header Auth-Key with your personal Auth-Key:


Auth-Key: YOUR-AUTH-KEY-HERE

If you don't have an Auth-key yet you can get one for free here:

abuse.ch Authentication Portal

Here's a sample python3 script that shows how to share IOCs on ThreatFox:

#!/usr/bin/python3
import requests
import urllib3
import json

# Prepare HTTPSConnectionPool
headers = {
  "Auth-Key":        "YOUR-AUTH-APKEY-HERE",
}
pool = urllib3.HTTPSConnectionPool('threatfox-api.abuse.ch', port=443, maxsize=50, headers=headers, cert_reqs='CERT_NONE', assert_hostname=True)

# threat_type      - Query https://threatfox.abuse.ch/api/#types to get the appropriate
#                    threat_type / ioc_type combination
# ioc_type         - Query https://threatfox.abuse.ch/api/#types to get the appropriate
#                    threat_type / ioc_type combination
# malwareinfo      - Query https://threatfox.abuse.ch/api/#malware-list to get the appropriate
#                  - malware family or search through Malpedia web UI: https://malpedia.caad.fkie.fraunhofer.de/
# confidence_level - Optional; Must be between 0-100. Default: 50
# reference        - Optional; Must be a URL if provided
# Comment          - Optional; Your comment on the IOC(s) you want to submit
# anonymous        - Optional; 0 (false) or 1 (true). Default: 0 (false)
# tag_list         - Optional; List of tags
# iocs             - list of IOCs you want to submit

data = {
    'query':            'submit_ioc',
    'threat_type':      threat_type,
    'ioc_type':         ioc_type,
    'malware':          malware,
    'confidence_level': confidence_level,
    'reference':        reference,
    'comment':          comment,
    'anonymous':        0,
    'tags': [
        tag
    ],
    'iocs': [
        ioc
    ]
}
json_data = json.dumps(data)
response = pool.request("POST", "/api/v1/", body=json_data)
response = response.data.decode("utf-8", "ignore")
print(response)

An additional python samples script showing how to submit IOCs to ThreatFox is available here:

https://github.com/abusech/ThreatFox/blob/main/threatfox_submit-ioc.py

Need help?

If you encounter any problems when submitting IOCs to ThreatFox, please do not hesitate to contact us through the the Spamhaus Technology contact form:
https://www.spamhaus.com/#contact-form

Identify malware name (label)

If you submit IOCs to ThreatFox, you need to specify the corresponding Malware family. ThreatFox uses the malware labels from Malpedia. You can lookup the correct malware name on ThreatFox by sending a HTTP POST request to the API as documented below.

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `get_label`	get_label
`malware`	Yes	Malware you want to look for	warzone
`platform`	No	Platform (`win`, `osx`, `apk`, `jar` or `elf`)	win

Here's a sample curl command that describes how to query the API for a get_label:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "get_label", "malware": "warzone", "platform": "win"}'

A response from this API look like this:

{
    "query_status": "ok",
    "data": [
        {
            "malware": "win.ave_maria",
            "malware_printable": "Ave Maria",
            "malware_alias": "AVE_MARIA,AveMariaRAT,Warzone RAT,avemaria"
        }
    ]
}

Get malware list

You can obtain a list of supported malware families from ThreatFox by using the API documented below. The list of malware families is obtained from Malpedia.

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `malware_list`	malware_list

Here's a sample curl command that describes how to query the API for a malware_list:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "malware_list" }'

A response from this API look like this:

{
  "query_status": "ok",
  "data": {
      "win.sparksrv": {
          "malware_printable": "Sparksrv",
          "malware_alias": null
      },
      "win.sslmm": {
          "malware_printable": "SslMM",
          "malware_alias": null
      },
      "win.hermes_ransom": {
          "malware_printable": "Hermes Ransomware",
          "malware_alias": null
      },
      "apk.doublelocker": {
          "malware_printable": "DoubleLocker",
          "malware_alias": null
      },
      [...]
}

Get IOC / threat types

You can obtain a list of supported IOC / threat types from ThreatFox by using the API documented below.

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `types`	types

Here's a sample curl command that describes how to query the API for a types:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "types" }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": {
        "1": {
            "ioc_type": "url",
            "fk_threat_type": "payload_delivery",
            "description": "URL that delivers a malware payload"
        },
        "2": {
            "ioc_type": "domain",
            "fk_threat_type": "payload_delivery",
            "description": "Domain name that delivers a malware payload"
        },
        "3": {
            "ioc_type": "ip:port",
            "fk_threat_type": "payload_delivery",
            "description": "ip:port combination that delivery a malware payload"
        },
        [...]
}

Get tag list

You can obtain a list of tags known to ThreatFox by using the API documented below.

Key	Required?	Comment	Sample value
`query`	Yes	Selector, must be `tag_list`	tag_list

Here's a sample curl command that describes how to query the API for a types:

curl -H "Auth-Key: YOUR-AUTH-KEY" -X POST https://threatfox-api.abuse.ch/api/v1/ -d '{ "query": "tag_list" }'

A response from this API look like this:

{
    "query_status": "ok",
    "data": {
        "exe": {
            "first_seen": "2020-12-06 09:16:18",
            "last_seen": "2020-12-08 13:36:27",
            "color": "#D984D4"
        },

        "js": {
            "first_seen": "2020-12-06 15:04:03",
            "last_seen": "2020-12-06 15:04:03",
            "color": "#1BA0CD"
        },
        "Magecart": {
            "first_seen": "2020-12-06 15:04:03",
            "last_seen": "2020-12-06 15:04:03",
            "color": "#C41619"
        }
      }
    }

Example python scripts

You can find a handful example scripts for how to interacting with the ThreatFox API on our github repository:

Example python3 scripts for interacting with the ThreatFox API

Terms of Services (ToS)

By using the website of ThreatFox, or any of the services / datasets referenced above, you agree that:

All datasets offered by ThreatFox can be used for both, commercial and non-commercial purpose without any limitations (CC0)
Any data offered by ThreatFox is served as it is on best effort
ThreatFox can not be held liable for any false positive or damage caused by the use of the website or the datasets offered above
Any submission to ThreatFox will be treated and shared under TLP:WHITE and under Creative Commons No Rights Reserved (CC0)