Skip to content
lmackenPublic

About

Inject code into running Python processes

Topics

Resources

Stars

2.9k stars

Watchers

48 watching

Forks

Repository files navigation

https://raw.githubusercontent.com/lmacken/pyrasite/develop/docs/logo.png

pyrasite

https://github.com/lmacken/pyrasite/actions/workflows/ci.yml/badge.svg?branch=develop https://img.shields.io/pypi/v/pyrasite?style=flat

Tools for injecting arbitrary code into running Python processes.

homepage:https://github.com/lmacken/pyrasite
documentation:https://pyrasite.readthedocs.io/
download:https://pypi.org/project/pyrasite/
source:https://github.com/lmacken/pyrasite
issues:https://github.com/lmacken/pyrasite/issues

Requirements

  • gdb (version 7.3+)
  • A Linux system whose ptrace policy allows attaching to the target process. See ptrace_scope below.

Installation

pipx install pyrasite

or, for the optional memory viewer:

pip install "pyrasite[memory-viewer]"

Compatibility

Pyrasite runs on CPython 3.9 through 3.15. Injection works between versions as well, so you can run Pyrasite under one Python and inject into a process running another. Both the pyrasite client and the target process must be CPython.

ptrace_scope

Recent Linux distributions restrict ptrace so that a process may only be attached to by its ancestors. If /proc/sys/kernel/yama/ptrace_scope is non-zero you will see a warning. You can either allow attaching globally:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

or let the target process opt in by calling prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY). On Fedora, SELinux may also need:

sudo setsebool -P deny_ptrace=off

For multi-threaded programs pyrasite queues the payload with Py_AddPendingCall so that it runs on a thread that already holds the GIL. If the target is blocked in C and never executes Python bytecode, use --inject-method direct instead.

Usage

pyrasite <pid> hello.py
pyrasite <pid> - <<'EOF'
import sys
print(sys.version)
EOF
pyrasite <pid> <(echo 'print("hello")')

The payload is read by the pyrasite process and embedded in the gdb command, so the target does not need read access to the payload file. This also means pipes and process substitution work. Standard payloads can be selected by name (see pyrasite --list-payloads).

Remote and container use

To inject into a process on another host, run pyrasite there over SSH:

ssh host pyrasite <pid> - < payload.py
ssh -t host pyrasite-shell <pid>

When the target is in a different container and must connect back to a different address, choose the listening address, the address advertised to the target, and optionally a fixed port:

pyrasite-shell <pid> --bind-host 0.0.0.0 \
    --connect-host 10.0.0.5 --port 9001

The reverse shell socket has no authentication. Binding it to a non-loopback address lets anyone who can reach that address execute code in the target, so only do this on a trusted network or through an SSH tunnel.

Testing

pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .

To run the suite against every supported interpreter with uv:

uv python install 3.9 3.10 3.11 3.12 3.13 3.14 3.15
tox

To test injecting from one interpreter into all of the others, set PYRASITE_TEST_INTERPRETERS to a colon-separated list of interpreter paths before running pytest.

pyrasite-gui

The graphical interface is maintained separately at https://github.com/lmacken/pyrasite-gui.

Authors

Created by Luke Macken with the help of David Malcolm and many other contributors. Logo by Adam Saunders.

Licenses

Code

https://www.gnu.org/graphics/gplv3-127x51.png

Logo

https://creativecommons.org/images/deed/nolaw.png

About

Inject code into running Python processes

Topics

Resources

Stars

2.9k stars

Watchers

48 watching

Forks

Releases

Packages

Used by

Contributors

Languages