VAGD

VirtuAlization GDb integrations in pwntools

Installation

pip install vagd

or from repo with

git clone https://github.com/gfelber/vagd
pip install ./vagd/

Usage

vagd template [OPTIONS] [BINARY] [IP] [PORT] to generate a template, list OPTIONS with help -h

Use --degd (or --docker-api) to generate a template backed by the native Docker API instead of SSH. Degd uses attached Docker exec sockets for target I/O, Docker archive APIs for file transfer, and a localhost-only published port for GDB's connection to gdbserver. The vagd ssh command opens an attached Bash TTY for Degd, while vagd scp transfers files through Docker archives:

from vagd import Degd

vm = Degd(BINARY, image="ubuntu:noble")
t = vm.start(argv=ARGS, env=ENV, gdbscript=GDB)

The initial Degd implementation supports Debian and Ubuntu images. The existing Dogd SSH backend remains available unchanged. The bundled seccomp policy tracks Moby's upstream default and additionally allows personality(ADDR_NO_RANDOMIZE) for debugger-driven ASLR control.

Extra packages and TLS remotes can be included directly when generating a template:

vagd template --degd --package strace --ssl \
  ./binary challenge.example 443

Repeat --package to include more than one value. Capabilities and privileged mode remain available through the cap_add and privileged Python constructor arguments on Docker and Podman backends.

from pwn import *

GOFF   = 0x555555554000                               # GDB default base address
IP     = ''                                           # remote IP
PORT   = 0                                            # remote PORT
BINARY = ''                                           # PATH to local binary
ARGS   = []                                           # ARGS supplied to binary
ENV    = {}                                           # ENV supplied to binary

# GDB SCRIPT, executed at start of GDB session (e.g. set breakpoints here)
GDB    = f"""
set follow-fork-mode parent

c"""

context.binary = exe = ELF(BINARY, checksec=False)    # binary
context.aslr = False                                  # ASLR enabled (only GDB)

vm = None
# setup vagd vm
def setup():
  global vm
  if args.REMOTE or args.LOCAL:
    return

  try:
    # only load vagd if needed
    from vagd import Dogd, Qegd, Box
  except:
    log.error('Failed to import vagd, either run locally using LOCAL or install it')
  if not vm:
    vm = Dogd(BINARY, image=Box.DOCKER_UBUNTU, ex=True, fast=True)  # Docker
    # vm = Qegd(BINARY, img=Box.QEMU_UBUNTU, ex=True, fast=True)  # Qemu
  if vm.is_new:
    # additional setup here
    log.info('new vagd instance')


# get target (pwnlib.tubes.tube)
def get_target(**kw) -> tubes.tube:
  if args.REMOTE:
    # context.log_level = 'debug'
    return remote(IP, PORT)

  if args.LOCAL:
    if args.GDB:
      return gdb.debug([BINARY] + ARGS, env=ENV, gdbscript=GDB, **kw)
    return process([BINARY] + ARGS, env=ENV, **kw)

  return vm.start(argv=ARGS, env=ENV, gdbscript=GDB, **kw)


setup()

#===========================================================
#                   EXPLOIT STARTS HERE
#===========================================================

# libc = ELF('', checksec=False)

t = get_target()

t.interactive() # or it()

vagd info BINARY to print info about binary

# run as process in VM
./exploit.py
# run as gdb server in VM requires tmux
./exploit.py GDB
# run on remote IP:PORT
./exploit.py REMOTE
# run process locally
./exploit.py LOCAL [GDB]

I recommend using pwndbg.

Files

All created files ares stored in the local ./.vagd/ directory. Additional large files (e.g. cloudimages) are stored in the home directory ~/.share/local/vagd/ or handled by tools themselfs (e.g. Docker).

CLI

alias vagd="python -m vagd" # or install with pip / pipx
# help message
vagd -h
# analyses the binary, prints checksec and .comment (often includes Distro and Compiler info)
vagd info BINARY
# creates template, for more info use: vagd template -h
vagd template [OPTIONS] [BINARY] [IP] [PORT]
# ssh to current vagd instance, for more info use: vagd ssh -h
vagd ssh [OPTIONS]
# scp file to/from vagd instance, for more info use: vagd scp -h
# e.g. vagd scp ./test_file vagd:./ # vagd:./ is default target
vagd scp [OPTIONS] SOURCE [TARGET]
# stop and remove current vagd instance, for more info use: vagd clean -h
vagd clean [OPTIONS]

Documentation

Boxes

A listed of known working Boxes can be found in the Documentation. Other images might also work but currently only distributions that use apt and alpine for Docker are supported. This limitation may be circumvented by creating a target yourself (with the dependencies gdbserver, python, openssh) and creating a ssh connection via Shgd.

Troubleshooting

background processes

all instances continue to run in the background (after a vagd object has been started), this improves the runtime greatly after the first execution of the exploit. But this means that instances must be killed manually e.g.: vagd clean

gdb & gdbserver

Because gdbserver is used to run binaries on the instances I recommend using pwndbg. Other well known gdb plugins like peda aren't compatible with gdbserver and therefore won't work.

files

files on the virtual instance are never overwritten this has performance reason (so files aren't always copied if the exploit is run). If you need to updated files on the remote either use vagd scp or create use temporary directories Dogd(..., tmp=True)

gdb performance

Using gdbserver and gdb to index libraries can be very slow. Therefore an experimental feature is available that mounts libraries locally: Dogd(..., ex=True, fast=True)

Future plans

Better Docker integration

migrate away from ssh (attach from host) to get lower latency
additionally virtualize containers (Qemu) in order to change the used kernel

Metadata

Release files for vagd 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vagd 1.8.0
File	Size	Uploaded
vagd-1.8.0.tar.gz	54.3 kB	Aug 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vagd 1.8.0
File	Interpreter	ABI	Platform	Reset
vagd-1.8.0-py3-none-any.whl 58.8 kB Aug 3, 2026	Python 3	none	any	Details

Total release size: 113.2 kB

Release files / vagd-1.8.0.tar.gz

Download URL	vagd-1.8.0.tar.gz
Size	54.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`7d1cf2f7f7a6b72c6244f4b227dd6025ecda7e4b3e799a4e1f634ff59fe33c6b`
BLAKE2b-256 checksum How to use checksums	`16ddb83de46164dd08ab44a6fdaf8886129847ea742f7f019cad567334495b8d`
Upload date	Aug 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.11`

Release files / vagd-1.8.0-py3-none-any.whl

Download URL	vagd-1.8.0-py3-none-any.whl
Size	58.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3a8d849306701779787877859c11ae0506242e46c7d473c6fc20d90a6c71ccac`
BLAKE2b-256 checksum How to use checksums	`fdfa540e8e3f1e6f3a0282e3f8e0f7f5274dde4c513e4160935e965f7a74b45b`
Upload date	Aug 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.11`