PyMemoryEditor 2.2.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

PyMemoryEditor/__init__.py

@@ -8,7 +8,7 @@ Supported platforms: Windows, Linux and macOS (32-bit and 64-bit).
 """
 
 __author__ = "Jean Loui Bernard Silva de Jesus"
-__version__ = "2.2.0"
+__version__ = "3.0.0"
 
 import logging
 import sys

PyMemoryEditor/linux/functions.py

@@ -32,6 +32,7 @@ from ..util import (
     _validate_pytype,
     as_writable_c_buffer,
     get_c_type_of,
+    sign_extend_narrow_int,
     values_to_bytes,
 )
 from ..util.pattern import PatternLike, compile_pattern
@@ -369,13 +370,23 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
     _validate_pytype(pytype)
 
     data = get_c_type_of(pytype, bufflength)
-    _process_vm_readv(pid, addressof(data), address, sizeof(data))
+    # `bufflength`, not `sizeof(data)`. The two differ whenever the width
+    # rounds up to a wider C type — `int` at 3 bytes gets a `c_int32` — and
+    # passing the buffer size made this backend read 4 bytes where Windows and
+    # macOS read 3, so the same call returned a different value per platform
+    # (0x11223344 here against 0x223344 there). `get_c_type_of` guarantees
+    # `sizeof(data) >= bufflength`, so reading into the front of a larger,
+    # zero-initialised buffer is safe and matches the other two backends.
+    _process_vm_readv(pid, addressof(data), address, bufflength)
 
     if pytype is str:
         return bytes(data).decode("utf-8", errors="replace")
     elif pytype is bytes:
         return bytes(data)
     else:
+        # Narrow widths pad with zeroes, which reads a signed value as
+        # unsigned -- and a scan for the same bytes is signed.
+        sign_extend_narrow_int(data, pytype, bufflength)
         return data.value
 
 
@@ -525,7 +536,12 @@ def write_process_memory(
     data = get_c_type_of(pytype, bufflength)
     data.value = value.encode() if isinstance(value, str) else value
 
-    _process_vm_writev(pid, addressof(data), address, sizeof(data))
+    # `bufflength`, not `sizeof(data)` — this one corrupted memory rather than
+    # merely disagreeing. A write of 3 bytes sized a 4-byte `c_int32` and then
+    # wrote all four, destroying a byte the caller never asked to touch, while
+    # Windows and macOS wrote exactly three. Verified on Linux: `w=3` touched 4
+    # bytes and `w=5` touched 8.
+    _process_vm_writev(pid, addressof(data), address, bufflength)
     return value
 
 

PyMemoryEditor/macos/functions.py

@@ -30,6 +30,7 @@ from ..util import (
     _validate_pytype,
     as_writable_c_buffer,
     get_c_type_of,
+    sign_extend_narrow_int,
     values_to_bytes,
 )
 from ..util.pattern import PatternLike, compile_pattern
@@ -311,6 +312,31 @@ _PAGE_GONE_KRS = (
     KERN_MEMORY_ERROR,
 )
 
+# KERN_PROTECTION_FAILURE is tolerated by a full-address-space *sweep* only,
+# never by a read of caller-supplied addresses — hence a second tuple rather
+# than another entry above.
+#
+# The sweeps walk every region the filter accepted and have no opinion about
+# any single one: a range the kernel declines to hand over is a range with no
+# matches in it, and aborting the whole scan over it loses every region that
+# came after. `search_values_by_addresses` is the opposite case — the caller
+# named those addresses, and its documented `raise_error=True` must still be
+# able to report that one of them could not be read. Anything in the tuple
+# above is swallowed even when `raise_error` is set (see
+# process.scanning.iter_values_for_addresses), so putting kr=2 there would
+# silently turn "permission denied" into the same `(address, None)` the caller
+# gets for an address in a gap.
+#
+# Honest limits of what is known here. This was added because a plain
+# search_by_value over the current process died with kr=2 on GitHub's
+# virtualized macOS runners, on a 22 MB region that reported VM_PROT_READ and
+# Shared=False. The mechanism was not established. It does *not* reproduce
+# locally: probing all 135 scannable regions of a live process yields only kr=1
+# and kr=10, and a page deliberately re-protected to PROT_NONE (or never
+# mapped) answers KERN_INVALID_ADDRESS, not kr=2 — so the usual
+# "protection changed under us" story does not explain it.
+_SWEEP_SKIPPABLE_KRS = _PAGE_GONE_KRS + (KERN_PROTECTION_FAILURE,)
+
 
 class MachReadError(OSError):
     """OSError subclass that carries the underlying kern_return_t."""
@@ -494,6 +520,14 @@ def _is_transient(exc: BaseException) -> bool:
     return isinstance(exc, MachReadError) and exc.kr in _PAGE_GONE_KRS
 
 
+def _is_skippable_by_sweep(exc: BaseException) -> bool:
+    """
+    Same as :func:`_is_transient`, plus the codes only a full-address-space
+    sweep may skip. See :data:`_SWEEP_SKIPPABLE_KRS`.
+    """
+    return isinstance(exc, MachReadError) and exc.kr in _SWEEP_SKIPPABLE_KRS
+
+
 def _query_region(task: int, address: int):
     """Return the region containing `address`, or None when the query fails."""
     addr = mach_vm_address_t(address)
@@ -554,6 +588,9 @@ def read_process_memory(
     elif pytype is bytes:
         return bytes(data)
     else:
+        # Narrow widths pad with zeroes, which reads a signed value as
+        # unsigned -- and a scan for the same bytes is signed.
+        sign_extend_narrow_int(data, pytype, bufflength)
         return data.value
 
 
@@ -683,7 +720,7 @@ def search_addresses_by_value(
         scan_type,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 
@@ -1044,7 +1081,7 @@ def search_addresses_by_pattern(
         length,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 

PyMemoryEditor/mcp/__init__.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+"""
+A Model Context Protocol server for PyMemoryEditor.
+
+Exposes the library's process-memory tools over MCP so an AI assistant can run
+the Cheat Engine loop itself — enumerate processes, attach, scan for a value,
+narrow the matches as the value changes, then read (and optionally write) the
+address it converged on.
+
+Install and run::
+
+    pip install "PyMemoryEditor[mcp]"
+    pymemoryeditor-mcp                 # asks before attaching; writes allowed
+    pymemoryeditor-mcp --read-only     # never modifies a target
+
+Or register it with a client — Claude Code::
+
+    claude mcp add pymemoryeditor -- pymemoryeditor-mcp
+
+...and any client that reads ``mcpServers`` JSON::
+
+    {
+      "mcpServers": {
+        "pymemoryeditor": {
+          "command": "pymemoryeditor-mcp",
+          "args": []
+        }
+      }
+    }
+
+No flags are needed, because consent is asked for where it can actually be
+given: attaching to a process the operator did not pre-approve **asks the
+user**, and every ``write_value`` call is confirmed by their client.
+``--read-only`` drops the write tool entirely, ``--allow-process NAME``
+pre-approves a target so it stops prompting, and ``--allow-any-process`` turns
+prompting off for scripted runs. Read :doc:`the MCP guide </mcp>` before
+pointing it at anything you care about — it runs with your privileges and it is
+**not a sandbox**.
+
+Layout: :mod:`~PyMemoryEditor.mcp.toolset` holds the tools (and imports no MCP
+SDK, so it is testable on its own), :mod:`~PyMemoryEditor.mcp.session` the
+process/scan handles, :mod:`~PyMemoryEditor.mcp.policy` the access rules, and
+:mod:`~PyMemoryEditor.mcp.server` the protocol wiring.
+"""
+
+from .config import ServerConfig, build_parser, parse_args
+from .policy import AccessDecision, ProcessPolicy
+from .server import INSTRUCTIONS, build_server, main
+from .session import ScanResult, Session, SessionError, SessionStore
+from .toolset import MemoryToolset, ToolError
+
+__all__ = (
+    "INSTRUCTIONS",
+    "AccessDecision",
+    "MemoryToolset",
+    "ProcessPolicy",
+    "ScanResult",
+    "ServerConfig",
+    "Session",
+    "SessionError",
+    "SessionStore",
+    "ToolError",
+    "build_parser",
+    "build_server",
+    "main",
+    "parse_args",
+)

PyMemoryEditor/mcp/__main__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+"""``python -m PyMemoryEditor.mcp`` — the same entry point as the console script.
+
+Useful when the console script is not on PATH, which is the usual situation
+when an MCP client launches the server from a virtualenv it did not activate::
+
+    {"command": "/path/to/venv/bin/python",
+     "args": ["-m", "PyMemoryEditor.mcp", "--allow-process", "game.exe"]}
+"""
+
+import sys
+
+from .server import main
+
+if __name__ == "__main__":
+    sys.exit(main())

PyMemoryEditor/mcp/config.py

@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+
+"""
+Command-line configuration for the MCP server.
+
+The server is launched by an MCP *client* (Claude Code, Claude Desktop, an
+editor plugin) from a JSON config file, not by a human at a prompt. The
+operator writes these flags once, months before the model ever calls a tool,
+and nobody is watching stderr when it does — so the defaults are what actually
+governs the server, and they need to be the ones that make it useful *and*
+keep a human in the loop.
+
+Both halves are load-bearing here. The server is a memory **editor**: a
+read-only default made the headline workflow — find a value, change it —
+require a flag nobody discovers, which is a bad trade when the protections that
+matter are elsewhere. Consent is enforced at the two points where it can
+actually be given:
+
+* **which process** — attaching to a target the operator did not pre-approve
+  asks the user, live, and the prompt says whether writes are possible
+  (:mod:`PyMemoryEditor.mcp.policy`);
+* **each write** — ``write_value`` is tagged so a client prompts on every call,
+  even in its most permissive auto-approve mode
+  (see ``_ALWAYS_ASK`` in :mod:`PyMemoryEditor.mcp.server`).
+
+``--read-only`` is there for when you want the guarantee enforced below this
+process rather than promised by it: the write tool is not registered at all, so
+the model never sees it, and on Windows the target is opened with a handle that
+carries no write rights, leaving the kernel to enforce it.
+"""
+
+import argparse
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional, Sequence, Tuple, cast
+
+from .policy import ProcessPolicy
+
+
+#: The transports the MCP SDK can serve this server over. Spelled as a
+#: ``Literal`` because the SDK's ``run()`` is overloaded per transport — a plain
+#: ``str`` matches none of the overloads and fails type checking at the call
+#: site.
+Transport = Literal["stdio", "sse", "streamable-http"]
+
+#: Hard ceiling on the addresses one scan keeps. A first scan for a common
+#: value (``int`` ``0``, ``100``) legitimately matches millions of addresses;
+#: keeping them all would blow out the server's memory for a result set no
+#: refine loop can use anyway. At the cap the scan stops early and says so.
+#:
+#: 100 000 costs 4.2 MB per result set against 2.1 MB, and 21 ms to sort
+#: against 10 ms. The figure that matters is not per set, though: a session
+#: keeps ``MAX_SCANS_PER_SESSION`` (20) of them and a server keeps
+#: ``MAX_OPEN_SESSIONS`` (8) sessions, so the ceiling on retained addresses
+#: goes from ~336 MB to ~672 MB. Reaching it needs 160 capped result sets,
+#: which a long refine chain across several targets can do.
+#:
+#: What it buys: a scan whose true hit count falls between the two ceilings
+#: stops being flagged ``partial``, and refining a truncated set can converge
+#: on an address that was never in it. That case is real but narrow — above
+#: the new ceiling nothing changes, and a common value like ``int 0`` matches
+#: millions and is out of reach at any sane cap.
+#:
+#: What it costs in time depends on the value's density, and an earlier
+#: version of this comment got that wrong. Measured on ``int 0``, reaching
+#: either ceiling took 0.02s against 0.03s — but that is the dense case, where
+#: hits arrive faster than the clock can spend. For a sparser value the scan
+#: has to walk further to collect twice as many hits, so the time roughly
+#: doubles up to the 30-second budget. "Wall clock is unchanged" was true of
+#: one measurement, not of the change.
+DEFAULT_MAX_SCAN_RESULTS = 100_000
+
+#: Wall-clock budget for one scan, in seconds. A full address-space scan of a
+#: large process takes minutes — long past the point where an MCP client gives
+#: up on the request and the model starts retrying. Scans check the budget
+#: between region batches and return a partial, explicitly-flagged result
+#: instead of hanging.
+DEFAULT_MAX_SCAN_SECONDS = 30.0
+
+#: Bytes of target memory one scan batch covers before the deadline is checked.
+#: Value scans only yield on a *hit*, so a rare value produces no yields for
+#: minutes; the only way to stay interruptible is to drive the scan region
+#: batch by region batch and check the clock between them.
+DEFAULT_SCAN_BATCH_BYTES = 64 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    """Everything the server's behaviour depends on.
+
+    :param allow_write: register the memory-mutating tools (``write_value``).
+        **On by default** — editing memory is what the library is for, and each
+        write is confirmed by the client. Set it off with ``--read-only`` when
+        you want the guarantee enforced below this process: the tool then does
+        not exist, and on Windows the process handle carries no write rights.
+    :param allowed_processes: process names pre-approved so they open without
+        prompting — see :class:`~PyMemoryEditor.mcp.policy.ProcessPolicy`.
+        Leaving it empty does **not** mean "anything goes": unlisted targets
+        prompt the user instead.
+    :param allow_any_process: never prompt — open any target the denylist
+        permits. For scripted use, where there is nobody to ask.
+    :param allow_system_processes: lift the system-process denylist.
+    :param max_scan_results: per-scan cap on stored addresses.
+    :param max_scan_seconds: per-scan wall-clock budget.
+    :param scan_batch_bytes: memory covered per deadline check.
+
+    :raises ValueError: if ``max_scan_results``, ``max_scan_seconds`` or
+        ``scan_batch_bytes`` is not positive.
+
+    .. note::
+       The three numeric bounds are validated here as well as in
+       ``parse_args``, so an embedder constructing this in code gets the same
+       answer the CLI operator gets. They used to be checked only at the CLI,
+       which meant a config built in Python failed quietly instead of loudly:
+       ``scan_batch_bytes=0`` made every region its own scan batch (thousands
+       of generator setups per scan on a desktop target), and
+       ``max_scan_results=0`` made every scan return nothing while flagging
+       itself partial. Neither is unsafe — that is why the process allowlist,
+       where a bad value silently disables the consent prompt, was fixed first
+       — but both are indistinguishable from a broken server.
+    """
+
+    allow_write: bool = True
+    allowed_processes: Tuple[str, ...] = field(default=())
+    allow_any_process: bool = False
+    allow_system_processes: bool = False
+    max_scan_results: int = DEFAULT_MAX_SCAN_RESULTS
+    max_scan_seconds: float = DEFAULT_MAX_SCAN_SECONDS
+    scan_batch_bytes: int = DEFAULT_SCAN_BATCH_BYTES
+
+    def __post_init__(self) -> None:
+        # Mirrors the three checks in `parse_args`. Kept as ValueError rather
+        # than `parser.error`: this constructor is library API, and the CLI
+        # already reports its own violations before ever reaching here.
+        if self.max_scan_results < 1:
+            raise ValueError(
+                "max_scan_results must be at least 1 (got %r)." % (self.max_scan_results,)
+            )
+        if self.max_scan_seconds <= 0:
+            raise ValueError(
+                "max_scan_seconds must be positive (got %r)." % (self.max_scan_seconds,)
+            )
+        if self.scan_batch_bytes < 1:
+            raise ValueError(
+                "scan_batch_bytes must be at least 1 (got %r)." % (self.scan_batch_bytes,)
+            )
+
+    def policy(self) -> ProcessPolicy:
+        """Build the :class:`ProcessPolicy` this configuration describes."""
+        return ProcessPolicy(
+            allowed_names=self.allowed_processes,
+            allow_system=self.allow_system_processes,
+            allow_any=self.allow_any_process,
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The ``pymemoryeditor-mcp`` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="pymemoryeditor-mcp",
+        description=(
+            "Expose PyMemoryEditor's process-memory tools over the Model "
+            "Context Protocol, so an AI assistant can run the Cheat "
+            "Engine scan/refine/read loop against a live process."
+        ),
+        epilog=(
+            "Needs no flags: it asks you before attaching to a process, and "
+            "your client confirms every write. Pass --read-only to remove the "
+            "write tool entirely, or --allow-process NAME to skip the attach "
+            "prompt for a target you already trust."
+        ),
+    )
+    parser.add_argument(
+        "--read-only",
+        action="store_true",
+        dest="read_only",
+        help=(
+            "do not register the write tool, so the server can read and scan "
+            "but never modify a target. On Windows the process handle is also "
+            "opened without write rights, so the kernel enforces it."
+        ),
+    )
+    parser.add_argument(
+        "--allow-process",
+        action="append",
+        default=[],
+        metavar="NAME",
+        dest="allowed_processes",
+        help=(
+            "pre-approve processes whose name contains NAME (case-insensitive), "
+            "so attaching to them never prompts. Repeatable. Omitting it does "
+            "not open the server up: unlisted targets ask for your approval at "
+            "the moment they are needed."
+        ),
+    )
+    parser.add_argument(
+        "--allow-any-process",
+        action="store_true",
+        help=(
+            "never ask — open any target the system denylist permits. Use it "
+            "for scripted or non-interactive runs, where no one is there to "
+            "answer a prompt. Interactively, prefer the default: it asks once "
+            "per process and can remember your answer."
+        ),
+    )
+    parser.add_argument(
+        "--allow-system-processes",
+        action="store_true",
+        help=(
+            "lift the built-in denylist of OS/credential processes "
+            "(lsass.exe, launchd, systemd, ...). Rarely what you want."
+        ),
+    )
+    parser.add_argument(
+        "--scan-batch-bytes",
+        type=int,
+        default=DEFAULT_SCAN_BATCH_BYTES,
+        metavar="BYTES",
+        help=(
+            "target memory covered between deadline checks during a scan "
+            "(default: %(default)s). Smaller means a scan gives up closer to "
+            "its time budget, at the cost of more per-batch overhead. The "
+            "field existed and was honoured, but had no flag — so it could "
+            "only be set from Python."
+        ),
+    )
+    parser.add_argument(
+        "--max-scan-results",
+        type=int,
+        default=DEFAULT_MAX_SCAN_RESULTS,
+        metavar="N",
+        help="addresses one scan may keep (default: %(default)s).",
+    )
+    parser.add_argument(
+        "--max-scan-seconds",
+        type=float,
+        default=DEFAULT_MAX_SCAN_SECONDS,
+        metavar="SECONDS",
+        help="wall-clock budget for one scan (default: %(default)s).",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "sse", "streamable-http"),
+        default="stdio",
+        help=(
+            "MCP transport (default: %(default)s). stdio is what desktop "
+            "clients launch; the HTTP transports are for remote hosting and "
+            "expose this machine's memory to whoever can reach the port."
+        ),
+    )
+    return parser
+
+
+def parse_args(
+    argv: Optional[Sequence[str]] = None,
+) -> Tuple[ServerConfig, Transport]:
+    """Parse ``argv`` into a :class:`ServerConfig` and a transport name."""
+    args = build_parser().parse_args(argv)
+
+    if args.max_scan_results < 1:
+        build_parser().error("--max-scan-results must be at least 1.")
+    if args.max_scan_seconds <= 0:
+        build_parser().error("--max-scan-seconds must be positive.")
+    if args.scan_batch_bytes < 1:
+        # 0 or negative makes every region its own batch, so a desktop target
+        # with thousands of regions pays thousands of generator setups per
+        # scan — and the operator would get no error at launch.
+        build_parser().error("--scan-batch-bytes must be at least 1.")
+
+    # Stripped, not merely tested for blankness: a JSON args array carrying
+    # "notepad.exe " (trailing space) used to be stored verbatim, so the
+    # substring matched no process at all — the pre-approval silently did
+    # nothing while the operator kept being prompted.
+    allowed: List[str] = [
+        stripped
+        for stripped in (name.strip() for name in args.allowed_processes)
+        if stripped
+    ]
+
+    config = ServerConfig(
+        allow_write=not args.read_only,
+        allowed_processes=tuple(allowed),
+        allow_any_process=args.allow_any_process,
+        allow_system_processes=args.allow_system_processes,
+        max_scan_results=args.max_scan_results,
+        max_scan_seconds=args.max_scan_seconds,
+        scan_batch_bytes=args.scan_batch_bytes,
+    )
+    # argparse's `choices` already constrains this to the three names; the cast
+    # just carries that guarantee into the type system.
+    return config, cast(Transport, args.transport)
+
+
+__all__ = (
+    "DEFAULT_MAX_SCAN_RESULTS",
+    "Transport",
+    "DEFAULT_MAX_SCAN_SECONDS",
+    "DEFAULT_SCAN_BATCH_BYTES",
+    "ServerConfig",
+    "build_parser",
+    "parse_args",
+)