shamiko

shamiko is a library for inspecting running Python processes.

It can

• inspect Python processes
  • obtain information about current frames and threads of the running process
• inject arbitrary code into specified frame and thread of the process
• attach the running process with pdb

Install

pip install shamiko

CLI

shamiko provides the command-line interface.

shamiko --help

Usage: shamiko [OPTIONS] PID COMMAND [ARGS]...

Arguments:
  PID (int): PID of target Python process

Options:
  -e, --executable (str):  executable path of given PID
  -c, --context (str):     context directory of given PID
  --help                   show help message

Commands:
  inspect     inspect the running process
  attach      attach a debugger to the running process
  run-file    inject a python script file into the running process
  run-script  inject a python code into the running process
  shell       launch an interactive shell

inspect

inspect the running process

Usage: shamiko PID inspect

attach

attach a debugger to the running process

Usage: shamiko PID attach [OPTIONS]

Options:
  --thread (int): thread id where you can obtain by `inspect` command
  --frame (int): frame id where you can obtain by `inspect` command
  --debugger (str): debugger type. available debuggers: [pdb]

run-file

inject a python script file into the running process

Usage: shamiko PID run-file [OPTIONS] FILE_PATH

Arguments:
  FILE_PATH (str): a path of the python script that you want to inject into given PID

Options:
  --thread (int): thread id where you can obtain by `inspect` command
  --frame (int): frame id where you can obtain by `inspect` command

run-script

inject a python code into the running process

Usage: shamiko PID run-script [OPTIONS] SCRIPT

Arguments:
  SCRIPT (str): a python code that you want to inject into given PID

Options:
  --thread (int): thread id where you can obtain by `inspect` command
  --frame (int): frame id where you can obtain by `inspect` command

shell

launch an interactive shell

Usage: shamiko PID shell

FAQ

ptrace: Operation not permitted

Could not attach to process.  If your uid matches the uid of the target
process, check the setting of /proc/sys/kernel/yama/ptrace_scope, or try
again as the root user.  For more details, see /etc/sysctl.d/10-ptrace.conf
ptrace: Operation not permitted.

In most distributions, executing ptrace of non-child processes by a non-super user is disallowed. You can disable this temporarily by

echo 0 > /proc/sys/kernel/yama/ptrace_scope

auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load"

warning: File "/home/user/.pyenv/versions/3.6.9/bin/python3.6-gdb.py" auto-loading has been declined by your `auto-load safe
-path' set to "$debugdir:$datadir/auto-load".

shamiko uses the gdb Python extension script python-gdb.py. To allow auto loading of this file, execute

echo "add-auto-load-safe-path [path to python-gdb.py]" >> ~/.gdbinit

To simply allow auto loading of all pathes, execute

echo "add-auto-load-safe-path /" >> ~/.gdbinit

Examples

• To allow Python 3.6 that you installed by pyenv

echo "add-auto-load-safe-path ~/.pyenv/shims/python3.6-gdb.py" >> ~/.gdbinit