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)
The Official interpreter for the Pix programming language.

The official interpreter for the Pix programming language. Pix Pix is a programming language dedicated to readable syntax and usability Q) Is Pix the

Pix 6 Sep 25, 2022
CountdownTimer - Countdown Timer For Python

Countdown Timer This python script asks for the user time (input) in seconds, an

Arinzechukwu Okoye 1 Jan 01, 2022
Contains a Jupyter Notebook for calculating remaining plants required based on field/lathhouse data.

Davis-Sunflowers-Su21 Project goals: Plants influence their reproduction and mating system in many ways. Various factors such as time of flowering, ab

1 Feb 10, 2022
Scraper pour les offres de stage Tesla et les notes sur Oasis (Polytech Paris-Saclay) sous forme de bot Discord

Scraper pour les offres de stage Tesla et les notes sur Oasis (Polytech Paris-Saclay) sous forme de bot Discord

Alexandre Malfreyt 1 Jan 21, 2022
Generic NDJSON importer for hashlookup server

Generic NDJSON importer for hashlookup server Usage usage: hashlookup-json-importer.py [-h] [-v] [-s SOURCE] [-p PARENT] [--parent-meta PARENT_META [P

hashlookup 2 Jan 19, 2022
Fetch data from an excel file and create HTML file

excel-to-html Problem Statement! - Fetch data from excel file and create html file Excel.xlsx file contain the information.in multiple rows that is ne

Vivek Kashyap 1 Oct 25, 2021
decorator

Decorators for Humans The goal of the decorator module is to make it easy to define signature-preserving function decorators and decorator factories.

Michele Simionato 734 Dec 30, 2022
That is a example of a Book app on Python, made with support of all JS libraries on React framework

React+Python Books App You can use this repository whenever you want Used for a video Create the database: python -m dbutils Start the web server: pyt

Koma Human 1 Apr 20, 2022
ALSPAC data analysis studying links between screen-usage and mental health issues in children. Provided data has been synthesised.

ADSMH - Mental Health and Screen Time Group coursework for Applied Data Science at the University of Bristol. Overview The data set that you have was

Kai 1 Jan 13, 2022
🔵Open many google dorks in a fasted way

Dorkinho 🔵 The author is not responsible for misuse of the tool, use it in good practices like Pentest and CTF OSINT challenges. Dorkinho is a script

SidHawks 2 May 02, 2022
Tensorboard plugin 3d with python

tensorboard-plugin-3d Overview In this example, we render a run selector dropdown component. When the user selects a run, it shows a preview of all sc

KitwareMedical 26 Nov 14, 2022
Tie together `drf-spectacular` and `djangorestframework-dataclasses` for easy-to-use apis and openapi schemas.

Speccify Tie together drf-spectacular and djangorestframework-dataclasses for easy-to-use apis and openapi schemas. Usage @dataclass class MyQ

Lyst 4 Sep 26, 2022
python scripts to perform coin die clustering (performed on Riedones3D).

python scripts to perform coin die clustering (performed on Riedones3D).

Sofiane 2 Apr 29, 2022
Use Ghidra Structs in Python

Strudra Welcome to Strudra, a way to craft Ghidra structs in python, using ghidra_bridge. Example First, init Strudra - you can pass in a custom Ghidr

Dominik Maier 27 Nov 24, 2022
Automatização completa do site https://blaze.com

PyBlaze Pyblaze possibilita o acesso a api do site blaze utilizando python, retornando os últimos resultados de crashs e doubles. Agora também é possí

Cleiton Leonel 24 Dec 30, 2022
Architectural Patterns implementation by using notification handler module prototype

This repository covers singleton, indirection, factory, adaptor, mediator patterns in python language by using university hypothetical notification module prototype. The code is just for demonstratin

Muhammad Umair 2 Jan 08, 2022
Some basic sorting algos

Sorting-Algos Some basic sorting algos HacktoberFest 2021 This repository consists of mezzo-level projects that undertake a simple task and perform it

Manthan Ghasadiya 7 Dec 13, 2022
Information about a signed UEFI Shell that can be used when Secure Boot is enabled.

SignedUEFIShell During our research of the BootHole vulnerability last year, we tried to find as many signed bootloaders as we could. We searched all

Mickey 61 Jan 03, 2023
simple password manager.

simple password manager.

1 Nov 18, 2021
Library for managing git hooks

Autohooks Library for managing and writing git hooks in Python. Looking for automatic formatting or linting, e.g., with black and pylint, while creati

Greenbone 165 Dec 16, 2022