• This repository has been archived on 29/Dec/2022
  • Stars
    star
    1,638
  • Rank 27,347 (Top 0.6 %)
  • Language
    Python
  • License
    Other
  • Created about 10 years ago
  • Updated over 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Debugger capable of attaching to and injecting code into python processes.

DISCLAIMER: This is not an official google project, this is just something I wrote while at Google.

Pyringe

What this is

Pyringe is a python debugger capable of attaching to running processes, inspecting their state and even of injecting python code into them while they're running. With pyringe, you can list threads, get tracebacks, inspect locals/globals/builtins of running functions, all without having to prepare your program for it.

What this is not

A "Google project". It's my internship project that got open-sourced. Sorry for the confusion.

What do I need?

Pyringe internally uses gdb to do a lot of its heavy lifting, so you will need a fairly recent build of gdb (version 7.4 onwards, and only if gdb was configured with --with-python). You will also need the symbols for whatever build of python you're running.
On Fedora, the package you're looking for is python-debuginfo, on Debian it's called python2.7-dbg (adjust according to version). Arch Linux users: see issue #5, Ubuntu users can only debug the python-dbg binary (see issue #19).
Having Colorama will get you output in boldface, but it's optional.

How do I get it?

Get it from the Github repo, PyPI, or via pip (pip install pyringe).

Is this Python3-friendly?

Short answer: No, sorry. Long answer:
There's three potentially different versions of python in play here:

  1. The version running pyringe
  2. The version being debugged
  3. The version of libpythonXX.so your build of gdb was linked against

2 Is currently the dealbreaker here. Cpython has changed a bit in the meantime[1], and making all features work while debugging python3 will have to take a back seat for now until the more glaring issues have been taken care of.
As for 1 and 3, the 2to3 tool may be able to handle it automatically. But then, as long as 2 hasn't been taken care of, this isn't really a use case in the first place.

[1] - For example, pendingbusy (which is used for injection) has been renamed to busy and been given a function-local scope, making it harder to interact with via gdb.

Will this work with PyPy?

Unfortunately, no. Since this makes use of some CPython internals and implementation details, only CPython is supported. If you don't know what PyPy or CPython are, you'll probably be fine.

Why not PDB?

PDB is great. Use it where applicable! But sometimes it isn't.
Like when python itself crashes, gets stuck in some C extension, or you want to inspect data without stopping a program. In such cases, PDB (and all other debuggers that run within the interpreter itself) are next to useless, and without pyringe you'd be left with having to debug using print statements. Pyringe is just quite convenient in these cases.

I injected a change to a local var into a function and it's not showing up!

This is a known limitation. Things like inject('var = 2') won't work, but inject('var[1] = 1337') should. This is because most of the time, python internally uses a fast path for looking up local variables that doesn't actually perform the dictionary lookup in locals(). In general, code you inject into processes with pyringe is very different from a normal python function call.

How do I use it?

You can start the debugger by executing python -m pyringe. Alternatively:

import pyringe
pyringe.interact()

If that reminds you of the code module, good; this is intentional.
After starting the debugger, you'll be greeted by what behaves almost like a regular python REPL.
Try the following:

==> pid:[None] #threads:[0] current thread:[None]
>>> help()
Available commands:
 attach: Attach to the process with the given pid.
 bt: Get a backtrace of the current position.
 [...]
==> pid:[None] #threads:[0] current thread:[None]
>>> attach(12679)
==> pid:[12679] #threads:[11] current thread:[140108099462912]
>>> threads()
[140108099462912, 140108107855616, 140108116248323, 140108124641024, 140108133033728, 140108224739072, 140108233131776, 140108141426432, 140108241524480, 140108249917184, 140108269324032]

The IDs you see here correspond to what threading.current_thread().ident would tell you.
All debugger functions are just regular python functions that have been exposed to the REPL, so you can do things like the following.

==> pid:[12679] #threads:[11] current thread:[140108099462912]
>>> for tid in threads():
...   if not tid % 10:
...     thread(tid)
...     bt()
... 
Traceback (most recent call last):
  File "/usr/lib/python2.7/threading.py", line 524, in __bootstrap
    self.__bootstrap_inner()
  File "/usr/lib/python2.7/threading.py", line 551, in __bootstrap_inner
    self.run()
  File "/usr/lib/python2.7/threading.py", line 504, in run
    self.__target(*self.__args, **self.__kwargs)
  File "./test.py", line 46, in Idle
    Thread_2_Func(1)
  File "./test.py", line 40, in Wait
    time.sleep(n)
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> 

You can access the inferior's locals and inspect them like so:

==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> inflocals()
{'a': <proxy of A object at remote 0x1d9b290>, 'LOL': 'success!', 'b': <proxy of B object at remote 0x1d988c0>, 'n': 1}
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> p('a')
<proxy of A object at remote 0x1d9b290>
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> p('a').attr
'Some_magic_string'
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> 

And sure enough, the definition of a's class reads:

class Example(object):
  cl_attr = False
  def __init__(self):
    self.attr = 'Some_magic_string'

There's limits to how far this proxying of objects goes, and everything that isn't trivial data will show up as strings (like '<function at remote 0x1d957d0>').
You can inject python code into running programs. Of course, there are caveats but... see for yourself:

==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> inject('import threading')
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> inject('print threading.current_thread().ident')
==> pid:[12679] #threads:[11] current thread:[140108241524480]
>>> 

The output of my program in this case reads:

140108241524480

If you need additional pointers, just try using python's help (pyhelp() in the debugger) on debugger commands.

More Repositories

1

material-design-icons

Material Design icons by Google (Material Symbols)
49,776
star
2

guava

Google core libraries for Java
Java
48,313
star
3

zx

A tool for writing better scripts
JavaScript
37,928
star
4

styleguide

Style guides for Google-originated open-source projects
HTML
36,487
star
5

leveldb

LevelDB is a fast key-value storage library written at Google that provides an ordered mapping from string keys to string values.
C++
33,564
star
6

material-design-lite

Material Design Components in HTML/CSS/JS
HTML
32,283
star
7

googletest

GoogleTest - Google Testing and Mocking Framework
C++
32,215
star
8

jax

Composable transformations of Python+NumPy programs: differentiate, vectorize, JIT to GPU/TPU, and more
Python
27,959
star
9

python-fire

Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.
Python
26,112
star
10

comprehensive-rust

This is the Rust course used by the Android team at Google. It provides you the material to quickly teach Rust.
Rust
25,973
star
11

mediapipe

Cross-platform, customizable ML solutions for live and streaming media.
C++
25,320
star
12

gson

A Java serialization/deserialization library to convert Java Objects into JSON and back
Java
22,945
star
13

flatbuffers

FlatBuffers: Memory Efficient Serialization Library
C++
21,883
star
14

iosched

The Google I/O Android App
Kotlin
21,789
star
15

ExoPlayer

An extensible media player for Android
Java
21,465
star
16

eng-practices

Google's Engineering Practices documentation
19,741
star
17

web-starter-kit

Web Starter Kit - a workflow for multi-device websites
HTML
18,434
star
18

flexbox-layout

Flexbox for Android
Kotlin
18,141
star
19

fonts

Font files available from Google Fonts, and a public issue tracker for all things Google Fonts
HTML
17,588
star
20

filament

Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
C++
16,946
star
21

cadvisor

Analyzes resource usage and performance characteristics of running containers.
Go
16,273
star
22

libphonenumber

Google's common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers.
C++
15,728
star
23

gvisor

Application Kernel for Containers
Go
15,047
star
24

WebFundamentals

Former git repo for WebFundamentals on developers.google.com
JavaScript
13,842
star
25

yapf

A formatter for Python files
Python
13,560
star
26

tink

Tink is a multi-language, cross-platform, open source library that provides cryptographic APIs that are secure, easy to use correctly, and hard(er) to misuse.
Java
13,318
star
27

deepdream

13,212
star
28

brotli

Brotli compression format
TypeScript
12,921
star
29

guetzli

Perceptual JPEG encoder
C++
12,863
star
30

guice

Guice (pronounced 'juice') is a lightweight dependency injection framework for Java 11 and above, brought to you by Google.
Java
12,342
star
31

wire

Compile-time Dependency Injection for Go
Go
12,222
star
32

blockly

The web-based visual programming editor.
TypeScript
12,067
star
33

sanitizers

AddressSanitizer, ThreadSanitizer, MemorySanitizer
C
10,754
star
34

grumpy

Grumpy is a Python to Go source code transcompiler and runtime.
Go
10,464
star
35

or-tools

Google's Operations Research tools:
C++
10,405
star
36

dopamine

Dopamine is a research framework for fast prototyping of reinforcement learning algorithms.
Jupyter Notebook
10,367
star
37

auto

A collection of source code generators for Java.
Java
10,234
star
38

go-github

Go library for accessing the GitHub v3 API
Go
9,941
star
39

oss-fuzz

OSS-Fuzz - continuous fuzzing for open source software.
Shell
9,859
star
40

go-cloud

The Go Cloud Development Kit (Go CDK): A library and tools for open cloud development in Go.
Go
9,314
star
41

sentencepiece

Unsupervised text tokenizer for Neural Network-based text generation.
C++
8,657
star
42

re2

RE2 is a fast, safe, thread-friendly alternative to backtracking regular expression engines like those used in PCRE, Perl, and Python. It is a C++ library.
C++
8,190
star
43

traceur-compiler

Traceur is a JavaScript.next-to-JavaScript-of-today compiler
JavaScript
8,182
star
44

tsunami-security-scanner

Tsunami is a general purpose network security scanner with an extensible plugin system for detecting high severity vulnerabilities with high confidence.
Java
8,118
star
45

trax

Trax β€” Deep Learning with Clear Code and Speed
Python
7,943
star
46

skia

Skia is a complete 2D graphic library for drawing Text, Geometries, and Images.
C++
7,874
star
47

benchmark

A microbenchmark support library
C++
7,812
star
48

android-classyshark

Android and Java bytecode viewer
Java
7,468
star
49

pprof

pprof is a tool for visualization and analysis of profiling data
Go
7,408
star
50

closure-compiler

A JavaScript checker and optimizer.
Java
7,245
star
51

agera

Reactive Programming for Android
Java
7,227
star
52

accompanist

A collection of extension libraries for Jetpack Compose
Kotlin
7,210
star
53

magika

Detect file content types with deep learning
Python
7,171
star
54

flutter-desktop-embedding

Experimental plugins for Flutter for Desktop
C++
7,109
star
55

latexify_py

A library to generate LaTeX expression from Python code.
Python
6,953
star
56

diff-match-patch

Diff Match Patch is a high-performance library in multiple languages that manipulates plain text.
Python
6,918
star
57

lovefield

Lovefield is a relational database for web apps. Written in JavaScript, works cross-browser. Provides SQL-like APIs that are fast, safe, and easy to use.
JavaScript
6,847
star
58

glog

C++ implementation of the Google logging module
C++
6,797
star
59

jsonnet

Jsonnet - The data templating language
Jsonnet
6,742
star
60

error-prone

Catch common Java mistakes as compile-time errors
Java
6,690
star
61

model-viewer

Easily display interactive 3D models on the web and in AR!
TypeScript
6,473
star
62

gops

A tool to list and diagnose Go processes currently running on your system
Go
6,375
star
63

draco

Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
C++
6,188
star
64

automl

Google Brain AutoML
Jupyter Notebook
6,153
star
65

gopacket

Provides packet processing capabilities for Go
Go
6,082
star
66

physical-web

The Physical Web: walk up and use anything
Java
6,017
star
67

j2objc

A Java to iOS Objective-C translation tool and runtime.
Java
5,976
star
68

grafika

Grafika test app
Java
5,964
star
69

snappy

A fast compressor/decompressor
C++
5,940
star
70

ios-webkit-debug-proxy

A DevTools proxy (Chrome Remote Debugging Protocol) for iOS devices (Safari Remote Web Inspector).
C
5,848
star
71

osv-scanner

Vulnerability scanner written in Go which uses the data provided by https://osv.dev
Go
5,826
star
72

seesaw

Seesaw v2 is a Linux Virtual Server (LVS) based load balancing platform.
Go
5,599
star
73

seq2seq

A general-purpose encoder-decoder framework for Tensorflow
Python
5,577
star
74

EarlGrey

🍡 iOS UI Automation Test Framework
Objective-C
5,570
star
75

flax

Flax is a neural network library for JAX that is designed for flexibility.
Python
5,493
star
76

google-java-format

Reformats Java source code to comply with Google Java Style.
Java
5,366
star
77

wireit

Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient.
TypeScript
5,280
star
78

battery-historian

Battery Historian is a tool to analyze battery consumers using Android "bugreport" files.
Go
5,249
star
79

clusterfuzz

Scalable fuzzing infrastructure.
Python
5,201
star
80

bbr

5,156
star
81

gumbo-parser

An HTML5 parsing library in pure C99
HTML
5,141
star
82

syzkaller

syzkaller is an unsupervised coverage-guided kernel fuzzer
Go
5,111
star
83

git-appraise

Distributed code review system for Git repos
Go
5,090
star
84

google-authenticator

Open source version of Google Authenticator (except the Android app)
Java
5,077
star
85

gemma.cpp

lightweight, standalone C++ inference engine for Google's Gemma models.
C++
5,076
star
86

uuid

Go package for UUIDs based on RFC 4122 and DCE 1.1: Authentication and Security Services.
Go
4,994
star
87

gts

β˜‚οΈ TypeScript style guide, formatter, and linter.
TypeScript
4,930
star
88

gemma_pytorch

The official PyTorch implementation of Google's Gemma models
Python
4,920
star
89

closure-library

Google's common JavaScript library
JavaScript
4,837
star
90

cameraview

[DEPRECATED] Easily integrate Camera features into your Android app
Java
4,734
star
91

grr

GRR Rapid Response: remote live forensics for incident response
Python
4,641
star
92

liquidfun

2D physics engine for games
C++
4,559
star
93

pytype

A static type analyzer for Python code
Python
4,528
star
94

gxui

An experimental Go cross platform UI library.
Go
4,450
star
95

bloaty

Bloaty: a size profiler for binaries
C++
4,386
star
96

clasp

πŸ”— Command Line Apps Script Projects
TypeScript
4,336
star
97

ko

Build and deploy Go applications on Kubernetes
Go
4,329
star
98

santa

A binary authorization and monitoring system for macOS
Objective-C
4,288
star
99

google-ctf

Google CTF
Go
4,246
star
100

tamperchrome

Tamper Dev is an extension that allows you to intercept and edit HTTP/HTTPS requests and responses as they happen without the need of a proxy. Works across all operating systems (including Chrome OS).
TypeScript
4,148
star