Skip to main content

A proof-of-concept snapshot, transmission and restoring python runtime

Project description

build pypi

icon

A proof-of-concept serialization, transmission and restoring python runtime.

About

pyteleport is capable of making snapshots of python runtime from (almost) aribtrary state, including locals, globals and stack. It then transforms snapshots into specially designed bytecode that resumes execution from the snapshot state. The bytecode can be run remotely: this way pyteleport teleports python runtime.

Install

pip install pyteleport

Example

term cast 0

Note that the two outputs were produced by different processes on different machines! This is what tp_bash does: it transmits the runtime from one python process to another (remotely).

Also works from within a stack:

def a():
    def b():
        def c():
            result = "hello"
            tp_bash(...)
            return result + " world"
        return len(c()) + float("3.5")
    return 5 * (3 + b())
assert a() == 87.5

API

from pyteleport import tp_shell

def tp_shell(
    *shell_args, python="python", before="cd $(mktemp -d)",
    pyc_fn="payload.pyc", shell_delimiter="; ",
    pack_file=bash_inline_create_file,
    pack_object=dumps, unpack_object=portable_loads,
    detect_interactive=True, files=None, stack_method=None,
    _frame=None, **kwargs):
    """
    Teleport into another shell.

    Parameters
    ----------
    shell_args
        Arguments to start a new shell.
    python : str
        Python executable in the shell.
    before : str, list
        Shell commands to be run before running python.
    pyc_fn : str
        Temporary filename to save the bytecode to.
    shell_delimiter : str
        Shell delimiter to chain multiple commands.
    pack_file : Callable
        A function `f(name, contents)` turning a file
        into a shell-friendly assembly.
    pack_object : Callable, None
        A method (serializer) turning objects into bytes
        locally.
    unpack_object : Callable, None
        A method (deserializer) turning bytes into objects
        remotely. It does not have to rely on globals.
    detect_interactive : bool
        If True, attempts to detect the interactive mode
        and to open an interactive session remotely while
        piping stdio into this python process.
    files : list
        A list of files to teleport alongside.
    stack_method
        Stack collection method.
    _frame
        The frame to collect.
    kwargs
        Other arguments to `subprocess.run`.
    """

How it works

  • You invoke teleport in your python script.
  • pyteleport collects the runtime state: globals, locals, stack.
  • pyteleport dumps the runtime into a specially designed "morph" bytecode which resumes from where teleport was invoked.
  • The bytecode is transmitted to the target environment and passed to a python interpreter there.
  • The remote python runs the bytecode which restores the runtime state. The python program casually resumes from where it was interrupted.
  • The local python runtime is terminated and simply pipes stdio from the target environment.

Known limitations

This is a proof of concept. The package works with cPython v3.8, 3.9, or 3.10.

What is implemented:

  • MWE: snapshot, serialize, transmit, restore
  • serialize generators
  • yield from
  • threads (currently ignored)
  • block stack: for,try, with
  • async (non-python stack; needs further investigation)
  • forking to remote (possible with bytecode sstack prediction)
  • back-teleport (needs API development)
  • nested teleport (needs minimal changes)
  • cross-fork communications (need API development)
  • REPL integration
  • detecting non-python stack (peek into past value stack?)

Won't fix:

  • non-python stack (not possible)
  • cross-version (too fragile)

License

LICENSE.md

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyteleport-0.2.1.post2.tar.gz (22.2 kB view details)

Uploaded Source

File details

Details for the file pyteleport-0.2.1.post2.tar.gz.

File metadata

  • Download URL: pyteleport-0.2.1.post2.tar.gz
  • Upload date:
  • Size: 22.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.1 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10

File hashes

Hashes for pyteleport-0.2.1.post2.tar.gz
Algorithm Hash digest
SHA256 d067beae8e09a0f6f3c660df606bcec0048b0745f41efc5bb8cc75289bf3055c
MD5 32f1231de14f3c213734d050a6ba9033
BLAKE2b-256 0600c57ff9e9f51a7e90a02e8d11b1c664b6d7e0d9b958e36519c94d1dbfd3b3

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page