ThreatFox API

Python library and CLI tool for interacting with the ThreatFox API.

Massive thanks to abuse.ch for all the work they do!

Install

This python library requires python3.7 or greater. Ideally, python3.9 or greater.

pip install threatfox

Configure

You can supply your API Key to the CLI tool with the --api-key option. For repeated use by the current user, you can save the API key with threatfox --save-api-key. This will store the key at ~/.threatfox/config.ini. If you want all users on a system to share an API key, you can add your API Key to a config like the following at /etc/threatfox/config.ini:

[default]
api_key = 

Proxy settings can be configured for current user or system wide with the following option supplied to the default section.

proxy = http://user:pass@proxy_address:proxy_port

User configurations override system configurations.

CLI Tool

Note that the CLI tool returns human readable JSON for convenient parsing, scripting, and data manipulation. If you're an analyst and not acquainted with jq, it's a powerful friend.

$ threatfox -h
usage: threatfox [-h] [-d] [--api-key API_KEY] [--save-api-key SAVE_API_KEY] {ioc,i,malware,m,tag,t,submit,s} ...

Tool for interacting with the ThreatFox API.

positional arguments:
  {ioc,i,malware,m,tag,t,submit,s}
    ioc (i)             ThreatFox IOC API interface.
    malware (m)         Interact with ThreatFox Malware APIs.
    tag (t)             ThreatFox tag operations.
    submit (s)          Submit IOCs to ThreatFox.

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           Turn on debug logging.
  --api-key API_KEY     An ThreatFox API key to use.
  --save-api-key SAVE_API_KEY
                        Save an ThreatFox API key to use as the default.

Example: Search for an IOC

Here is an example of searching for an IOC by value with the command line tool:

$ threatfox ioc -s 'http://auto.lambolero.com/f1nygync/J18Keqh/'
{
  "query_status": "ok",
  "data": [
    {
      "id": "294783",
      "ioc": "http://auto.lambolero.com/f1nygync/J18Keqh/",
      "threat_type": "payload_delivery",
      "threat_type_desc": "Indicator that identifies a malware distribution server (payload delivery)",
      "ioc_type": "url",
      "ioc_type_desc": "URL that delivers a malware payload",
      "malware": "win.emotet",
      "malware_printable": "Emotet",
      "malware_alias": "Geodo,Heodo",
      "malware_malpedia": "https://malpedia.caad.fkie.fraunhofer.de/details/win.emotet",
      "confidence_level": 90,
      "first_seen": "2022-01-13 20:16:02 UTC",
      "last_seen": null,
      "reference": null,
      "reporter": "Cryptolaemus1",
      "tags": null,
      "malware_samples": []
    }
  ]
}

Example: Submitting IOCs

You can submit one or more IOCs via the command line too:

$ threatfox submit -tt payload -it sha256_hash -m win.ave_maria -i db0b1dbcb819306bbeab5de5dc5cddf3861cd96bb142e4feacd425b064f0ef33 -cl 75 -r 'https://app.any.run/tasks/f6ab3692-5bcf-46e9-af21-f3bb6a1dd586/' -t "Ave Maria"
{
  "query_status": "ok",
  "data": {
    "ok": [
      "db0b1dbcb819306bbeab5de5dc5cddf3861cd96bb142e4feacd425b064f0ef33"
    ],
    "ignored": [],
    "duplicated": [],
    "reward": 5
  }
}

You can also submit IOC in bulk by passing the IOCs via STDIN or by pointing to a file containing the IOC values.

$ cat urls.txt
http://auto.lambolero.com/zip/AIN_426946/
http://auto.lambolero.com/f1nygync/065138_50/
http://auto.lambolero.com/f1nygync/IOENXupeXUt/

From STDIN

$ cat urls.txt | threatfox submit -tt payload_delivery -it url -m win.emotet -cl 90 -t Emotet --from-stdin
{
  "query_status": "ok",
  "data": {
    "ok": [
      "http://auto.lambolero.com/zip/AIN_426946/",
      "http://auto.lambolero.com/f1nygync/065138_50/",
      "http://auto.lambolero.com/f1nygync/IOENXupeXUt/"
    ],
    "ignored": [],
    "duplicated": [],
    "reward": 5
  }
}

From File

threatfox submit -tt payload_delivery -it url -m win.emotet -cl 90 -t Emotet --from-file urls.txt       
{
  "query_status": "ok",
  "data": {
    "ok": [],
    "ignored": [],
    "duplicated": [
      "http://auto.lambolero.com/zip/AIN_426946/",
      "http://auto.lambolero.com/f1nygync/065138_50/",
      "http://auto.lambolero.com/f1nygync/IOENXupeXUt/"
    ],
    "reward": 0
  }
}

Questions

If you have any questions at all or run into a bug, please let me know by opening an issue.

Also, if there is interest I can document all of the various ways you could use this tool via the CLI and as a python library.