Teach you a binary exploitation for great good.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bintut
miscbin
playground
scripts
sources
tests
try
.gitignore
CHANGELOG.rst
LICENSE.txt
MANIFEST.in
README.rst
SConstruct
bintut.py
make.cmd
requirements.txt
setup.cfg
setup.py

README.rst

BinTut

Dynamic or live demonstration of classical exploitation techniques of typical memory corruption vulnerabilities, from debugging to payload generation and exploitation, for educational purposes 😋.

Official Mirrors

What's BinTut

BinTut is a set of tutorials, as well as exercises.

Tutorials

See Get Started for usage information.

If you are a fan of Faiz, Burst Mode or Single Mode should sound familiar and inspiring.

Burst Mode

Watch and replay to obtain general understanding of the process.

Use -b / --burst to control the interval (in seconds). Note that -b0 means Single Mode, which is the default.

Single Mode

Play and examine various contents such as the stack, registers or memory addresses, carefully and step by step, to acquire comprehensive and detailed knowledge of the process.

Use Enter or Ctrl + D to step.

You can execute normal GDB commands via the promt. But note that BinTut won't synchronize the display when you execute state-changing commands, e.g. stepi or nexti, which are discouraged for the time being.

Another bad news is that readline does not work 😱, and I can't figure out the reason 😱.

Exercises

Write exploits that work outside debuggers when you understand the principles and techniques via watching and replaying (i.e. rewatching), careful playing (i.e., Single Mode), and most importantly, reading the source code responsible for exploit generation, which resides in a file named exploits.py.

Installation

Notice

If pip is used to install BinTut, make sure that you use the pip version corresponding to the Python version shipped with GDB. For more details, see #1.

pip install bintut may or may not work for the time being.

Therefore it's recommended to just clone this repository and run without installation as long as necessary libraries are installed by pip install -r requirements.txt.

Warning

BinTut does not work inside virtualenv at present.

Tested Platforms

Arch GNU/Linux

Current version of Arch GNU/Linux ships GDB with Python 3, in which I developed BinTut.

The latest release version should work fine.

  • Install lib32-glibc

    sudo pacman -S lib32-glibc
    
  • Install Python 3 and pip3.

    sudo pacman -S python python-pip
    
  • Install BinTut using pip3

    sudo pip3 install bintut
    
  • You are ready!

    bintut -b0.1 jmp-esp
    

Fedora GNU/Linux

The latest Fedora Workstation comes with GDB with Python 3, which has been tested and BinTut is known to work properly as in Arch GNU/Linux.

  • Install glibc.i686 to support 32-bit programs if needed.

    sudo dnf install glibc.i686
    
  • Install BinTut from PyPI.

    sudo pip3 install bintut
    
  • Give it a try.

    bintut -b0.1 frame-faking
    

Debian GNU/Linux

GDB from the stable branch of Debian GNU/Linux ships with Python 2.

Latest source from Git works with minor problems.

  • Add support to 32-bit programs if necessary.

    sudo dpkg --add-architecture i386
    sudo apt-get update
    sudo apt-get install libc6:i386
    
  • Clone the latest source code from Git and install requirements.

    git clone https://github.com/NoviceLive/bintut.git
    cd bintut
    sudo apt-get install python-pip gdb
    pip2 install -r requirements.txt
    
  • Run it without installation.

    python2 ./bintut.py -b0.1 frame-faking
    

Kali GNU/Linux

GDB from the latest rolling version of Kali GNU/Linux ships with Python 3.

  • Enable i386 support according to aforementioned instructions.

  • Install pip3

    apt-get install python3-pip
    
  • Install the latest BinTut release using pip3

    pip3 install bintut
    
  • Start hacking!

    bintut -b0.1 jmp-esp
    

Requirements

GDB

Python scripting support is required.

BinTut is developed with Python 3, but it's intended to be Python 2 compatible.

Therefore, when Python 2 yells at you, feel free to create an issue or send me a pull request.

Known unresolved issues existing on Python 2
  • Can't display disassembly after returning to shellcode.
  • Can't print the payload for some courses.

Ropper

Show information about binary files and find gadgets to build rop chains for different architectures.

pyelftools

Python library for analyzing ELF files and DWARF debugging information.

Pat

Customizable Lazy Exploit Pattern Utility.

Colorama

Simple cross-platform colored terminal text in Python.

Click

Python composable command line utility.

Get Started

See bintut --help and give it a shot via bintut --burst 0.1 frame-faking.

./bintut.py --help
Usage: bintut.py [OPTIONS] [COURSE]

  Teach You A Binary Exploitation For Great Good.

Options:
  -V, --version      Show the version and exit.
  -l, --list         List available courses.
  -6, --x64          Use x64 courses.
  -A, --aslr         Enable ASLR.
  -b, --burst FLOAT  Use this burst mode interval.  [default: 0]
  -v, --verbose      Be verbose.
  -q, --quiet        Be quiet.
  -h, --help         Show this message and exit.

Available Courses

Other courses might be added later.

Stack-based buffer overflow

1. plain

Return to plain shellcode.

Linux x86 / x64.

NX: Disabled.

ASLR: Disabled.

Stack Protector: Disabled.

2. nop-slide

Return to NOPs plus shellcode.

Linux x86 / x64.

NX: Disabled.

ASLR: Disabled.

Stack Protector: Disabled.

This course is not demonstrative enough and shall be updated when the author finds a scenario where nop-slide really stands out.

3. jmp-esp

Return to shellcode via JMP ESP / RSP.

Linux x86 / x64.

NX: Disabled.

ASLR: Disabled.

Stack Protector: Disabled.

4. off-by-one NULL

Variant of plain stack-based buffer overflow.

Linux x86 / x64.

NX: Disabled.

ASLR: Disabled.

Stack Protector: Disabled.

5. ret2lib

Return to functions.

Linux x86.

NX: Enabled.

ASLR: Disabled.

Stack Protector: Disabled.

Notes for x64

Either on Linux or Windows, the ABI of x64, unlike that of x86, passes some arguments, first six or four integral arguments on Linux or Windows respectively, via registers, which may not be controlled without resort to certain gadgets.

Therefore, it may be discussed in the section for ROP.

6. frame-faking

Return to chained functions via LEAVE RET gadget.

Linux x86.

NX: Enabled.

ASLR: Disabled.

Stack Protector: Disabled.

Notes for x64

See Notes for x64.

Bug Reports

Create issues.

BinTut might or might not work on your system, but bug reports with necessary information are always welcome.

Tips

Remember to include bintut --version in your report.

You can just submit the verbose log (stderr) if out of words, e.g., bintut -v -b0.1 frame-faking 2>log.txt.

TODO List & You Can Contribute

  • Improve the code if you find something that can be done better.

    The codebase of BinTut can always be improved by those who have a deeper understanding of Python than the author.

    Also, there are hardcoded behaviors which can be generalized.

  • Change color scheme to red highlight when content changes.

    Currently, our color scheme remains unchanged, in predefined colors, which is just not eye-catching or obvious when we want to observe some significant changes in certain registers or specific memory locations.

    Here is an example of such change, the least-significant-byte of saved EBP / RBP being cleared due to an off-by-one NULL write.

    Ref. That's what you will expect in OllyDbg and probably many other debuggers will also behave in this manner.

    Ref. Some GDB enhancement projects have already implemented this.

  • Synchronize the display when executing state-changing commands.

  • Add course variants that does not allow NULL bytes.

    For example, add variant courses using strcpy instead of fread to trigger overflow, in order to demonstrate the techniques to survive in severe environments, which happen to be the case of our real world.

  • Use a better combination of chained functions for frame-faking.

    What follows is the current choice.

    Yes, two consecutive /bin/sh and exit.

    elif post == 'frame-faking':
        payload = (
            Faked(offset=offset, address=addr) +
            Faked(b'system', ['/bin/sh']) +
            Faked(b'execl', ['/bin/sh', '/bin/sh', 0]) +
            Faked(b'exit', [0]))
    
  • Support demonstration on Windows and MacOS.

References