Pymem Documentation

repository·master·Indexed 18 days ago

https://github.com/srounet/pymem

A Python library for manipulating Windows processes, providing tools to interact with process memory and low-level Windows internals. Pymem allows developers to read and write to memory addresses, perform pattern scanning (AOB scanning), and manage processes and threads. It includes specialized modules for memory structures, process lifecycle identification, and exception handling for failed attachments or invalid addresses.

Tokens
5.9K
Snippets
16
Records
27
Agent score
63%

What's inside Pymem

  1. What is Pymem and when to use it

    master

    Pymem is a Python toolbox designed for process memory manipulation. It is primarily used for tasks such as:

    • Reading and writing to process memory.
    • Memory pattern searching.
    • Performing injections.
    • Assembly manipulation (note: support for pyfasm was dropped in 2020 due to x64 incompatibility).

    It is particularly well-suited for reverse engineering games (e.g., writing bots for games like World of Warcraft) and general Windows API-based memory debugging and hooking.

  2. Manage processes and threads

    master

    For low-level process and thread management, use the following modules:

    • Process: Use pymem.process to perform operations related to the target process lifecycle and identification.
    • Thread: Use pymem.thread to interact with and manage threads within the target process.
  3. Work with memory structures and patterns

    master

    Pymem provides specialized modules for advanced memory manipulation:

    • Structures: Use pymem.ressources.structure to work with defined memory layouts and data structures.
    • Pattern: Use pymem.pattern for pattern scanning (AOB scanning) within process memory to find specific byte sequences.
  4. Install Pymem

    master

    Install the core Pymem library using pip. If you require enhanced performance, you can install the optional speedups using the [speed] extra.

    # Standard installation
    pip install pymem
    
    # Installation with speedups
    pip install pymem[speed]
  5. Configure the Python system PATH on Windows

    master

    To use all Pymem functionalities, the system Python directory must be included in your Windows PATH. This ensures the system can access pythonXX.dll.

    1. Open Start Search, type "env", and select Edit the system environment variables.
    2. Click Environment Variables....
    3. Under System Variables, find Path and click Edit.
    4. Click New and add your Python installation path (e.g., C:\Users\xxx\AppData\Local\Programs\Python\Python38).
    5. Close the windows to save changes.
  6. Inject a Python interpreter into a process

    master

    You can inject a Python interpreter into a target process using Pymem.inject_python_interpreter(). This method dynamically locates the correct python.dll for your environment, injects it into the target process, and registers the py_run_simple_string function, allowing you to execute Python code within that process's memory space.

    To execute arbitrary Python code after injection, use Pymem.inject_python_shellcode(shellcode). This method performs the following steps:

    1. Uses VirtualAllocEx to allocate memory in the target process.
    2. Writes your Python code (as a string) into the allocated space.
    3. Executes py_run_simple_string to interpret the code within the target process.
    from pymem import Pymem
    import os
    import subprocess
    
    # 1. Start a target process
    notepad = subprocess.Popen(['notepad.exe'])
    
    # 2. Attach Pymem to the process
    pm = Pymem('notepad.exe')
    
    # 3. Inject the Python interpreter and register py_run_simple_string
    pm.inject_python_interpreter()
    
    # 4. Prepare and inject Python shellcode
    filepath = os.path.join(os.path.abspath('.'), 'pymem_injection.txt')
    filepath = filepath.replace("\", "\\\\")
    shellcode = """
    f = open("{}", "w+")
    f.write("pymem_injection")
    f.close()
    """.format(filepath)
    
    pm.inject_python_shellcode(shellcode)
    
    # 5. Cleanup
    notepad.kill()
  7. Get started with Pymem

    master

    To begin using Pymem, you should follow these steps in order:

    1. Installation: Set up the library in your environment.
    2. Quickstart: Follow the quickstart guide to understand the basic workflow.
    3. Tutorials: For more complex tasks, refer to the tutorials section to learn how to write small software using Pymem.

    Pymem is designed to be lightweight; except for running tests or building documentation, it does not require any external libraries other than ctypes (specifically WinDLL).

  8. Create and activate a Python virtual environment

    master

    Using a virtual environment (via the venv module) isolates Pymem's dependencies from other projects.

    Create an environment

    Linux/macOS:

    $ mkdir myproject
    $ cd myproject
    $ python3 -m venv venv

    Windows:

    $ py -3 -m venv venv

    Activate the environment

    Linux/macOS:

    $ . venv/bin/activate

    Windows:

    > venv\Scripts\activate