malsub: online malware analysis and threat intelligence services

malsub is a Python 3.6.x framework that wraps several web services of online malware and URL analysis sites through their RESTful Application Programming Interfaces (APIs). It supports submitting files or URLs for analysis, retrieving reports by hash values, domains, IPv4 addresses or URLs, downloading samples and other files, making generic searches and getting API quota values. The framework is designed in a modular way so that new services can be added with ease by following the provided template module and functions to make HTTP GET and POST requests and to pretty print results. This approach avoids having to write individual and specialized wrappers for each and every API by leveraging what they have in common in their calls and responses. The framework is also multi-threaded and dispatches service API functions across a thread pool for each input argument, meaning that it spawns a pool of threads per each file provided for submission or per each hash value provided for report retrieval, for example.

The following services are currently included in malsub:

• AVCaesar;
• Have I been pwned?;
• Hybrid Analysis;
• Joe Sandbox Cloud;
• MalShare;
• maltracker;
• malwr;
• Metadefender;
• OpenPhish;
• PDF Examiner;
• PhishTank;
• QuickSand;
• Safe Browsing;
• Threat Crowd;
• ThreatStream;
• URLVoid;
• VirusTotal;
• VxStream.

Most of these services require API keys that are generated after registering an account in their respective websites, which need to be specified in the apikey.yaml file according to the given structure. Note that some of the already bundled services are limited in supported operations due to the fact that they were developed with free API keys. API keys associated with paid subscriptions are allowed to make additional calls not open to the public and may not be restricted by a given quota. Yet, malsub can process multiple input arguments and pause between requests as a workaround for cooldown periods.

The main goal of malsub is to serve as a one-stop-shop for querying multiple online services of malware analysis and for aiding investigators. It is thus suitable for incident response, forensic and malware analysts, as well as for security practitioners alike.

Installation

git clone https://github.com/diogo-fernan/malsub.git
cd malsub
pip install -r requirements.txt

Usage

Usage: malsub [-h] [-a <service>] [-H] [-p <num>] [-R] [-v ...]

              [-d | -f | -q | -r | -s | -t]

              [-i | -o | -l | -u]

              [<input> ...]



Interact with online malware, URL and intelligence analysis services for malware

samples, domain names, IP addresses or URLs.



Options:

  -h, --help  show this help message and exit



  -a, --analysis <service>  character-separated list of services (class or short names) [default: all]

  -H, --servhelp     show help messages about selected services and exit

  -p, --pause <num>  wait an interval in seconds between service requests (rate limit) [default: 0]

  -R, --recursive    recurse on input paths

  -v, --verbose      display verbose and debug messages



API functions:

  -d, --download  download files or malware samples

  -f, --find      search for arbitrary terms (input format irrelevant)

  -q, --quota     retrieve API user quota

  -r, --report    retrieve submission reports for domains, files, hash values, IP addresses or URLs

  -s, --submit    submit malware samples or URLs for analysis

  -t, --test      test API calls by calling each service function as defined with some default values



Input formats (hash values or files are given as default depending on options):

  -i, --ipaddr  input are IPv4 addresses (applies to '-r' only)

  -o, --domain  input are domain names (applies to '-r' only)

  -l, --appl    input are hash values for application lookups (applies to '-r' only)

  -u, --url     input are URLs (applies to '-r' and '-s' only)



Supported hash values: MD5, SHA1, SHA-256 and SHA-512.

Copyright © 2017 Diogo A. B. Fernandes.
All rights reserved.

Source: https://github.com/diogo-fernan/