picklock 0.1.0__py3-none-any.whl

picklock/__init__.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+"""
+Picklock — a plain-text terminal client for PyMemoryEditor.
+
+Picklock exposes PyMemoryEditor's process introspection, memory scanning and
+read/write features through an interactive shell: ASCII result tables, a
+one-line prompt, no curses, no GUI toolkit, no colour beyond a single
+highlight for errors. It runs anywhere Python does — a desktop, a headless
+server, an SSH session, a CI job.
+
+The package is a *client*: every memory operation is performed by
+PyMemoryEditor, which Picklock depends on but does not vendor.
+"""
+
+__author__ = "Jean Loui Bernard Silva de Jesus"
+__version__ = "0.1.0"
+
+from .errors import CommandError, NoProcessError, PicklockError
+from .session import Session
+from .shell import Shell
+
+__all__ = (
+    "CommandError",
+    "NoProcessError",
+    "PicklockError",
+    "Session",
+    "Shell",
+    "__author__",
+    "__version__",
+)

picklock/__main__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+"""Entry point for ``python -m picklock``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

picklock/addressing.py

@@ -0,0 +1,259 @@
+# -*- coding: utf-8 -*-
+
+"""
+The little address language every command shares.
+
+Anywhere Picklock takes an address it takes an *expression*, so the workflows
+that matter can be typed on one line instead of copied between commands:
+
+===============================  =========================================
+``0x7ffee3a01000`` / ``140...``  a literal, hex or decimal
+``game.exe+0x1234``              a module base plus a static offset (ASLR-proof)
+``"libfoo-1.so"+0x20``           the same, quoted when the name has a ``-``
+``[game.exe+0x1234]+0x10``       read the pointer there, then add ``0x10``
+``[[base+0x8]+0x20]+0x4``        a pointer chain, nested as deep as you like
+``#3``                           the address on row 3 of the last scan
+===============================  =========================================
+
+The grammar is deliberately tiny — brackets, ``+``, ``-`` and the three kinds
+of term above — because an address expression that needs its own manual page
+has stopped being a convenience.
+"""
+
+from typing import TYPE_CHECKING, Any, List, NamedTuple, Optional
+
+from .errors import CommandError
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .session import Session
+
+_IDENT_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.")
+
+#: Token kinds produced by :func:`_tokenize`.
+_NUMBER, _IDENT, _RESULT, _OPEN, _CLOSE, _PLUS, _MINUS = range(7)
+
+
+class _Token(NamedTuple):
+    """One lexeme, with what it looked like and whether a space came first.
+
+    The source text and the spacing are what let a module name containing a
+    hyphen be told from a subtraction: ``_ssl.cpython-311-darwin.so`` is one
+    name, ``game.exe - 0x10`` is a sum.
+    """
+
+    kind: int
+    value: Any
+    source: str
+    spaced_before: bool
+
+
+def _tokenize(text: str) -> List["_Token"]:
+    tokens: List[_Token] = []
+    index = 0
+    length = len(text)
+    spaced = False
+
+    def emit(kind: int, value: Any, source: str) -> None:
+        tokens.append(_Token(kind, value, source, spaced))
+
+    while index < length:
+        char = text[index]
+
+        if char.isspace():
+            index += 1
+            spaced = True
+            continue
+
+        if char == "[":
+            emit(_OPEN, "[", "[")
+            index += 1
+            spaced = False
+            continue
+
+        if char == "]":
+            emit(_CLOSE, "]", "]")
+            index += 1
+            spaced = False
+            continue
+
+        if char == "+":
+            emit(_PLUS, "+", "+")
+            index += 1
+            spaced = False
+            continue
+
+        if char == "-":
+            emit(_MINUS, "-", "-")
+            index += 1
+            spaced = False
+            continue
+
+        if char == "#":
+            index += 1
+            start = index
+            while index < length and text[index].isdigit():
+                index += 1
+            if start == index:
+                raise CommandError("'#' must be followed by a result number, e.g. #3.")
+            emit(_RESULT, int(text[start:index]), text[start - 1 : index])
+            spaced = False
+            continue
+
+        if char in ("'", '"'):
+            end = text.find(char, index + 1)
+            if end == -1:
+                raise CommandError(f"Unterminated {char} in address expression.")
+            emit(_IDENT, text[index + 1 : end], text[index : end + 1])
+            index = end + 1
+            spaced = False
+            continue
+
+        if char.lower() == "0" and text[index : index + 2].lower() == "0x":
+            start = index
+            index += 2
+            while index < length and text[index] in "0123456789abcdefABCDEF_":
+                index += 1
+            try:
+                emit(_NUMBER, int(text[start:index].replace("_", ""), 16), text[start:index])
+                spaced = False
+            except ValueError:
+                raise CommandError(f"{text[start:index]!r} is not a hex number.")
+            continue
+
+        if char in _IDENT_CHARS:
+            start = index
+            while index < length and text[index] in _IDENT_CHARS:
+                index += 1
+            word = text[start:index]
+            # A run of digits is a decimal literal; anything else (including
+            # "game.exe" and "libc.so.6") is a module name.
+            if word.replace("_", "").isdigit():
+                emit(_NUMBER, int(word.replace("_", "")), word)
+            else:
+                emit(_IDENT, word, word)
+            spaced = False
+            continue
+
+        raise CommandError(f"Unexpected character {char!r} in address expression.")
+
+    return tokens
+
+
+class _Parser:
+    """Recursive-descent parser over the token list. One expression per call."""
+
+    def __init__(self, tokens: List[_Token], session: "Session"):
+        self.tokens = tokens
+        self.session = session
+        self.position = 0
+
+    def peek(self, ahead: int = 0) -> Optional[_Token]:
+        index = self.position + ahead
+        if index < len(self.tokens):
+            return self.tokens[index]
+        return None
+
+    def next(self) -> _Token:
+        token = self.peek()
+        if token is None:
+            raise CommandError("Unexpected end of address expression.")
+        self.position += 1
+        return token
+
+    def parse_expression(self) -> int:
+        value = self.parse_term()
+        while True:
+            token = self.peek()
+            if token is None or token.kind not in (_PLUS, _MINUS):
+                return value
+            self.position += 1
+            operand = self.parse_term()
+            value = value + operand if token.kind == _PLUS else value - operand
+
+    def parse_term(self) -> int:
+        token = self.next()
+
+        if token.kind == _NUMBER:
+            return int(token.value)
+
+        if token.kind == _RESULT:
+            return self.session.result_address(int(token.value))
+
+        if token.kind == _IDENT:
+            return self.session.module_base(self._module_name(str(token.value)))
+
+        if token.kind == _OPEN:
+            inner = self.parse_expression()
+            closing = self.next()
+            if closing.kind != _CLOSE:
+                raise CommandError("Missing ']' in address expression.")
+            return self.session.read_pointer(inner)
+
+        raise CommandError("Expected an address, a module name or '[' here.")
+
+    def _module_name(self, name: str) -> str:
+        """Rejoin a module name the tokenizer split on a hyphen.
+
+        A hyphen is a subtraction sign and also a perfectly ordinary character
+        in a library's name — ``_ssl.cpython-311-darwin.so`` is what every
+        Python process is full of. The two are told apart by asking: the pieces
+        are rejoined only while they are written without spaces *and* the
+        result names a module that is actually loaded. So
+        ``game.exe-0x10`` stays a subtraction, because no such module exists,
+        and ``game.exe - 0x10`` never even gets here.
+        """
+        best, consumed = name, 0
+        candidate = name
+        ahead = 0
+
+        while True:
+            minus, part = self.peek(ahead), self.peek(ahead + 1)
+            if minus is None or part is None:
+                break
+            if minus.kind != _MINUS or minus.spaced_before or part.spaced_before:
+                break
+            if part.kind not in (_IDENT, _NUMBER):
+                break
+
+            candidate += "-" + part.source
+            ahead += 2
+            if self.session.knows_module(candidate):
+                best, consumed = candidate, ahead
+
+        self.position += consumed
+        return best
+
+
+def parse_address(text: str, session: "Session") -> int:
+    """Evaluate an address expression against ``session``.
+
+    :raises CommandError: on any syntax error, unknown module, out-of-range
+        result index or unreadable dereference — all of which are the user's
+        to correct, so the shell keeps running.
+    """
+    tokens = _tokenize(text)
+    if not tokens:
+        raise CommandError("Empty address.")
+
+    parser = _Parser(tokens, session)
+    address = parser.parse_expression()
+
+    if parser.peek() is not None:
+        raise CommandError(f"Trailing characters in address {text!r}.")
+    if address < 0:
+        raise CommandError(f"Address expression {text!r} resolved below zero.")
+    return address
+
+
+def parse_int(text: str, what: str = "value") -> int:
+    """Parse a plain integer argument (hex or decimal), not an address."""
+    cleaned = text.strip().replace("_", "")
+    try:
+        if cleaned[:2].lower() == "0x":
+            return int(cleaned, 16)
+        return int(cleaned, 10)
+    except (ValueError, IndexError):
+        raise CommandError(f"{text!r} is not a valid {what}.")
+
+
+__all__ = ("parse_address", "parse_int")

picklock/cli.py

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+
+"""
+The ``picklock`` entry point.
+
+Run bare, it opens the interactive shell. Given commands — with ``-e``, as a
+trailing command line, in a file, or on standard input — it runs them and
+exits with a status, so the same vocabulary works inside a script, an SSH
+session or a CI job:
+
+    picklock                                          # the shell
+    picklock ps:list chrome                           # one command, then exit
+    picklock -p 4242 -e "memory:read game.exe+0x10"   # attach, read, exit
+    picklock -f setup.txt                             # a file of commands
+    echo "ps:list" | picklock                         # a pipe
+"""
+
+import argparse
+import shlex
+import sys
+from typing import List, Optional, Sequence
+
+from . import dependencies
+from .commands import top_level_listing
+from .commands.alias_commands import restore as restore_aliases
+from .commands.session_commands import restore as restore_settings
+from .commands.session_commands import version_report
+from .errors import CommandError, PicklockError
+from .output import Printer
+from .session import Session
+from .shell import Shell
+
+
+def _format_commands() -> str:
+    """The same layered summary the shell's own ``help`` prints.
+
+    Every word you can type first, and nothing below it — rather than all
+    thirty-odd commands at once, which is a wall rather than an answer.
+    """
+    rows = top_level_listing()
+    width = max(len(signature) for signature, _ in rows)
+
+    lines: List[str] = ["picklock commands:", ""]
+    # Four spaces between the columns, as the shell's own listings use.
+    lines += [f"  {signature.ljust(width)}    {summary}" for signature, summary in rows]
+    lines += [
+        "",
+        "Run 'picklock help <command>' for what a command takes, or",
+        "'picklock help' for the topics ('types', 'address', 'scanning').",
+    ]
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="picklock",
+        description=(
+            "A terminal client for PyMemoryEditor: read, write and scan the "
+            "memory of a running process from any shell, on Windows, Linux or "
+            "macOS."
+        ),
+        epilog=_format_commands(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    target = parser.add_argument_group("target")
+    target.add_argument("-p", "--pid", type=int, help="attach to this PID at startup")
+    target.add_argument("-n", "--name", help="attach to this process name at startup")
+    target.add_argument(
+        "-i",
+        "--ignore-case",
+        action="store_true",
+        help="match --name regardless of case",
+    )
+    target.add_argument(
+        "--partial",
+        action="store_true",
+        help="match --name as a substring ('chrome' finds 'chrome.exe')",
+    )
+
+    running = parser.add_argument_group("commands")
+    running.add_argument(
+        "-e",
+        "--execute",
+        action="append",
+        default=[],
+        metavar="COMMAND",
+        help="run a command and exit; repeatable, run in order",
+    )
+    running.add_argument(
+        "-f",
+        "--file",
+        metavar="FILE",
+        help="run the commands in FILE and exit",
+    )
+
+    output = parser.add_argument_group("output")
+    output.add_argument(
+        "--no-color", action="store_true", help="never emit ANSI colour"
+    )
+    output.add_argument(
+        "--no-timing", action="store_true", help="omit the elapsed-time footer"
+    )
+    output.add_argument(
+        "--limit",
+        type=int,
+        metavar="N",
+        help="rows printed per result table (0 for no limit)",
+    )
+    output.add_argument(
+        "-q", "--quiet", action="store_true", help="skip the welcome banner"
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        # The same block the 'version' command prints. Which PyMemoryEditor is
+        # underneath matters as much as which Picklock is on top, and someone
+        # pasting this into a bug report should not have to open the shell to
+        # get the useful half.
+        version=version_report(),
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="a single command to run, e.g. 'picklock ps:list chrome'",
+    )
+    return parser
+
+
+def _startup_lines(options: argparse.Namespace) -> List[str]:
+    """The commands implied by the target flags, run before anything else."""
+    if options.pid is None and options.name is None:
+        return []
+    if options.pid is not None and options.name is not None:
+        raise CommandError("Give --pid or --name, not both.")
+
+    parts = ["ps:open"]
+    if options.pid is not None:
+        parts += ["--pid", str(options.pid)]
+    else:
+        parts += ["--name", shlex.quote(options.name)]
+    if options.ignore_case:
+        parts.append("-i")
+    if options.partial:
+        parts.append("--partial")
+    return [" ".join(parts)]
+
+
+def _batch_lines(options: argparse.Namespace, stdin) -> Optional[List[str]]:
+    """The commands to run non-interactively, or ``None`` for the shell.
+
+    Standard input counts only when it is *not* a terminal: a pipe or a
+    redirect is someone scripting Picklock, while a terminal is someone who
+    typed ``picklock`` and wants the prompt.
+    """
+    lines: List[str] = []
+
+    lines.extend(options.execute)
+
+    if options.command:
+        lines.append(" ".join(shlex.quote(part) for part in options.command))
+
+    if options.file:
+        lines.append(f"source {shlex.quote(options.file)}")
+
+    if lines:
+        return lines
+
+    if not getattr(stdin, "isatty", lambda: True)():
+        return stdin.read().splitlines()
+
+    return None
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Run Picklock. Returns the process exit status."""
+    parser = build_parser()
+    options = parser.parse_args(argv)
+
+    printer = Printer(
+        color=False if options.no_color else None,
+        timing=not options.no_timing,
+    )
+
+    # Before anything touches a process: a PyMemoryEditor below the declared
+    # floor fails later, deep inside a scan, with an error that names a Mach
+    # call rather than the cause.
+    outdated = dependencies.check()
+    if outdated is not None:
+        printer.error(outdated)
+        return 2
+
+    session = Session(printer)
+    shell = Shell(session, printer=printer)
+
+    # The aliases the user defined in an earlier run. Loaded here rather than
+    # in Session, so a Session built in a test or a script touches no files
+    # unless it asks to.
+    dropped = restore_aliases(session)
+    if dropped:
+        printer.note(
+            "Dropped %s, whose command no longer exists: %s."
+            % (
+                "an alias" if len(dropped) == 1 else "some aliases",
+                ", ".join(sorted(dropped)),
+            )
+        )
+
+    # Settings come back too. Restored before --limit is applied, so a flag
+    # given on this run still wins over what was stored on the last one.
+    forgotten = restore_settings(session)
+    if forgotten:
+        printer.note(
+            "Ignored %s no longer recognised: %s."
+            % (
+                "a stored setting" if len(forgotten) == 1 else "stored settings",
+                ", ".join(sorted(forgotten)),
+            )
+        )
+
+    if options.limit is not None:
+        session.set_option("limit", str(options.limit))
+
+    try:
+        startup = _startup_lines(options)
+    except CommandError as error:
+        printer.error(str(error))
+        return 2
+
+    batch = _batch_lines(options, sys.stdin)
+    interactive = batch is None
+
+    try:
+        # A failed --pid/--name is fatal either way: the commands that follow
+        # were written for a target that is not there.
+        for line in startup:
+            if not shell.run_line(line, raise_errors=False):
+                return 1
+
+        if interactive:
+            return shell.interact(banner=not options.quiet)
+
+        try:
+            return shell.run_lines(batch or [], raise_errors=True)
+        finally:
+            session.close()
+
+    except PicklockError as error:
+        printer.error(str(error))
+        return 1
+    except KeyboardInterrupt:
+        printer.clear_progress()
+        printer.write()
+        return 130
+    except BrokenPipeError:  # pragma: no cover - depends on the consumer
+        # 'picklock ps | head' closes the pipe early; that is not an error.
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())