Automatic and platform-independent unpacker for Windows binaries based on emulation

Overview
 _   _         __  _  __                    _
| | | |       / / (_) \ \                  | |
| | | |_ __  | |   _   | | _ __   __ _  ___| | _____ _ __
| | | | '_ \/ /   | |   \ \ '_ \ / _` |/ __| |/ / _ \ '__|
| |_| | | | \ \   | |   / / |_) | (_| | (__|   <  __/ |
 \___/|_| |_|| |  |_|  | || .__/ \__,_|\___|_|\_\___|_|
              \_\     /_/ | |
                          |_|

Un{i}packer PyPI: unipacker Docker Cloud Build Status DOI

Master Build Status
Dev Build Status

Unpacking PE files using Unicorn Engine

The usage of runtime packers by malware authors is very common, as it is a technique that helps to hinder analysis. Furthermore, packers are a challenge for antivirus products, as they make it impossible to identify malware by signatures or hashes alone.

In order to be able to analyze a packed malware sample, it is often required to unpack the binary. Usually this means, that the analyst will have to manually unpack the binary by using dynamic analysis techniques (Tools: OllyDbg, x64Dbg). There are also some approaches for automatic unpacking, but they are all only available for Windows. Therefore when targeting a packed Windows malware the analyst will require a Windows machine. The goal of our project is to enable platform independent automatic unpacking by using emulation that yields runnable Windows binaries.

Fully supported packers

  • ASPack: Advanced commercial packer with a high compression ratio
  • FSG: Freeware, fast to unpack
  • MEW: Specifically designed for small binaries
  • MPRESS: Free, more complex packer
  • PEtite: Freeware packer, similar to ASPack
  • UPX: Cross-platform, open source packer
  • YZPack

Other packers

Any other packers should work as well, as long as the needed API functions are implemented in Un{i}packer. For packers that aren't specifically known you will be asked whether you would like to manually specify the start and end addresses for emulation. If you would like to start at the entry point declared in the PE header and just emulate until section hopping is detected, press Enter

Showcase

We are humbled to see some active usage of Un{i}packer for research projects and university courses that teach students about malware obfuscation:

  • Tutorial video belonging to the Master's course "Malware Analysis and Cyber Threat Intelligence" at the Westphalian University, demonstrating how to analyze obfuscated malware with Un{i}packer
  • DeepReflect: Paper presenting a tool for localizing and identifying malware components within a malicious binary. Its dataset relies on a Un{i}packer preprocessing step
  • BDHunter: Paper describing a system that automatically identifies behavior dispatchers to assist triggering malicious behaviors. The tool requires unpacked malware samples as input, where the authors propose using Un{i}packer
  • JARV1S Disassembler: Disassembler that uses Un{i}packer as a preprocessing step
  • Anti-Anti-Virus 2 lecture of University of Virginia's "CS 4630: Defense Against the Dark Arts", using Un{i}packer as an example for unpacking techniques

If you are using Un{i}packer for additional projects and would like them featured in this list, we would love to hear from you!

Usage

Normal installation

Install the YARA package for your OS, get Un{i}packer from PyPi and start it using the automatically created command line wrapper:

pip3 install unipacker
unipacker

For detailed instructions on how to use Un{i}packer please refer to the Wiki. Additionally, all of the shell commands are documented. To access this information, use the help command

You can take a quick look at Un{i}packer in action in a (german) video by Prof. Chris Dietrich

Development mode installation

Clone the repository, and inside the project root folder activate development mode using pip3 install -e .

Using Docker

You can also use the provided Dockerfile to run a containerized version of Un{i}packer:

docker run -it -v ~/local_samples:/root/unipacker/local_samples vfsrfs/unipacker

Assuming you have a folder called local_samples in your home directory, this will be mounted inside the container. Un{i}packer will thus be able to access those binaries via /root/unipacker/local_samples

RESTful API

A 3rd party wrapper created by @rpgeeganage allows to unpack samples by sending a request to a RESTful server: https://github.com/rpgeeganage/restful4up

Comments
  • Showing only New Sample option

    Showing only New Sample option

    I have installed Python 3.6 and also installed all requirements. I ran the unpacker with command <python3.6 unipacker.py> I get only one option shown when I start the Unipacker. I give 0 and when asked for path of file I gave relative path to current directory. I get the following output from which I am unable to infer anything. Please tell me what this is and what should be done to make it work properly. unpackerbug

    TIA.

    opened by Bhuvanamitra 11
  • Using unipacker as a package & Parallel Calls

    Using unipacker as a package & Parallel Calls

    Hello, thanks a lot for the great work! There are two minor things that we would love to adjust for integration purpose. It will be great if we can adjust the verbosity of the printing or logging level with log.info/error. Also If we understand the code correctly, the current implmentation always generate unpack.exe and then move the the user supplied dest path. However, this prevents us having parallel runs for unpacking (they always ends up the same file). Could we make it part of the arguments for UnpackerEngine? So far our workaround is:

    dest = file + '_unipacker'
    def _dump(_self, uc, apicall_handler, sample, path=dest):
      _self.dumper.dump_image(uc, _self.BASE_ADDR, _self.virtualmemorysize, apicall_handler, sample, path)
    
    uni_sample.dump = _dump
    
    

    Again, thanks a lot for the great work!

    opened by steven-hh-ding 7
  • non-unique brokenimport.exe & other pefile calls

    non-unique brokenimport.exe & other pefile calls

    📑 Summary:

    1/ brokenimport.exe were reused across runs so I changed it to depend on the dest path (output file path) 2/ fixed other pefile calls that locks file handles

    Issues not fixed (need some discussions): brokenimport.exe files are not completely cleaned up after runs (some return before os.remove). Is it a temporary file? If so we can make pe_write under a context manager:

    
    @contextmanager
    def pe_write(uc, base_addr, total_size, filename, clean_up=False):
        try:
            data = uc.mem_read(base_addr, total_size)
            with open(filename, 'wb+') as f:
                f.write(data)
            yield filename
        finally:
            if clean_up and os.exists(filename):
                os.remove(filename)
    
    

    (part of #44 )

    opened by steven-hh-ding 5
  • Error in file shell.py

    Error in file shell.py

    I have error in file shell.py (line 251, print_imports). Really file has no imports, only sections UPX0, UPX1 and .rsrsc. Die reports that it is packed with UPX 3.03[NRV,best].

    opened by crypto2011 4
  • install fails on Windows 7

    install fails on Windows 7

    Hello! Seems like I am following installation instructions to the letter, but install still fails with this error: ERROR: Command "'c:\program files (x86)\python37-32\python.exe' -u -c 'import setuptools, tokenize;file='"'"'D:\cygwin64\tmp\pip-install-wb408v9s\unicorn-unipacker\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(file);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, file, '"'"'exec'"'"'))' install --record 'D:\cygwin64\tmp\pip-record-t15lv_bc\install-record.txt' --single-version-externally-managed --compile" failed with error code 1 in D:\cygwin64\tmp\pip-install-wb408v9s\unicorn-unipacker\

    Could somebody please help? Thanks in advance!

    opened by PavelKotov1 4
  • Invalid syntax in unipacker.py Line 73

    Invalid syntax in unipacker.py Line 73

    When I run unipacker.py, I get Invalid Syntax Error in this line.

    Line 73: ("End of unpacking stub:", f"0x{endaddr:02x}" if endaddr != sys.maxsize else "unknown"),

    opened by Bhuvanamitra 4
  • RESTful API for Unipacker

    RESTful API for Unipacker

    Hi, this is not about an issue. I came to know about this wonderful project while I was looking into malware unpackers. So, I wrote a RESTful API interface for your project using Docker. This is my repo: https://github.com/rpgeeganage/restful4up I hope it will help this awesome project.

    opened by rpgeeganage 3
  • AttributeError: 'Shell' object has no attribute 'shell_event'

    AttributeError: 'Shell' object has no attribute 'shell_event'

    Hi,

    I am going to use your software to uncompress the upx file. But this error is received:

    Enter the option ID: 0 Please enter the sample path (single file or directory): /usr/bin/uname.upx e_magic = 17791 Wrong DOS Magic Value (MZ). Aborting... Could not initialize /usr/bin/uname.upx: Traceback (most recent call last): File "/usr/local/bin/unipacker", line 11, in <module> sys.exit(main()) File "/usr/local/lib/python3.6/site-packages/unipacker/shell.py", line 742, in main Shell() File "/usr/local/lib/python3.6/site-packages/unipacker/shell.py", line 82, in __init__ self.shell_event.wait() AttributeError: 'Shell' object has no attribute 'shell_event'

    what is the reason?

    Thank you.

    opened by esmailzadeh1 3
  • Allow developers to specify the path of a YARA rules file

    Allow developers to specify the path of a YARA rules file

    Simple change to allow developers to specify the path of a YARA rules file (or even includes).

    from unipacker.core import Sample
    sample = Sample(pe, yara_path='/path/to/another/packer_signatures.yar')
    

    Bonus: improvement to MEW packer rules as it will avoid PEs to be identified as packed if they have the MEW string inside the binary.

    opened by lubiedo 1
  • init_uc can take a long time

    init_uc can take a long time

    Hello!

    https://github.com/unipacker/unipacker/blob/37724cc8323b06fbe3f0864a8954704b2a2e1c4a/unipacker/core.py#L152-L155

    In our test, init_uc can take a really long time for certain file that is intentionally made large e.g. https://bazaar.abuse.ch/sample/c92af6007b3c7f48e9c18d73dd99d889dd08dbccfe12c346724a149ba483ec2c/

    So we can't set timeout on this function. Can we move the call for init_uc to engine.emu ?

    opened by steven-hh-ding 1
  • |ERROR| Invalid command 'Sj' (0x53)

    |ERROR| Invalid command 'Sj' (0x53)

    using radare2 commit: 3cde905a209a39fbc88ba03557705fb5467aff6e build: 2019-02-19__12:15:40 using r2pipe (1.2.0) in order to be able to run your script I had to modify "Sj" to "iSj". (it seems that iSj is for rabin)

    opened by garanews 1
  • Errors trying to run the command

    Errors trying to run the command

    Traceback (most recent call last): File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main return run_code(code, main_globals, None, File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in run_code exec(code, run_globals) File "C:\Users\Source\AppData\Local\Programs\Python\Python310\Scripts\unipacker.exe_main.py", line 4, in File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\site-packages\unipacker\shell.py", line 13, in from cmd2 import Cmd File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\site-packages\cmd2_init.py", line 13, in from .cmd2 import Cmd, Statement, EmptyStatement, categorize File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\site-packages\cmd2\cmd2.py", line 48, in from . import utils File "C:\Users\Source\AppData\Local\Programs\Python\Python310\lib\site-packages\cmd2\utils.py", line 73, in default_values: collections.Iterable = ()): AttributeError: module 'collections' has no attribute 'Iterable'

    opened by SSources 1
  • it shows only these for any exe

    it shows only these for any exe

    I install it without any errors but now it shows these with test by any exe Python39>unipacker v1.0.3

    Your options for today:

        [0]  New sample...
    

    Enter the option ID: 0 Please enter the sample path (single file or directory): 1.exe OPT Magic: 523 Wrong Optional Header Magic. Aborting... Could not initialize 1.exe: Traceback (most recent call last): File "c:\users\administrator\appdata\local\programs\python\python39\lib\runpy.py", line 197, in _run_module_as_main return _run_code(code, main_globals, None, File "c:\users\administrator\appdata\local\programs\python\python39\lib\runpy.py", line 87, in run_code exec(code, run_globals) File "C:\Users\Administrator\AppData\Local\Programs\Python\Python39\Scripts\unipacker.exe_main.py", line 7, in File "c:\users\administrator\appdata\local\programs\python\python39\lib\site-packages\unipacker\shell.py", line 738, in main Shell() File "c:\users\administrator\appdata\local\programs\python\python39\lib\site-packages\unipacker\shell.py", line 82, in init self.shell_event.wait() AttributeError: 'Shell' object has no attribute 'shell_event'

    anybody can help?

    opened by Mafhoom 2
  • Error while dumping

    Error while dumping

    I have error while dumping UPX-file. image_dump.py (line 208, fix_imports_by_rebuilding->line 170, find_iat): IndexError in lx = possible_ptrs[-1]. Before dumping I had some errors like raiseUcError(status) Invalid memory write (UC_ERR_WRITE_UNMAPPED) after message GetProcAddress:..... accept Unfortunately I cannot place trace log here.

    opened by crypto2011 7
Releases(1.0.6)
Free components that wrap up Python into Delphi and Lazarus (FPC)

Python for Delphi (P4D) is a set of free components that wrap up the Python DLL into Delphi and Lazarus (FPC). They let you easily execute Python scri

747 Jan 02, 2023
🚀 emojimash 🚀 is a programming language with ALL THE EMOJI

🚀 emojimash 🚀 is a programming language with ALL THE EMOJI

Python Whiz 256 1 Oct 26, 2021
Emulate and Dissect MSF and *other* attacks

Need help in analyzing Windows shellcode or attack coming from Metasploit Framework or Cobalt Strike (or may be also other malicious or obfuscated code)? Do you need to automate tasks with simple scr

123 Dec 16, 2022
Viewer for NFO files

NFO Viewer NFO Viewer is a simple viewer for NFO files, which are "ASCII" art in the CP437 codepage. The advantages of using NFO Viewer instead of a t

Osmo Salomaa 114 Dec 29, 2022
Dotfiles for my configurations!

Dotfiles Repo Welcome! Over here, you can find my dotfiles for various applications, including QTile, Alacritty, Kitty, LunarVim, and more! Make sure

class PythonAddict 3 Jan 10, 2022
A simple wrapper to analyse and visualise reinforcement learning agents' behaviour in the environment.

Visrl Visrl (pronounced "visceral") is a simple wrapper to analyse and visualise reinforcement learning agents' behaviour in the environment. Reinforc

Jet New 14 Jun 27, 2022
Here, I have discuss the three methods of list reversion. The three methods are built-in method, slicing method and position changing method.

Three-different-method-for-list-reversion Here, I have discuss the three methods of list reversion. The three methods are built-in method, slicing met

Sachin Vinayak Dabhade 4 Sep 24, 2021
An example repository for how to generate results using PyBaMM

PyBaMM results This repository provides a template for generating results (for example, for a paper) using PyBaMM Installation Install PyBaMM using a

PyBaMM Team 7 Oct 09, 2022
CaskDB is a disk-based, embedded, persistent, key-value store based on the Riak's bitcask paper, written in Python.

CaskDB - Disk based Log Structured Hash Table Store CaskDB is a disk-based, embedded, persistent, key-value store based on the Riak's bitcask paper, w

886 Dec 27, 2022
MODeflattener deobfuscates control flow flattened functions obfuscated by OLLVM using Miasm.

MODeflattener deobfuscates control flow flattened functions obfuscated by OLLVM using Miasm.

Suraj Malhotra 138 Jan 07, 2023
A tool converting rpk (记乎) to apkg (Anki Package)

RpkConverter This tool is used to convert rpk file to Anki apkg. 如果遇到任何问题,请发起issue,并描述情况。如果转换rpk出现问题,请将文件发到邮箱 ssqyang [AT] outlook.com,我会debug并修复问题。 下

9 Nov 01, 2021
My collection of mini-projects in various languages

Mini-Projects My collection of mini-projects in various languages About: This repository consists of a number of small projects. Most of these "mini-p

Siddhant Attavar 1 Jul 11, 2022
LinuxHelper - A collection of utilities for non-technical Linux users accessible via a GUI

Linux Helper A collection of utilities for non-technical Linux users accessible via a GUI This app is still in very early development, expect bugs and

Seth 7 Oct 03, 2022
This program tries to book a tennis court slot in either Southwark Park or Tanner Street Park in Southwark, London.

Book tennis courts in London This program tries to book a tennis court slot in either Southwark Park or Tanner Street Park in Southwark, London. Note:

Daniele 1 Jul 25, 2022
This repository contains Python games that I've worked on. You'll learn how to create python games with AI. I try to focus on creating board games without GUI in Jupyter-notebook.

92_Python_Games 🎮 Introduction 👋 This repository contains Python games that I've worked on. You'll learn how to create python games with AI. I try t

Milaan Parmar / Милан пармар / _米兰 帕尔马 166 Jan 01, 2023
Time python - Códigos para auxiliar e mostrar formas de como fazer um relógio e manipular o seu tempo

Time_python Códigos para auxiliar e mostrar formas de como fazer um relógio e manipular o seu tempo. Bibliotecas Nestes foram usadas bibliotecas nativ

Eduardo Henrique 1 Jan 03, 2022
A Python library that helps data scientists to infer causation rather than observing correlation.

A Python library that helps data scientists to infer causation rather than observing correlation.

QuantumBlack Labs 1.7k Jan 04, 2023
A python script to get your activity

activities A python script to get your activity Not complete Requirements Python (=3.7) Pip (for python = 3.7) Git Pip packages psutil asyncio aioht

StarNumber 3 Nov 07, 2021
A competition for forecasting electricity demand at the country-level using a standard backtesting framework

A competition for forecasting electricity demand at the country-level using a standard backtesting framework

5 Jul 12, 2022
IEEE ITU bunyesinde komitelere verilen Python3 egitiminin dokumanlastirilmis versiyonlari bu repository altinda tutulmaktadir.

IEEE ITU Python Egitimi Nasil Faydalanmaliyim? Dersleri izledikten sonra dokumanlardaki kodlari yorum satirlari isaretlerini kaldirarak deneyebilirsin

İTÜ IEEE Student Branch 47 Sep 04, 2022