vagd

Submodules

Classes

`Box`	constants class for recommended images and boxes
`Cogd`
`Degd`	Native Docker API backend with Docker exec and gdbserver integration.
`Dogd`
`Pogd`
`Logd`	local execution of binary
`Qegd`
`Shgd`	ssh interface for pwntools
`Vagd`

Package Contents

class vagd.Box

constants class for recommended images and boxes

QEMU_NOBLE = 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img'

QEMU_JAMMY = 'https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img'

QEMU_FOCAL = 'https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img'

QEMU_BIONIC = 'https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img'

QEMU_UBUNTU = 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img'

QEMU_NOBLE_ARM = 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-arm64.img'

QEMU_JAMMY_ARM = 'https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-arm64.img'

DOCKER_NOBLE = 'ubuntu:noble'

DOCKER_JAMMY = 'ubuntu:jammy'

DOCKER_FOCAL = 'ubuntu:focal'

DOCKER_BIONIC = 'ubuntu:bionic'

DOCKER_XENIAL = 'ubuntu:xenial'

DOCKER_UBUNTU = 'ubuntu:noble'

DOCKER_I386_FOCAL = 'i386/ubuntu:focal'

DOCKER_I386_BIONIC = 'i386/ubuntu:bionic'

DOCKER_I386_XENIAL = 'i386/ubuntu:xenial'

DOCKER_ALPINE_320 = 'alpine:3.20'

DOCKER_ALPINE = 'alpine:3.20'

DOCKER_ARCH = 'archlinux:base'

VAGRANT_JAMMY64 = 'ubuntu/jammy64'

VAGRANT_FOCAL64 = 'ubuntu/focal64'

VAGRANT_BIONIC64 = 'ubuntu/bionic64'

VAGRANT_XENIAL64 = 'ubuntu/xenial64'

class vagd.Cogd(binary: str, containerhome: str, cogd_type: str, lockfile: str, image: str = DEFAULT_IMAGE, user: str = DEFAULT_USER, forward: Dict[str, int] | None = None, packages: List[str] | None = None, cap_add: List[str] | None = None, privileged: bool = False, symbols: bool = True, rm: bool = True, ex: bool = False, fast: bool = False, alpine: bool = False, **kwargs: Any)

Bases: vagd.virts.shgd.Shgd

Container virtualization for pwntools

Parameters:

binary – binary to execute
containerhome – home directory of container runtime
lockfile – lockfile of container runtime
cogd_type – type of container tool
image – docker base image
user – name of user on docker container
forward – Dictionary of forwarded ports, needs to follow docker api format: ‘hostport/(tcp|udp)’ : guestport
packages – packages to install on the container
cap_add – Linux capabilities to add to the container
privileged – run the container with extended privileges
symbols – additionally install libc6 debug symbols (also updates libc6)
ex – if experimental features, e.g. alpine, gdbserver should be enabled
rm – remove container after exit
alpine – if the conainter is alpine (also autochecks image name)
fast – mounts libs locally for faster symbol extraction (experimental) NOT COMPATIBLE WITH ALPINE
kwargs – parameters to pass through to super

_image: str

_name: str

_user: str

_port: int

_packages: List[str]

_client: docker.DockerClient | podman.PodmanClient

_id: str

_containerdir: str

_dockerfile: str

_has_not_apt: bool

_rm: bool

_ex: bool

_forward: Dict[str, int]

_symbols: bool

_template: str

_containerhome: str

_lockfile: str

_type: str

VAGD_PREFIX = 'vagd-'

DEFAULT_USER = 'vagd'

DEFAULT_PORT = 2222

DEFAULT_IMAGE = 'ubuntu:noble'

DEFAULT_PACKAGES = ['gdbserver', 'python3', 'sudo', 'openssh-server']

_cap_add = []

_privileged = False

_create_dockerfile()

_create_container_instance()

_build_image()

_vm_setup() → None: pass

_vm_create()

abstractmethod _client_setup() → Any

class vagd.Degd(binary: str, image: str = DEFAULT_IMAGE, user: str = DEFAULT_USER, forward: Dict[str, Any] | None = None, packages: List[str] | None = None, cap_add: List[str] | None = None, privileged: bool = False, symbols: bool = True, files: str | List[str] | None = None, libs: bool = False, tmp: bool = False, rm: bool = True, fast: bool = False, ex: bool = False, **kwargs: Any)

Bases: vagd.virts.pwngd.Pwngd

Native Docker API backend with Docker exec and gdbserver integration.

Parameters:

binary – local binary to upload and execute
image – Debian or Ubuntu base image
user – user for target processes inside the container
forward – additional Docker port mappings
packages – additional packages installed while building the image
cap_add – Linux capabilities to add to the container
privileged – run the container with extended privileges
symbols – install libc debug symbols
files – additional files or directories to upload
libs – download the target’s dynamically linked libraries
tmp – use a fresh temporary working directory
rm – automatically remove the container when it stops

TYPE = 'degd'

LOCKFILE = './.vagd/docker-api.lock'

DOCKERHOME

DEFAULT_IMAGE = 'ubuntu:noble'

DEFAULT_USER = 'vagd'

WORKDIR = '/vagd'

GDBSERVER_PORT = 42069

DEFAULT_PACKAGES = ['gdbserver', 'python3', 'sudo']

is_new = False

_path = b'.'

_binary

_image = 'ubuntu:noble'

_user = 'vagd'

_forward

_cap_add = []

_privileged = False

_rm = True

_symbols = True

_packages = ['gdbserver', 'python3', 'sudo']

_client

_container

_workdir = '/vagd'

_ssh_setup() → None: setup ssh connection

_configuration() → Dict[str, Any]

_image_configuration() → Dict[str, Any]

_build_directory() → str

_create_dockerfile() → str

_build_image() → Any

_container_name() → str

_create_container() → None

_vm_setup() → None: setup vagrant machine creates new one if no Vagrantfile is specified or box does not match

_run_wait(command: str | List[str], user: str | None = None) → bytes

_remote_exists(path: str) → bool

_sync(file: str) → bool: upload file on remote if not exist :type file: file to upload :return: if the file was uploaded

static _archive(path: str) → bytes

static put_to(container: Any, file: str, remote: str) → None

put(file: str, remote: str | None = None) → None

upload file or dir on vm,

Parameters:

file – file to upload
remote – remote location of file, working directory if not specified

Returns:

returns

static pull_from(container: Any, file: str, local: str | None = None) → None

pull(file: str, local: str | None = None) → None

download file or dir on vm,

Parameters:

file – remote location of file, working directory if not specified
local – local location of file, current directory if not specified

Returns:

returns

libs(directory: str) → None

Downloads the libraries referred to by a file. This is done by running ldd on the remote server, parsing the output and downloading the relevant files.

directory(str): Output directory :return:

which(program: str) → str | None

process(argv: List[str] | None = None, command: List[str] | None = None, **kwargs: Any) → vagd.virts.docker_exec.DockerExecTube

run binary in vm as process

Parameters:

argv – comandline arguments for binary
kwargs – pwntool parameters

Returns:

pwntools process

system(command: str | List[str]) → vagd.virts.docker_exec.DockerExecTube

executes command on vm, interface to pwnlib.tubes.ssh.ssh.system

Parameters:: cmd – command to execute on vm
Returns:: returns

debug(argv: List[str] | None = None, gdb_args: List[str] | None = None, gdbscript: str = '', sysroot: str | None = None, sysroot_debug: str | None = None, api: bool = False, **kwargs: Any) → vagd.virts.docker_exec.DockerExecTube

run binary in vm with gdb (pwnlib feature set)

Parameters:

argv – comandline arguments for binary
gdb_args – gdb args to forward to gdb
gdbscript – GDB script for GDB
sysroot – sysroot dir
sysroot_debug – sysroot debug lib dir
kwargs – pwntool parameters

Returns:

pwntools process

start(argv: List[str] | None = None, gdbscript: str = '', api: bool = False, sysroot: str | None = None, sysroot_debug: str | None = None, gdb_args: List[str] | None = None, **kwargs: Any) → vagd.virts.docker_exec.DockerExecTube

start binary on remote and return pwnlib.tubes.process.process

Parameters:

argv – commandline arguments for binary
gdbscript – GDB script for GDB
api – if GDB API should be enabled
sysroot – sysroot dir
sysroot_debug – sysroot debug lib dir
gdb_args – extra gdb args
kwargs – pwntool parameters

Returns:

pwntools process, if api=True tuple with gdb api

class vagd.Dogd(binary: str, **kwargs: Any)

Bases: vagd.virts.cogd.Cogd

Docker virtualization for pwntools

Parameters:: kwargs – parameters to pass through to super

SSH from cmd

vagd ssh
# or
ssh -o "StrictHostKeyChecking=no" -i ~/.share/local/vagd/keyfile -p $(cut .vagd/docker.lock -d":" -f 2) vagd@0.0.0.0

connect with docker exec

docker exec -it $(cut ./.vagd/docker.lock -d":" -f 1) /bin/bash

Kill from cmd:

vagd clean
#or
docker kill $(cut ./.vagd/docker.lock -d":" -f 1)

Docker containers are automatically removed after they stop
Docker images need to be manually removed from docker
Dockerfiles are stored in home directory to allow caching ~/.share/local/vagd/docker/<image>/Dockerfile

docker images # list images
docker rmi <id> # remove correct image

TYPE = 'dogd'

DOCKERHOME

LOCKFILE = './.vagd/docker.lock'

_client_setup() → Any

class vagd.Pogd(binary: str, **kwargs: Any)

Bases: vagd.virts.cogd.Cogd

Podman virtualization for pwntools

Parameters:: kwargs – parameters to pass through to super

SSH from cmd

vagd ssh
# or
ssh -o "StrictHostKeyChecking=no" -i ~/.share/local/vagd/keyfile -p $(cut .vagd/podman.lock -d":" -f 2) vagd@0.0.0.0

connect with podman exec

podman exec -it $(cut ./.vagd/podman.lock -d":" -f 1) /bin/bash

Kill from cmd:

vagd clean
#or
podman kill $(cut ./.vagd/podman.lock -d":" -f 1)

Podman containers are automatically removed after they stop
Podman images need to be manually removed from docker
Dockerfiles are stored in home directory to allow caching ~/.share/local/vagd/podman/<image>/Dockerfile

podman images # list images
podman rmi <id> # remove correct image

TYPE = 'pogd'

PODMANHOME

LOCKFILE = './.vagd/podman.lock'

_client_setup() → Any

class vagd.Logd(binary: str, **kwargs: Any)

Bases: vagd.virts.pwngd.Pwngd

local execution of binary

Parameters:: binary – binary to execute

_binary: str

_vm_setup() → None: NOT IMPLEMENTED

_ssh_setup() → None: NOT IMPLEMENTED

_sync(file: str) → None: NOT IMPLEMENTED

_mount(remote_dir: str, local_dir: str) → None: NOT IMPLEMENTED

_mount_lib(remote_lib: str = '/usr/lib') → None: NOT IMPLEMENTED

system(cmd: str) → None: NOT IMPLEMENTED

_install_packages(packages: Iterable): NOT IMPLEMENTED

put(file: str, remote: str | None = None): NOT IMPLEMENTED

debug(**kwargs: Any) → pwnlib.tubes.process.process: run binary with gdb locally :param kwargs: pwntool arguments :rtype: pwnlib.tubes.process.process

pwn_debug(argv: list[str] | None = None, **kwargs: Any) → pwnlib.tubes.process.process: run binary with gdb locally :param argv: comandline arguments for binary :param kwargs: pwntool arguments :rtype: pwnlib.tubes.process.process

process(argv: list[str] | None = None, **kwargs: Any) → pwnlib.tubes.process.process: run binary locally :param argv: comandline arguments for binary :param kwargs: pwntool parameters :return: pwntools process

start(argv: list[str] | None = None, gdbscript: str = '', api: bool = False, **kwargs: Any) → pwnlib.tubes.process.process: start binary locally and return pwnlib.tubes.process.process :param argv: commandline arguments for binary :param gdbscript: GDB script for GDB :param api: if GDB API should be enabled (experimental) :param kwargs: pwntool parameters :return: pwntools process, if api=True tuple with gdb api

class vagd.Qegd(binary: str, img: str = DEFAULT_IMG, user: str = DEFAULT_USER, forward: Dict[str, int] | None = None, packages: List[str] | None = None, arm: bool = False, qemu: str = DEFAULT_QEMU_CMD, cpu: str = DEFAULT_QEMU_CPU, memory: str = DEFAULT_QEMU_MEMORY, machine: str = DEFAULT_QEMU_MACHINE, cores: str = DEFAULT_QEMU_CORES, bios: str | None = None, detach: bool = False, custom: str = '', **kwargs: Any)

Bases: vagd.virts.shgd.Shgd

QEMU Virtualization for pwntools

Parameters:

binary – binary for VM debugging
img – qemu image to use (requires ssh)
user – user inside qemu image
ports – forwarded ports
packages – packages to install on vm
arm – emulate arm in qemu
qemu – qemu cmd
cpu – value for :code -cpu
memory – value for :code -m
cores – value for :code -smp
machine – value for :code -machine
bios – value for :code -bios
custom – custom qemu arguments
detach – run qemu in new terminal
kwargs – parameters to pass through to super

SSH from cmd

vagd ssh
# or
ssh -o "StrictHostKeyChecking=no" -i ~/.share/local/vagd/keyfile -p $(cat .vagd/qemu.lock) ubuntu@0.0.0.0

Kill from cmd:

vagd clean
# or
kill $(cat .vagd/qemu.pid)

Qemu images are cached in the home directory: ~/.share/local/vagd/qemu-imgs/

current used images are stored in the local directory: ./.vagd/current.img
These should be deleted automatically, but if a machine gets improperly stopped
(shutdown host while vm is running) it might remain and use up space. You can find remaining images with:

find ~/ -name current.img
rm <path/current.img>

DEFAULT_IMG = 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img'

QEMU_DIR = './.vagd/'

IMGS_DIR

DEFAULT_USER = 'vagd'

DEFAULT_HOST = '0.0.0.0'

TYPE = 'qegd'

DEFAULT_PORT = 2222

DEFAULT_QEMU_CMD = 'qemu-system-x86_64'

DEFAULT_QEMU_ARM_CMD = 'qemu-system-aarch64'

DEFAULT_QEMU_MACHINE_PREFIX = '-machine'

DEFAULT_QEMU_MACHINE = 'accel=kvm,type=q35'

DEFAULT_QEMU_ARM_MACHINE = 'virt'

DEFAULT_QEMU_CPU_PREFIX = '-cpu'

DEFAULT_QEMU_CPU = 'host'

DEFAULT_QEMU_ARM_CPU = 'cortex-a72'

DEFAULT_QEMU_CORES_PREFIX = '-smp'

DEFAULT_QEMU_CORES = '2'

DEFAULT_QEMU_BIOS_PREFIX = '-bios'

DEFAULT_QEMU_ARM_BIOS = '/usr/share/edk2/aarch64/QEMU_EFI.fd'

DEFAULT_QEMU_MEMORY_PREFIX = '-m'

DEFAULT_QEMU_MEMORY = '2G'

_img: str

_local_img: str

_user: str

_host: str

_port: int

_forward: Dict[str, int]

_qemu: str

_cpu: str

_cores: str

_memory: str

_bios: str

_machine: str

_detach: bool

_custom = ''

static _is_local(url) → bool: check if provided url is local or remote :param url: url to check :return: if the url is local or remote

CURRENT_IMG = './.vagd/current.img'

_set_local_img(): get local image for qemu machine

METADATA_FILE = './.vagd/metadata.yaml'

_METADATA = Multiline-String

Show Value

"""instance-id: iid-local01
local-hostname: cloudimg
"""

USER_DATA_FILE = './.vagd/user-data.yaml'

_USER_DATA = Multiline-String

Show Value

"""#cloud-config
users:
  - default
  - name: {user}
    groups: sudo
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh_authorized_keys:
      - {pubkey}
"""

SEED_FILE = './.vagd/seed.img'

_GENERATE_SEED_IMG = 'cloud-localds ./.vagd/seed.img ./.vagd/user-data.yaml ./.vagd/metadata.yaml'

_setup_seed(): create seed.img with config data like ssh keypair in .qemu

_QEMU_PORT_FORWARDING = ',hostfwd={type}::{guest}-:{host}'

_QEMU_START = '{qemu} {machine} {cores} {cpu} {memory} -nographic -serial none -monitor none -pidfile...

_QEMU_PIPE = '> /dev/null; '

_QEMU_SUFFIX = 'rm -f {lock} {current} {pidfile}'

_QEMU_ARM_START = ''

LOCKFILE = './.vagd/qemu.lock'

PIDFILE = './.vagd/qemu.pid'

_qemu_start(): start qemu machine

_new_vm() → None: create new vm

_vm_setup() → None: setup qemu machine

class vagd.Shgd(binary: str, user: str = DEFAULT_USER, host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, keyfile: str = Pwngd.KEYFILE, **kwargs: Any)

Bases: vagd.virts.pwngd.Pwngd

ssh interface for pwntools

Parameters:

binary – binary to execute
user – ssh user
host – ssh hostname
port – ssh port
keyfile – ssh keyfile (default in .vagd)
kwargs – parameters to pass through to super

DEFAULT_HOST = 'localhost'

DEFAULT_PORT = 22

DEFAULT_USER = 'root'

_user: str

_host: str

_port: int

_keyfile: str

_ssh: pwnlib.tubes.ssh.ssh

bind(port: int) → int: bind port from ssh connection locally :param port: :return:

_vm_setup() → None: pass

_TRIES = 3

_ssh_setup() → None: setup ssh connection

class vagd.Vagd(binary: str, vagrantfile: str = VAGRANTFILE_PATH, vbox: str | None = None, packages: List[str] | None = None, **kwargs: Any)

Bases: vagd.virts.shgd.Shgd

Vagrant Virtualization for pwntools

Parameters:

binary – binary for VM debugging
vbox – vagrant box to use
vagrantfile – location of Vagrantfile
packages – packages to install on vm
kwargs – arguments to pass through to super

SSH from cmd:

vagd ssh
# or
VAGRANT_CWD=.vagd vagrant ssh

halt from cmd

VAGRANT_CWD=.vagd vagrant halt

destroy from cmd

vagd clean
# or
VAGRANT_CWD=.vagd vagrant destroy

VAGRANTFILE_PATH = './.vagd/Vagrantfile'

VAGRANTFILE_BOX = 'config.vm.box'

VAGRANT_BOX = 'ubuntu/jammy64'

KEYFILE = './.vagd/.vagd/.vagrant/machines/default/virtualbox/private_key'

TYPE = 'vagd'

_box: str

_vagrantfile: str

_v: object

_get_box() → str: returns box of current vagrantfile @:rtype box name of Vagrantfile

_vm_setup() → None: setup vagrant machine creates new one if no Vagrantfile is specified or box does not match