Malwoverview

  Copyright (C)  2018-2026 Alexandre Borges (https://exploitreversing.com)

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  See GNU Public License on <http://www.gnu.org/licenses/>.

Current Version: 8.0.5 (Codename: Revolutions)

 Important note:  Malwoverview does NOT submit samples to any endpoint by default, 
 so it respects possible Non-Disclosure Agreements (NDAs). There're specific options
 that explicitly submit samples, but these options are explained in the help.

ABOUT

Malwoverview.py is a first response tool for threat hunting, which performs an initial and quick triage of malware samples, URLs, IP addresses, domains, malware families, IOCs and hashes. Additionally, Malwoverview is able to get dynamic and static behavior reports, submit and download samples from several endpoints. In few words, it works as a client to main existing sandboxes.

This tool aims to :

1. Determine similar executable malware samples (PE/PE+) according to the import table (imphash) and group them by different colors (pay attention to the second column from output). Thus, colors matter!
2. Show hash information on Virus Total, Hybrid Analysis, Malshare, Polyswarm, URLhaus, Alien Vault, Malpedia and ThreatCrowd engines.
3. Determining whether the malware samples contain overlay and, if you want, extract it.
4. Check suspect files on Virus Total, Hybrid Analysis and Polyswarm.
5. Check URLs on Virus Total, Malshare, Polyswarm, URLhaus engines and Alien Vault.
6. Download malware samples from Hybrid Analysis, Malshare, URLHaus, Polyswarm and Malpedia engines.
7. Submit malware samples to VirusTotal, Hybrid Analysis and Polyswarm.
8. List last suspected URLs from URLHaus.
9. List last payloads from URLHaus.
10. Search for specific payloads on the Malshare.
11. Search for similar payloads (PE32/PE32+) on Polyswarm engine.
12. Classify all files in a directory searching information on Virus Total and Hybrid Analysis.
13. Make reports about a suspect domain using different engines such as VirusTotal, Malpedia and ThreatCrowd.
14. Check APK packages directly from Android devices against Hybrid Analysis and Virus Total.
15. Submit APK packages directly from Android devices to Hybrid Analysis and Virus Total.
16. Show URLs related to an user provided tag from URLHaus.
17. Show payloads related to a tag (signature) from URLHaus.
18. Show information about an IP address from Virus Total, Alien Vault, Malpedia and ThreatCrowd.
19. Show IP address, domain and URL information from Polyswarm.
20. Perform meta-search on Polyswarm Network using several criteria: imphash, IPv4, domain, URL and malware family.
21. Gather threat hunting information from AlienVault using different criteria.
22. Gather threat hunting information from Malpedia using different criteria.
23. Gather threat hunting information from Malware Bazaar using different criteria.
24. Gather IOC information from ThreatFox using different criteria.
25. Gather threat hunting information from Triage using different criteria.
26. Get evaluation to hashes from a given file against Virus Total.
27. Submit large files (>= 32 MB) to Virus Total.
28. Malwoverview uses Virus Total API v.3, so there isn't longer any option using v.2.
29. Retrieve information about a given IP address from IPInfo service.
30. Retrieve information about a given IP address from BGPView service.
31. Retrieve combined information about a given IP address from multiple services.
32. Offer extra option to save any downloaded file to a central location.
33. List and search vulnerabilities from NIST through different criterias.
34. Query VulnCheck database - Community/Free tier.
35. Gather threat hunting information from Shodan using different criteria.
36. Check IP reputation from AbuseIPDB.
37. Check IP classification from GreyNoise (community API).
38. Perform domain and IP Whois/RDAP lookups.
39. Cross-service hash correlation across VirusTotal, Hybrid Analysis, Triage, and AlienVault.
40. Batch hash check against Malware Bazaar from a file containing hashes.
41. Batch hash check against Hybrid Analysis from a file containing hashes.
42. Batch hash check against Triage from a file containing hashes.
43. Directory scan against Malware Bazaar, Hybrid Analysis, and Triage.
44. Extract IOCs (hashes, IPs, URLs, domains, CVEs) from text files.
45. Scan files or directories with YARA rules.
46. Interactive REPL mode for continuous threat hunting sessions.
47. JSON and CSV structured output formats.
48. Result caching with configurable TTL (SQLite-based).
49. HTTP/HTTPS/SOCKS5 proxy support for all API requests.
50. MITRE ATT&CK technique mapping for behavior reports.
51. TUI (Text User Interface) dashboard mode with panel-based navigation.
52. Gather threat hunting information from URLScan.io — submit URLs, retrieve scan results, and search scans.
53. LLM-powered threat enrichment — AI-generated risk assessment, MITRE ATT&CK mapping, and analyst recommendations appended to any query result. Supports Claude, Gemini, OpenAI, and Ollama (local).
54. Batch IP check against VirusTotal from a file containing IP addresses, showing a summary table (IP Address, Country, AS Owner, Detection).

CONTRIBUTORS

  Alexandre Borges (https://github.com/alexandreborges) | project owner and main developer
  Artur Marzano (https://github.com/Macmod) | co-main developer
  Corey Forman (https://github.com/digitalsleuth) | responsible for REMnux integration
  Christian Clauss (https://github.com/cclauss)

HOW TO CONTRIBUTE TO THIS PROJECT

Since version 6.0.0, there is a new branch named "dev". All contributions and proposals must be done into this "dev" branch.

Professionals who want to contribute must open an issue explaining your proposed improvement and how it would make the project better. Once it has been accepted, so she/he is authorized to submit the PR, which will be tested.

Once all changes are tested, this new version of Malwoverview is replicated to the master branch and a new Python package is generated.

INSTALLATION

This tool has been tested on REMnux, Ubuntu, Kali Linux, macOS and Windows. Malwoverview can be installed by executing the following command:

  * pip3.11 install git+https://github.com/alexandreborges/malwoverview

  or...

  * python -m pip install -U malwoverview

If you want to install the Malwoverview on macOS, you have to execute the following commands:

  * /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  * brew install libmagic
  * pip3 install urllib3==1.26.6
  * pip3 install -U malwoverview
  * Add Python binary directory to the PATH variable by editing .bash_profile file in your home 
    directory. Example:

      export PATH=$PATH:/Users/alexandreborges/Library/Python/3.9/bin

  * Execute: . ./.bash_profile

If you are installing Malwoverview on Windows, make sure that the following conditions are true
AFTER having installed Malwoverview:

  * python-magic is NOT installed. (pip show python-magic)
  * python-magic-bin IS installed. (pip show python-magic-bin)

Note: It is recommended to save the .malwapi.conf before any update!

Optional Features

Some features require optional dependencies. Install them as needed:

  * YARA scanning:       pip install malwoverview[yara]
  * PDF report export:   pip install malwoverview[pdf]
  * TUI dashboard:       pip install malwoverview[tui]
  * All optional:        pip install malwoverview[all]

REQUIRED APIs

It is possible to start using Malwoverview does without inserting all APIs. However, to use all options of Malwoverview, you must insert the respective API of the following services: VirusTotal, Hybrid Analysis, URLHaus, Malshare, Polyswarm, Alien Vault, Malpedia, Triage, IPInfo, Malware Bazaar, ThreatFox, VulnCheck, Shodan, AbuseIPDB, GreyNoise and URLScan.io into the .malwapi.conf configuration file, which must be present (or created) in the home directory (/home/[username] or /root on Linux, and C:\Users[username] on Windows. Alternatively, users can create a custom configuration file and indicate it by using the -c option.

To highlight: if the .malwapi.conf file does not exist in your home directory, so you must create it!

• A special note about the Alien Vault: it is necessary to subscribe to pulses on Alien Vault website before using -n 1 option.

The .malwapi.conf configuration file has the following format:

  [VIRUSTOTAL]
  VTAPI =

  [HYBRID-ANALYSIS]
  HAAPI =

  [MALSHARE]
  MALSHAREAPI =

  [HAUSSUBMIT]
  HAUSSUBMITAPI =

  [POLYSWARM]
  POLYAPI =

  [ALIENVAULT]
  ALIENAPI =

  [MALPEDIA]
  MALPEDIAAPI =

  [TRIAGE]
  TRIAGEAPI =

  [IPINFO]
  IPINFOAPI =

  [BAZAAR]
  BAZAARAPI =

  [THREATFOX]
  THREATFOXAPI =

  [VULNCHECK]
  VULNCHECKAPI =

  [URLHAUS]
  URLHAUSAPI =

  [SHODAN]
  SHODANAPI =

  [ABUSEIPDB]
  ABUSEIPDBAPI =

  [GREYNOISE]
  GREYNOISEAPI =

  [URLSCANIO]
  URLSCANIOAPI =

  [LLM]
  PROVIDER = claude
  CLAUDE_API_KEY =
  CLAUDE_MODEL = claude-opus-4-8
  GEMINI_API_KEY =
  OPENAI_API_KEY =
  OPENAI_MODEL = gpt-4o-mini
  OLLAMA_URL = http://localhost:11434
  OLLAMA_MODEL = llama3.1

The APIs can be requested on the respective service websites:

1. Virus Total (community and paid API): https://www.virustotal.com/gui/join-us
2. Hybrid Analysis: https://www.hybrid-analysis.com/signup
3. Malshare: https://malshare.com/doc.php
4. URLHaus: https://urlhaus.abuse.ch/api/#account
5. Polyswarm: https://docs.polyswarm.io/consumers
6. Alien Vault: https://otx.alienvault.com/api
7. Malpedia: It doesn't offer open registration, but you can request an user account directly through Twitter (DM) or feedback e-email. The Malpedia Twitter handle is @malpedia.
8. Malware Bazaar: https://bazaar.abuse.ch/api/#auth_key
9. ThreatFox: https://threatfox.abuse.ch/api/#auth_key
10. Triage: https://tria.ge/signup.
11. IPInfo: https://ipinfo.io/
12. VulnCheck: https://vulncheck.com/signin (Community/Free tier available)
13. BGPView: https://bgpview.docs.apiary.io/
14. Shodan: https://account.shodan.io/registe