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)
Lenovo Yoga Ideapad Autocharge

Description This program uses the conservation_mode of Lonovo Ideapad / Yoga not

1 Jan 09, 2022
My solutions for Advent of Code 2021 🌟🎄

🌟 Advent of Code 2021 🎄 My solutions for Advent of Code 2021. About · What is Advent of Code? · Contents · Usage · Table of puzzles (TODO: add final

Amanda P. Pinha 2 Dec 05, 2022
Python library for converting Python calculations into rendered latex.

Covert art by Joshua Hoiberg handcalcs: Python calculations in Jupyter, as though you wrote them by hand. handcalcs is a library to render Python calc

Connor Ferster 5.1k Jan 07, 2023
How to create the game Rock, Paper, Scissors in Python

Rock, Paper, Scissors! If you want to learn how to do interactive games using Python, then this is great start for you. In this code, You will learn h

SplendidSpidey 1 Dec 18, 2021
Cairo-integer-types - A library for bitwise integer types (e.g. int64 or uint32) in Cairo, with a test suite

The Cairo bitwise integer library (cairo-bitwise-int v0.1.1) The Cairo smart tes

27 Sep 23, 2022
Radiosonde Telemetry Decoders

Radiosonde Telemetry Frame Decoders This repository is an attempt to collate the various sources of information on how to decode radiosonde telemetry

Project Horus 3 Jan 04, 2022
Python Freecell Solver

freecell Python Freecell Solver Very early version right now. You can pick a board by changing the file path in freecell.py If you want to play a game

Ben Kaufman 1 Nov 26, 2021
The purpose is to have a fairly simple python assignment that introduces the basic features and tools of python

This repository contains the code for the python introduction lab. The purpose is to have a fairly simple python assignment that introduces the basic

1 Jan 24, 2022
A python library with various gambling and gaming classes

gamble is a simple library that implements a collection of some common gambling-related classes Features die, dice, d-notation cards, decks, hands pok

Jacobi Petrucciani 16 May 24, 2022
Grouping nucleotide coordinate ranges.

NuclRanger Grouping nucleotide coordinate ranges. A quick pre-processing step for "bedtools getfasta":- https://bedtools.readthedocs.io/en/latest/cont

Sujanavan Tiruvayipati 1 Oct 04, 2022
Python interface to ISLEX, an English IPA pronunciation dictionary with syllable and stress marking.

pysle Questions? Comments? Feedback? Pronounced like 'p' + 'isle'. An interface to a pronunciation dictionary with stress markings (ISLEX - the intern

Tim 38 Dec 14, 2022
because rico hates uuid's

terrible-uuid-lambda because rico hates uuid's sub 200ms response times! Try it out here: https://api.mathisvaneetvelde.com/uuid https://api.mathisvan

Mathis Van Eetvelde 2 Feb 15, 2022
Tucan Discord Token Generator - Remastered

TucanGEN-SRC Tucan Discord Token Generator - Remastered Tucan source made better by me. -- idk if it works anymore Includes: hCaptcha Bypass Automatic

Vast 8 Nov 04, 2022
Collections of python projects

nppy, mostly contains projects written in Python. Some projects are very simple while some are a bit lenghty and difficult(for beginners) Requirements

ghanteyyy 75 Dec 20, 2022
A data driven app for bicycle hiring in London(UK)

bicycle_hiring_app_deployed A data driven app for bicycle hiring in London(UK). It predicts expected number of bicycle hire in London. It asks users t

Rajarshi Roy Raju 1 Dec 10, 2021
【AI创造营】参赛作品

-AI-emmmm 【AI创造营】参赛作品 鬼畜小视频 AiStuido地址:https://aistudio.baidu.com/aistudio/projectdetail/1647685 BiliBili视频地址:https://www.bilibili.com/video/BV1Zv411b

107 Nov 09, 2022
Absolute solvation free energy calculations with OpenFF and OpenMM

ABsolute SOLVantion Free Energy Calculations The absolv framework aims to offer a simple API for computing the change in free energy when transferring

7 Dec 07, 2022
It was created to conveniently respond to events such as donation, follow, and hosting using the Alert Box provided by twip to streamers

This library is not an official library of twip. It was created to conveniently respond to events such as donation, follow, and hosting using the Alert Box provided by twip to streamers.

junah201 8 Nov 19, 2022
Configure request params such as text, color, size etc. And then download the image

Configure request params such as text, color, size etc. And then download the image

6 Aug 18, 2022
Turn crypto miner on/off depending on powerwall charge level

Mining Crypto with Tesla Solar and Powerwalls This script turns a crypto miner on and off when the Tesla Powerwall level drops/rises above a certain t

Matt 1 Nov 09, 2021