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)
Owner
null
Program to send ROM files to Turbo Everdrive; reverse-engineered and designed to be platform-independent

PCE_TurboEverdrive_USB What is this "TurboEverdrive USB" thing ? For those who have a TurboEverdrive v2.x from krikzz.com, there was originally an opt

David Shadoff 10 Sep 18, 2022
Run unpatched binaries on Nix/NixOS

Run unpatched binaries on Nix/NixOS

Thiago Kenji Okada 160 Jan 8, 2023
Binjago - Set of tools aiding in analysis of stripped Golang binaries with Binary Ninja

Binjago ?? Set of tools aiding in analysis of stripped Golang binaries with Bina

W3ndige 2 Jul 23, 2022
This is an independent project to track Nubank expenses

Nubank expense tracker This is an independent project to track Nubank expenses. To fetch Nubank data we are going to use an unofficial Nubank API, tha

Ramon Gazoni Lacerda 0 Aug 28, 2022
A Linux program to create a Windows USB stick installer from a real Windows DVD or image.

WoeUSB-ng A Linux program to create a Windows USB stick installer from a real Windows DVD or image. This package contains two programs: woeusb: A comm

Longinus 1 Nov 19, 2021
Speed up your typing by some exercises in the multi-platform(Windows/Ubuntu).

Introduction This project purpose is speed up your typing by some exercises in the multi-platform(Windows/Ubuntu). Build Environment Software Environm

lyfer233 1 Mar 24, 2022
A python script developed to process Windows memory images based on triage type.

Overview A python script developed to process Windows memory images based on triage type. Requirements Python3 Bulk Extractor Volatility2 with Communi

CrowdStrike 245 Nov 24, 2022
An evolutionary multi-agent platform based on mesa and NEAT

An evolutionary multi-agent platform based on mesa and NEAT

Valerio1988 6 Dec 4, 2022
Hook and simulate global keyboard events on Windows and Linux.

keyboard Take full control of your keyboard with this small Python library. Hook global events, register hotkeys, simulate key presses and much more.

BoppreH 3.2k Jan 1, 2023
Python implementation of an automatic parallel parking system in a virtual environment, including path planning, path tracking, and parallel parking

Automatic Parallel Parking: Path Planning, Path Tracking & Control This repository contains a python implementation of an automatic parallel parking s

null 134 Jan 9, 2023
creates a batch file that uses adb to auto-install apks into the Windows Subsystem for Android and registers it as the default application to open apks.

wsa-apktool creates a batch file that uses adb to auto-install apks into the Windows Subsystem for Android and registers it as the default application

Aditya Vikram 3 Apr 5, 2022
A browser login credentials thief for windows and Linux

Thief ???? A browser login credentials thief for windows and Linux Python script to decrypt login credentials from browsers in windows or linux Decryp

Ash 1 Dec 13, 2021
Generates Windows 95 and 95 OEM keys using the modulus 7 check algorithm

w95keygen-python windowskeygen.py - Generates Windows 95 and 95 OEM keys using the modulus 7 check algorithm Just download and drop in the directory y

Joshua Alto 1 Dec 6, 2021
A parser of Windows Defender's DetectionHistory forensic artifact, containing substantial info about quarantined files and executables.

A parser of Windows Defender's DetectionHistory forensic artifact, containing substantial info about quarantined files and executables.

Jordan Klepser 101 Oct 30, 2022
An unofficial opensource Pokemon cursor theme for Windows and Linux.

pokemon-cursor An unofficial opensource Pokemon cursor theme for Windows and Linux. Cursor Sizes 22 24 28 32 40 48 56 64 72 80 88 96 Colors Quick inst

Kaiz Khatri 72 Dec 26, 2022
Automatic certificate unpinning for Android apps

What is this? Script used to perform automatic certificate unpinning of an APK by adding a custom network security configuration that permits user-add

Antoine Neuenschwander 5 Jul 28, 2021
Python script which allows for automatic registration in Golfbox

Python script which allows for automatic registration in Golfbox

Guðni Þór Bjârnsson 8 Dec 4, 2021
A C-like hardware description language (HDL) adding high level synthesis(HLS)-like automatic pipelining as a language construct/compiler feature.

β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•”β•β•β•β•β• β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆ

Julian Kemmerer 391 Jan 1, 2023
LINUX-AOS (Automatic Optimization System)

LINUX-AOS (Automatic Optimization System)

null 1 Jul 12, 2022