Skip to content

Latest commit

 

History

History
100 lines (85 loc) · 2.88 KB

README.md

File metadata and controls

100 lines (85 loc) · 2.88 KB
Raw

madbg

Tests (GitHub Actions) PyPI Supported Python Versions PyPI version GitHub license

A fully-featured remote debugger for python.

  • Provides a full remote tty, allowing sending keyboard signals to the debugger, tab completion, command history, line editing and more
  • Runs the IPython debugger with all its capabilities
  • Allows attaching to running programs preemptively (does not require gdb, unlike similar tools)
  • Affects the debugged program minimally, although not yet recommended for use in production environments
  • Provides TTY features even when debugged program is a deamon, or run outside a terminal

Installation

pip install madbg

Usage

Madbg provide both a python API and a CLI.

Attaching to a running process

madbg attach <pid>

Or

import madbg
madbg.attach_to_process(pid)

Warning

  • Attaching on linux could potentially deadlock the target process. Not recommneded for use in production environments yet.
  • madbg has to be installed in the target process' interpreter for attach to work.

Starting a debugger

Using the CLI

Run a python file with automatic post-mortem:

madbg run path_to_your_script.py <args_for_script ...>

Run a python module similarly to python -m:

madbg run -m module.name <args_for_script ...>

Start a script, starting the debugger from the first line:

madbg run --use-set-trace script.py <args_for_script ...>

Using the API

Start a debugger in the next line:

madbg.set_trace()

Continue running the program until a client connects, then stop it and start a debugger:

madbg.set_trace_on_connect()

After an exception has occurred, or in an exception context, start a debugger in the frame the exception was raised from:

madbg.post_mortem()

Connecting to a debugger

Using the CLI

madbg connect

Using the API

madbg.connect_to_debugger()

Connection

All madbg API functions and CLI entry points allow using a custom IP and port (the default is 127.0.0.1:3513), for example:

madbg.set_trace(ip='0.0.0.0', port=1337)

or

madbg connect 8.8.8.8 1337

Platforms

Madbg supports linux with python>=3.8.

Possible effects

What madbg does that might affect a debugged program:

  • Changes the pgid and sid of the debugged process
  • Changes the CTTY of the debugged process
  • Affects child processes in unknown ways (Not tested yet)

What madbg doesn't do:

  • Writes or reads from stdio
  • Feeds your cat