[](https://pypi.org/project/vagd/) [](https://vagd.gfelber.dev)
# VAGD
VirtuAlization GDb integrations in pwntools
## Installation
```bash
pip install vagd
```
or from repo with
```bash
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`
```python
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
```bash
# 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](https://github.com/pwndbg/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
```bash
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](https://vagd.gfelber.dev)
## Boxes
A listed of known working Boxes can be found in the [Documentation](http://vagd.gfelber.dev/autoapi/vagd/box/index.html#module-vagd.box).
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](https://github.com/pwndbg/pwndbg). Other well known gdb plugins like [peda](https://github.com/longld/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
Raw data
{
"_id": null,
"home_page": null,
"name": "vagd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "vagd, pwn, pwntools, exploit, ctf, capture, the, flag, binary, vagrant, qemu, docker",
"author": "0x6fe1be2",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a6/fe/f3402f671e7c5cfded577528313443904a4656bf009fe1a34fd2f7437064/vagd-1.5.5.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/vagd/) [](https://vagd.gfelber.dev)\n\n# VAGD\n\nVirtuAlization GDb integrations in pwntools\n\n## Installation\n\n```bash\npip install vagd\n```\n\nor from repo with\n\n```bash\ngit clone https://github.com/gfelber/vagd\npip install ./vagd/\n```\n\n## Usage\n\n- `vagd template [OPTIONS] [BINARY] [IP] [PORT]` to generate a template, list OPTIONS with help `-h`\n\n```python\nfrom pwn import *\n\nGOFF = 0x555555554000 # GDB default base address\nIP = '' # remote IP\nPORT = 0 # remote PORT\nBINARY = '' # PATH to local binary\nARGS = [] # ARGS supplied to binary\nENV = {} # ENV supplied to binary\n\n# GDB SCRIPT, executed at start of GDB session (e.g. set breakpoints here)\nGDB = f\"\"\"\nset follow-fork-mode parent\n\nc\"\"\"\n\ncontext.binary = exe = ELF(BINARY, checksec=False) # binary\ncontext.aslr = False # ASLR enabled (only GDB)\n\nvm = None\n# setup vagd vm\ndef setup():\n global vm\n if args.REMOTE or args.LOCAL:\n return\n\n try:\n # only load vagd if needed\n from vagd import Dogd, Qegd, Box\n except:\n log.error('Failed to import vagd, either run locally using LOCAL or install it')\n if not vm:\n vm = Dogd(BINARY, image=Box.DOCKER_UBUNTU, ex=True, fast=True) # Docker\n # vm = Qegd(BINARY, img=Box.QEMU_UBUNTU, ex=True, fast=True) # Qemu\n if vm.is_new:\n # additional setup here\n log.info('new vagd instance')\n\n\n# get target (pwnlib.tubes.tube)\ndef get_target(**kw) -> tubes.tube:\n if args.REMOTE:\n # context.log_level = 'debug'\n return remote(IP, PORT)\n\n if args.LOCAL:\n if args.GDB:\n return gdb.debug([BINARY] + ARGS, env=ENV, gdbscript=GDB, **kw)\n return process([BINARY] + ARGS, env=ENV, **kw)\n\n return vm.start(argv=ARGS, env=ENV, gdbscript=GDB, **kw)\n\n\nsetup()\n\n#===========================================================\n# EXPLOIT STARTS HERE\n#===========================================================\n\n# libc = ELF('', checksec=False)\n\nt = get_target()\n\nt.interactive() # or it()\n\n```\n\n- `vagd info BINARY` to print info about binary\n\n```bash\n# run as process in VM\n./exploit.py\n# run as gdb server in VM requires tmux\n./exploit.py GDB\n# run on remote IP:PORT\n./exploit.py REMOTE\n# run process locally\n./exploit.py LOCAL [GDB]\n```\n\nI recommend using [pwndbg](https://github.com/pwndbg/pwndbg).\n\n## Files\n\nAll 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).\n\n## CLI\n\n```bash\nalias vagd=\"python -m vagd\" # or install with pip / pipx\n# help message\nvagd -h\n# analyses the binary, prints checksec and .comment (often includes Distro and Compiler info)\nvagd info BINARY\n# creates template, for more info use: vagd template -h\nvagd template [OPTIONS] [BINARY] [IP] [PORT]\n# ssh to current vagd instance, for more info use: vagd ssh -h\nvagd ssh [OPTIONS]\n# scp file to/from vagd instance, for more info use: vagd scp -h\n# e.g. vagd scp ./test_file vagd:./ # vagd:./ is default target\nvagd scp [OPTIONS] SOURCE [TARGET]\n# stop and remove current vagd instance, for more info use: vagd clean -h\nvagd clean [OPTIONS]\n```\n\n## [Documentation](https://vagd.gfelber.dev)\n\n## Boxes\n\nA listed of known working Boxes can be found in the [Documentation](http://vagd.gfelber.dev/autoapi/vagd/box/index.html#module-vagd.box).\nOther images might also work but currently only distributions that use `apt` and alpine for Docker are supported.\nThis limitation may be circumvented by creating a target yourself (with the dependencies gdbserver, python, openssh) and creating a ssh connection via Shgd.\n\n## Troubleshooting\n\n### background processes\n\nall 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`\n\n### gdb & gdbserver\n\nBecause gdbserver is used to run binaries on the instances I recommend using [pwndbg](https://github.com/pwndbg/pwndbg). Other well known gdb plugins like [peda](https://github.com/longld/peda) aren't compatible with gdbserver and therefore won't work.\n\n### files\n\nfiles 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)`\n\n### gdb performance\n\nUsing 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)`\n\n## Future plans\n\n### Better Docker integration\n\n- migrate away from ssh (attach from host) to get lower latency\n- additionally virtualize containers (Qemu) in order to change the used kernel\n",
"bugtrack_url": null,
"license": null,
"summary": "VirtuAlization GDb integrations in pwntools",
"version": "1.5.5",
"project_urls": {
"Bug Tracker": "https://github.com/gfelber/vagd/issues",
"Documentation": "https://gfelber.github.io/vagd/",
"Homepage": "https://github.com/gfelber/vagd"
},
"split_keywords": [
"vagd",
" pwn",
" pwntools",
" exploit",
" ctf",
" capture",
" the",
" flag",
" binary",
" vagrant",
" qemu",
" docker"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e939a551fcce75b9b5d8c901f92dc987f22cc3caa98796ec858c4d3e5d1ae897",
"md5": "d8ab4d8324635601f5394b1480c1d9d7",
"sha256": "ac6257b857768aef9b5f199d6fc46b6b767cb8239bebd7ae41d29ecd2b01b71b"
},
"downloads": -1,
"filename": "vagd-1.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8ab4d8324635601f5394b1480c1d9d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 49740,
"upload_time": "2024-10-26T12:24:12",
"upload_time_iso_8601": "2024-10-26T12:24:12.922303Z",
"url": "https://files.pythonhosted.org/packages/e9/39/a551fcce75b9b5d8c901f92dc987f22cc3caa98796ec858c4d3e5d1ae897/vagd-1.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6fef3402f671e7c5cfded577528313443904a4656bf009fe1a34fd2f7437064",
"md5": "6ae9594c6b2fb75be28a0e52e7c7cee9",
"sha256": "5abafae20ded1d2673655983e60abba60c4e4b73ad3f6d5a67c861e9c0673a57"
},
"downloads": -1,
"filename": "vagd-1.5.5.tar.gz",
"has_sig": false,
"md5_digest": "6ae9594c6b2fb75be28a0e52e7c7cee9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 46756,
"upload_time": "2024-10-26T12:24:14",
"upload_time_iso_8601": "2024-10-26T12:24:14.386930Z",
"url": "https://files.pythonhosted.org/packages/a6/fe/f3402f671e7c5cfded577528313443904a4656bf009fe1a34fd2f7437064/vagd-1.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 12:24:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gfelber",
"github_project": "vagd",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pwntools",
"specs": []
},
{
"name": "docker",
"specs": []
},
{
"name": "typer",
"specs": []
}
],
"lcname": "vagd"
}
JSON
