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 |
- gdb (version 7.3+)
- A Linux system whose ptrace policy allows attaching to the target process. See ptrace_scope below.
pipx install pyrasite
or, for the optional memory viewer:
pip install "pyrasite[memory-viewer]"
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.
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.
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).
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.
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.
The graphical interface is maintained separately at https://github.com/lmacken/pyrasite-gui.
Created by Luke Macken with the help of David Malcolm and many other contributors. Logo by Adam Saunders.
