Skip to main content

Group-IB THF REST API Python Bindings

Project description

Python bindings for Group-IB THF REST API

Latest Version: 1.0.6


The Group-IB THF Python Client enables you to fully integrate Group-IB THF Polygon into your malware analysis framework. Group-IB THF Polygon is a Malware Detonation & Research platform designed for deep dynamic analysis and enhanced indicators extraction.

You can use this library with


The code is written in Python and licensed under MIT.


  • python 3.6 or higher

Getting Started


pip install pythf

For upgrading pythf to a more recent version, use

pip install --upgrade pythf


In order to perform any queries via the API, you will need to get the API token for your Group-IB THF user.

  1. Open Group-IB THF Huntbox web interface.
  2. Navigate to "Profile" and click "Generate Auth Token".
  3. Copy this token. This is your API Key.

Sample Code

  1. Let's start by sending some file ("sample.exe") for analysis:
from pythf import Polygon

polygon = Polygon("MY_API_KEY")
analysis = polygon.upload_file(open("sample.exe", "rb"))
  1. If you want to detonate some URL, use the next method:
analysis = polygon.upload_url("")

Now we have the analysis object. To update analysis status and get info about it, use the next method:

info = analysis.get_info(extended=True)

Notice: parameter extended allows you to get full or short info about analysis process. The short version of the information is as follows:

    "status": "IN PROGRESS" | "FINISHED" | "FAILED",
    "verdict": None | True | False,
    "report_url": "https://...",
    "error": "Some error"  # optional field only for "FAILED" status

If the "verdict" is True then object is malicious. Notice: THF need some time to generate the report url. Until it happens, the response will not contain this field.

  1. You can get full report as a dictionary:
report = analysis.get_report()
  1. There is a way to download some detonation artifacts and the report:
archived_report = analysis.export_report()  # Export report as .tar.
pdf_report = analysis.export_pdf_report()   # Export report as PDF
pcap = analysis.export_pcap()               # Export all network activity as .pcap file.
screen_video = analysis.export_video()      # Export the screen-video of the detonation process.

Notice: If there is no artifact, all this methods raise ObjectNotFoundError.

  1. You can check some hash reputation with this method:
reputation = polygon.get_hash_reputation("md5", "ac55cf33c4691f863bfb3af8c06a7244")

You can get reputation for md5, sha1, sha256 hash types. The method returns a dict object:

    "found": true | false,
    "verdict": true | false,
    "malware_families": [],
    "score": float in [0; 100]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pythf-1.0.6.tar.gz (10.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page