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)
Translation patch for Hololive ERROR

Translation patch for Hololive ERROR How do I install the patch? Grab the Translation.zip file for the latest version from the releases page, and unzi

18 Jul 20, 2022
APC Power Usage is an application which shows power consuption overtime for UPS units manufactured by APC.

APC Power Usage Introduction APC Power Usage is an application which shows power consuption overtime for UPS units manufactured by APC. Screenshoots G

Stefan Kondinski 3 Oct 08, 2021
Svg-turtle - Use the Python turtle to write SVG files

SaVaGe Turtle Use the Python turtle to write SVG files If you're using the Pytho

Don Kirkby 7 Dec 21, 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
Helps to arrange nodes

Relax brush for nodes, helps to arrange nodes easier.

336 Dec 15, 2022
Easy Alias's for bash

easy-alias Easy Alias's for bash Setup Your system needs to have 'echo' which every 21st century computer has You dont need any python requirments but

Hashm 2 Jan 18, 2022
Poetry plugin to bundle projects into various formats

Poetry bundle plugin This package is a plugin that allows the bundling of Poetry projects into various formats. Installation The easiest way to instal

Poetry 54 Jan 02, 2023
Hopefully it'll become a very annoying desktop pet

AnnoyingPet Basic Tutorial: https://seebass22.github.io/python-desktop-pet-tutorial/ Handling Mouse Input: https://pythonhosted.org/pynput/mouse.html

1 Jun 08, 2022
For my Philips Airpurifier AC3259/10

Philips-Airpurifier For my Philips Airpurifier AC3259/10 I will try to keep this code

AcidSleeper 7 Feb 26, 2022
プレヤフHackUチーム「キャット・タン」が作成したアプリ「illustection」

cat_tongue_illustection プレヤフHackUチーム「キャット・タン」が作成した, プライバシー保護アプリ「illustection」です! デモ動画 https://youtu.be/z3I7LuB_i58 機能 アップロードされた画像をいい感じのイラストやの素材に置き換える(

4 Jul 03, 2021
A Python wrapper for Matrix Synapse admin API

Synapse-admin-api-python A Python wrapper for Matrix Synapse admin API. Versioning This library now supports up to Synapse 1.45.0, any Admin API intro

Knugi 9 Sep 28, 2022
Projeto job insights - Projeto avaliativo da Trybe do Bloco 32: Introdução à Python

Termos e acordos Ao iniciar este projeto, você concorda com as diretrizes do Código de Ética e Conduta e do Manual da Pessoa Estudante da Trybe. Boas

Lucas Muffato 1 Dec 09, 2021
Demo content - Automate your automation!

Automate-AAP2 Demo Content - Automate your automation! A fully automated Ansible Automation Platform. Context Installing and configuring Ansible Autom

0 Oct 27, 2022
CalHacks 8 Repo: Megha Jain, Gaurav Bhatnagar, Howard Meng, Vibha Tantry

CalHacks8 CalHacks 8 Repo: Megha Jain, Gaurav Bhatnagar, Howard Meng, Vibha Tantry Setup FE Install React Native via Expo, run App.js. Backend Create

0 Aug 20, 2022
Used the pyautogui library to automate some processes on the computer

Pyautogui Utilizei a biblioteca pyautogui para automatizar alguns processos no c

Dheovani Xavier 1 Dec 30, 2021
Insights in greek football league 2020-2021 and bookmaker's accuracy

Greek_Football_League_Analysis_2020_2021 Aim of Project: This project aims in deriving useful insights from greek football league 2020-2021 by mean st

2 Jan 16, 2022
TikTok Auto Claimer Made By Aim low!#9999 Leaked By bazooka#0001

Zues Auto Claimer Leaked By bazooka#0001 put proxies in prox.txt put ssid in sid.txt put all users you want to target in user.txt for the login just t

1 Jan 14, 2022
Integration of CCURE access control system with automation HVAC of a commercial building

API-CCURE-Automation-Quantity-Floor Integration of CCURE access control system with automation HVAC of a commercial building CCURE is an access contro

Alexandre Edson Silva Pereira 1 Nov 24, 2021
Clackety Keyboards Powered by Python

KMK: Clackety Keyboards Powered by Python KMK is a feature-rich and beginner-friendly firmware for computer keyboards written and configured in Circui

KMK Firmware 780 Jan 03, 2023
A python script that fetches the grades of a student from a WAEC result in pdf format.

About waec-result-analyzer A python script that fetches the grades of a student from a WAEC result in pdf format. Built for federal government college

Oshodi Kolapo 2 Dec 04, 2021