hisstrace 2026.10.28__tar.gz

hisstrace-2026.10.28/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Aivars Kalvans <aivars.kalvans@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hisstrace-2026.10.28/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: hisstrace
+Version: 2026.10.28
+Summary: Programmable syscall interception and fault injection in Python. strace, with fangs.
+Author-email: Aivars Kalvans <aivars.kalvans@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aivarsk/hisstrace
+Keywords: ptrace,strace,tracing,syscall,debugger
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Hisstrace
+
+Programmable syscall interception and fault injection in Python.
+
+**strace, with fangs.**
+
+Pure stdlib, no dependencies. Pure Python ptrace bindings, 64-bit x86 and ARM.
+
+## Install
+
+```bash
+pip install hisstrace
+```
+
+## What works
+
+- ptrace(2) via ctypes: no C extensions, no dependencies;
+- syscall number/name tables for x86-64 and AArch64, generated from kernel headers;
+- per-architecture register access (x86-64 uses GETREGS, AArch64 uses GETREGSET);
+- tracee memory reads and writes, plus `Tracer.exe_image()` / `Tracer.exe_vaddr()`
+  for byte-signature scans of the executable, stripped binaries included;
+- a `Tracer` that spawns a command or attaches to a pid and iterates syscall
+  stops as entry/exit events;
+- thread tracing: every thread is followed automatically, including threads
+  created later (PTRACE_O_TRACECLONE);
+- child processes are opt-in: `await on.fork()` surfaces each new process,
+  and `child.follow()` decides to trace it (the default is to let it run free);
+- attach to a running process and all its threads by pid (`-p`), following
+  threads spawned after the attach;
+- software breakpoints inside the tracee: `Tracer.set_breakpoint(addr)` arms
+  an int3, the stop surfaces as a `Trap` event with live registers, and the
+  original instruction is single-stepped and re-armed for you;
+- argument mutation at entry: on a pre-match, `call.overwrite(count=1)`
+  rewrites named argument registers before the kernel runs the call (names
+  come from the syscall table), and the matching post-match sees the new
+  values;
+- `hisstrace run CMD [ARGS...]`: a strace-style printer, built from the
+  scenario API like everything else.
+
+Events carry raw register values: six unsigned arguments at entry, the raw
+return register at exit.
+
+## Scenarios
+
+A scenario is one coroutine driven by syscall events:
+
+```python
+from hisstrace import post, pre
+
+async def scenario():
+    done = await post.read(count=100)  # completion of the next matching read
+    print(f"read: {done.data!r} (retval {done.retval})")
+
+    call = await pre.write()  # next write stops before it enters the kernel
+    print(f"write: {call.data!r}")
+```
+
+Run it against a command:
+
+```bash
+hisstrace scenario examples/capture.py -- python3 -c "..."
+```
+
+`examples/httpforever.py` prints curl's entire HTTP conversation with
+httpforever.com, request bytes marked `->` and response bytes `<-`, by
+finding the TCP socket on port 80 and watching `sendto`/`recvfrom` on it.
+`examples/byte_by_byte.py` takes the idea one step further: it rewrites the
+size argument of every socket read and write to 1 (`call.overwrite` for
+count-style calls, one poke inside the msghdr for `recvmsg`/`sendmsg`), so
+the kernel moves the whole conversation one byte per syscall, and it tracks
+happy-eyeballs connection churn, forked transfers, and fd reuse to do it.
+`examples/watch_conn.py` traces a full SSH round of a Go client (socket
+traffic across its thread handoff plus every getrandom, ending when the
+connection closes); `examples/ssh_handshake.py` parses that same traffic into
+the SSH handshake (KEXINIT algorithm lists, negotiation, ECDH, NEWKEYS);
+`examples/ssh_decrypted.py` goes the last mile: it plants a breakpoint on
+`crypto/ecdh.x25519ScalarMult` inside the process, recovers the X25519 shared
+secret from the trap's registers, derives the session keys, and decrypts the
+whole session in pure Python. `examples/ssh_rng_via_syscall.py` does the same
+decryption with no symbols and no breakpoints at all: a one-byte patch forces
+Go's getrandom off the vDSO and onto the syscall path, the KEX scalar is
+picked out of the syscall stream, and the session decrypts from there (this
+one example needs `pip install cryptography`; hisstrace itself has no
+dependencies).
+
+Or attach to a running process (every thread is traced, and threads spawned
+later are picked up automatically):
+
+```bash
+hisstrace run -p 4242
+hisstrace scenario examples/trackfd.py -p 4242
+```
+
+Contract, v1: one scenario runs at a time. While Python code between awaits
+runs, the matched tracee stays stopped; reaching the next await resumes it.
+Unmatched syscalls pass through unchanged. `post.X` correlates entry and exit
+of one invocation and returns a `CompletedCall` (entry args plus `retval`,
+`error`, `succeeded`, `failed`, and a capped `data` snapshot for read/write).
+`any_of(...)` awaits several matchers and resumes with whichever fires first:
+
+```python
+while True:
+    event = await any_of(post.read(fd=fd), pre.write(fd=fd), pre.close(fd=fd))
+    if event.name == "close":
+        break
+    print(event.name, event.data)
+```
+
+See `examples/trackfd.py` for the full fd-tracking loop. `pre.any()` and
+`post.any()` watch every syscall in that phase, which is all `hisstrace run`
+is: a strace built from the scenario API, with argument names for every
+syscall (generated from kernel prototypes) and C-string reads for pointer
+arguments:
+
+```python
+while True:
+    done = await post.any()
+    print(done.name, dict(done.args), done.retval)
+    # done.string("path") reads a NUL-terminated string at that argument
+```
+
+Child processes are the exception to pass-through: a new process stays frozen
+until the scenario decides. `await on.fork()` delivers it; `child.follow()`
+traces it, otherwise it runs untraced. Threads need no decision, they are
+always followed.
+
+```python
+child = await on.fork()
+child.follow()          # or don't: the child runs free
+print("new process", child.pid, "from thread", child.parent_tid)
+```
+
+When the coroutine returns, a spawned tracee keeps running untraced and
+`run()` waits it out and returns its exit status; an attached tracee is
+detached and `run()` returns 0.
+`data` is `None` for syscalls without a buffer; reads that fail give `b""`.
+Match filters compare against raw kernel argument values, so remember that
+Python adds `O_CLOEXEC` to `os.open` before the kernel sees the flags.
+
+Named arguments come from a table generated out of the kernel's syscall
+prototypes (461 syscalls; `make table` regenerates), with `arg0`..`arg5` as
+the fallback for anything missing, and are also usable as match filters, as
+`count=100` above shows.
+
+## Honest limits
+
+One scenario runs at a time, serially. Argument mutation at entry works via
+`call.overwrite()`, but there is no `call.fail()` or return-value replacement
+yet; the scenario can rewrite what a call asks for, not what the kernel
+answers with. No fd-lifetime tracking: `dup2` aliasing and fd reuse after
+close are invisible to plain `fd=` filters (scenarios track fds themselves,
+as `examples/byte_by_byte.py` does). Attaching to another user's process
+fails with the kernel's `ptrace_scope` error.
+
+## Develop
+
+```bash
+make test    # unittest against src/
+make lint    # ruff + mypy + line counts
+make build   # wheel into dist/
+make table   # regenerate syscall tables from kernel headers
+```

hisstrace-2026.10.28/README.md

@@ -0,0 +1,162 @@
+# Hisstrace
+
+Programmable syscall interception and fault injection in Python.
+
+**strace, with fangs.**
+
+Pure stdlib, no dependencies. Pure Python ptrace bindings, 64-bit x86 and ARM.
+
+## Install
+
+```bash
+pip install hisstrace
+```
+
+## What works
+
+- ptrace(2) via ctypes: no C extensions, no dependencies;
+- syscall number/name tables for x86-64 and AArch64, generated from kernel headers;
+- per-architecture register access (x86-64 uses GETREGS, AArch64 uses GETREGSET);
+- tracee memory reads and writes, plus `Tracer.exe_image()` / `Tracer.exe_vaddr()`
+  for byte-signature scans of the executable, stripped binaries included;
+- a `Tracer` that spawns a command or attaches to a pid and iterates syscall
+  stops as entry/exit events;
+- thread tracing: every thread is followed automatically, including threads
+  created later (PTRACE_O_TRACECLONE);
+- child processes are opt-in: `await on.fork()` surfaces each new process,
+  and `child.follow()` decides to trace it (the default is to let it run free);
+- attach to a running process and all its threads by pid (`-p`), following
+  threads spawned after the attach;
+- software breakpoints inside the tracee: `Tracer.set_breakpoint(addr)` arms
+  an int3, the stop surfaces as a `Trap` event with live registers, and the
+  original instruction is single-stepped and re-armed for you;
+- argument mutation at entry: on a pre-match, `call.overwrite(count=1)`
+  rewrites named argument registers before the kernel runs the call (names
+  come from the syscall table), and the matching post-match sees the new
+  values;
+- `hisstrace run CMD [ARGS...]`: a strace-style printer, built from the
+  scenario API like everything else.
+
+Events carry raw register values: six unsigned arguments at entry, the raw
+return register at exit.
+
+## Scenarios
+
+A scenario is one coroutine driven by syscall events:
+
+```python
+from hisstrace import post, pre
+
+async def scenario():
+    done = await post.read(count=100)  # completion of the next matching read
+    print(f"read: {done.data!r} (retval {done.retval})")
+
+    call = await pre.write()  # next write stops before it enters the kernel
+    print(f"write: {call.data!r}")
+```
+
+Run it against a command:
+
+```bash
+hisstrace scenario examples/capture.py -- python3 -c "..."
+```
+
+`examples/httpforever.py` prints curl's entire HTTP conversation with
+httpforever.com, request bytes marked `->` and response bytes `<-`, by
+finding the TCP socket on port 80 and watching `sendto`/`recvfrom` on it.
+`examples/byte_by_byte.py` takes the idea one step further: it rewrites the
+size argument of every socket read and write to 1 (`call.overwrite` for
+count-style calls, one poke inside the msghdr for `recvmsg`/`sendmsg`), so
+the kernel moves the whole conversation one byte per syscall, and it tracks
+happy-eyeballs connection churn, forked transfers, and fd reuse to do it.
+`examples/watch_conn.py` traces a full SSH round of a Go client (socket
+traffic across its thread handoff plus every getrandom, ending when the
+connection closes); `examples/ssh_handshake.py` parses that same traffic into
+the SSH handshake (KEXINIT algorithm lists, negotiation, ECDH, NEWKEYS);
+`examples/ssh_decrypted.py` goes the last mile: it plants a breakpoint on
+`crypto/ecdh.x25519ScalarMult` inside the process, recovers the X25519 shared
+secret from the trap's registers, derives the session keys, and decrypts the
+whole session in pure Python. `examples/ssh_rng_via_syscall.py` does the same
+decryption with no symbols and no breakpoints at all: a one-byte patch forces
+Go's getrandom off the vDSO and onto the syscall path, the KEX scalar is
+picked out of the syscall stream, and the session decrypts from there (this
+one example needs `pip install cryptography`; hisstrace itself has no
+dependencies).
+
+Or attach to a running process (every thread is traced, and threads spawned
+later are picked up automatically):
+
+```bash
+hisstrace run -p 4242
+hisstrace scenario examples/trackfd.py -p 4242
+```
+
+Contract, v1: one scenario runs at a time. While Python code between awaits
+runs, the matched tracee stays stopped; reaching the next await resumes it.
+Unmatched syscalls pass through unchanged. `post.X` correlates entry and exit
+of one invocation and returns a `CompletedCall` (entry args plus `retval`,
+`error`, `succeeded`, `failed`, and a capped `data` snapshot for read/write).
+`any_of(...)` awaits several matchers and resumes with whichever fires first:
+
+```python
+while True:
+    event = await any_of(post.read(fd=fd), pre.write(fd=fd), pre.close(fd=fd))
+    if event.name == "close":
+        break
+    print(event.name, event.data)
+```
+
+See `examples/trackfd.py` for the full fd-tracking loop. `pre.any()` and
+`post.any()` watch every syscall in that phase, which is all `hisstrace run`
+is: a strace built from the scenario API, with argument names for every
+syscall (generated from kernel prototypes) and C-string reads for pointer
+arguments:
+
+```python
+while True:
+    done = await post.any()
+    print(done.name, dict(done.args), done.retval)
+    # done.string("path") reads a NUL-terminated string at that argument
+```
+
+Child processes are the exception to pass-through: a new process stays frozen
+until the scenario decides. `await on.fork()` delivers it; `child.follow()`
+traces it, otherwise it runs untraced. Threads need no decision, they are
+always followed.
+
+```python
+child = await on.fork()
+child.follow()          # or don't: the child runs free
+print("new process", child.pid, "from thread", child.parent_tid)
+```
+
+When the coroutine returns, a spawned tracee keeps running untraced and
+`run()` waits it out and returns its exit status; an attached tracee is
+detached and `run()` returns 0.
+`data` is `None` for syscalls without a buffer; reads that fail give `b""`.
+Match filters compare against raw kernel argument values, so remember that
+Python adds `O_CLOEXEC` to `os.open` before the kernel sees the flags.
+
+Named arguments come from a table generated out of the kernel's syscall
+prototypes (461 syscalls; `make table` regenerates), with `arg0`..`arg5` as
+the fallback for anything missing, and are also usable as match filters, as
+`count=100` above shows.
+
+## Honest limits
+
+One scenario runs at a time, serially. Argument mutation at entry works via
+`call.overwrite()`, but there is no `call.fail()` or return-value replacement
+yet; the scenario can rewrite what a call asks for, not what the kernel
+answers with. No fd-lifetime tracking: `dup2` aliasing and fd reuse after
+close are invisible to plain `fd=` filters (scenarios track fds themselves,
+as `examples/byte_by_byte.py` does). Attaching to another user's process
+fails with the kernel's `ptrace_scope` error.
+
+## Develop
+
+```bash
+make test    # unittest against src/
+make lint    # ruff + mypy + line counts
+make build   # wheel into dist/
+make table   # regenerate syscall tables from kernel headers
+```

hisstrace-2026.10.28/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hisstrace"
+version = "2026.10.28"
+description = "Programmable syscall interception and fault injection in Python. strace, with fangs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Aivars Kalvans", email = "aivars.kalvans@gmail.com" }]
+keywords = ["ptrace", "strace", "tracing", "syscall", "debugger"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/aivarsk/hisstrace"
+
+[project.scripts]
+hisstrace = "hisstrace.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["hisstrace"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+show_error_codes = true
+check_untyped_defs = true
+
+[tool.ruff]
+line-length = 120

hisstrace-2026.10.28/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hisstrace-2026.10.28/src/hisstrace/__init__.py

@@ -0,0 +1,33 @@
+"""Hisstrace: programmable syscall interception and fault injection in Python.
+
+strace, with fangs.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .arch import current
+from .scenario import CompletedCall, Matcher, any_of, on, post, pre, run, tracer
+from .trace import Child, Event, TraceeExited, Tracer, Trap
+
+try:
+    __version__ = version("hisstrace")  # from the installed package metadata
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "dev"
+
+__all__ = [
+    "Child",
+    "CompletedCall",
+    "Event",
+    "Matcher",
+    "TraceeExited",
+    "Tracer",
+    "Trap",
+    "any_of",
+    "current",
+    "on",
+    "post",
+    "pre",
+    "run",
+    "tracer",
+    "__version__",
+]

hisstrace-2026.10.28/src/hisstrace/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

hisstrace-2026.10.28/src/hisstrace/arch.py

@@ -0,0 +1,128 @@
+"""Syscall register layouts for x86-64 and AArch64.
+
+One Arch class, configured per architecture: register block struct, syscall
+number register, return register, argument registers, and whether register
+access goes through GETREGS (x86-64) or GETREGSET (AArch64).
+"""
+
+import ctypes
+import platform
+
+from . import ptrace
+from .table import TABLES
+
+
+class Amd64Regs(ctypes.Structure):
+    _fields_ = [
+        (name, ctypes.c_ulonglong)
+        for name in (
+            "r15",
+            "r14",
+            "r13",
+            "r12",
+            "rbp",
+            "rbx",
+            "r11",
+            "r10",
+            "r9",
+            "r8",
+            "rax",
+            "rcx",
+            "rdx",
+            "rsi",
+            "rdi",
+            "orig_rax",
+            "rip",
+            "cs",
+            "eflags",
+            "rsp",
+            "ss",
+            "fs_base",
+            "gs_base",
+            "ds",
+            "es",
+            "fs",
+            "gs",
+        )
+    ]
+
+
+class Aarch64Regs(ctypes.Structure):
+    _fields_ = [(f"x{i}", ctypes.c_ulonglong) for i in range(31)]
+    _fields_ += [("sp", ctypes.c_ulonglong), ("pc", ctypes.c_ulonglong), ("pstate", ctypes.c_ulonglong)]
+
+
+class Iovec(ctypes.Structure):
+    _fields_ = [("base", ctypes.c_void_p), ("len", ctypes.c_size_t)]
+
+
+class Arch:
+    """Register access plus the syscall tables for one architecture."""
+
+    def __init__(self, machine, reg_struct, nr_reg, ret_reg, arg_regs, regset, pc_reg):
+        self.machine = machine
+        self._struct = reg_struct
+        self._nr, self._ret = nr_reg, ret_reg
+        self._args = arg_regs
+        self._pc = pc_reg
+        self._regset = regset  # True: GETREGSET/SETREGSET, False: GETREGS/SETREGS
+        self.syscalls = TABLES.get(machine, {})
+        self.names = {name: number for number, name in self.syscalls.items()}
+
+    def get(self, pid):
+        regs = self._struct()
+        if self._regset:
+            iov = Iovec(ctypes.addressof(regs), ctypes.sizeof(regs))
+            ptrace.ptrace(ptrace.GETREGSET, pid, ptrace.NT_PRSTATUS, ctypes.addressof(iov))
+        else:
+            ptrace.ptrace(ptrace.GETREGS, pid, 0, ctypes.addressof(regs))
+        return regs
+
+    def set(self, pid, regs):
+        if self._regset:
+            iov = Iovec(ctypes.addressof(regs), ctypes.sizeof(regs))
+            ptrace.ptrace(ptrace.SETREGSET, pid, ptrace.NT_PRSTATUS, ctypes.addressof(iov))
+        else:
+            ptrace.ptrace(ptrace.SETREGS, pid, 0, ctypes.addressof(regs))
+
+    def number(self, regs):
+        return getattr(regs, self._nr)
+
+    def set_number(self, regs, value):
+        setattr(regs, self._nr, value)
+
+    def args(self, regs):
+        return tuple(getattr(regs, name) for name in self._args)
+
+    def set_arg(self, regs, index, value):
+        setattr(regs, self._args[index], value)
+
+    def retval(self, regs):
+        return getattr(regs, self._ret)
+
+    def set_retval(self, regs, value):
+        setattr(regs, self._ret, value)
+
+    def pc(self, regs):
+        return getattr(regs, self._pc)
+
+    def set_pc(self, regs, value):
+        setattr(regs, self._pc, value)
+
+    def syscall_name(self, number):
+        return self.syscalls.get(number, f"sys_{number}")
+
+
+AMD64 = Arch("x86_64", Amd64Regs, "orig_rax", "rax", ("rdi", "rsi", "rdx", "r10", "r8", "r9"), False, "rip")
+AARCH64 = Arch("aarch64", Aarch64Regs, "x8", "x0", tuple(f"x{i}" for i in range(6)), True, "pc")
+
+_current = None
+
+
+def current():
+    global _current
+    if _current is None:
+        _current = {"x86_64": AMD64, "aarch64": AARCH64}.get(platform.machine())
+        if _current is None:
+            raise RuntimeError(f"unsupported architecture: {platform.machine()}")
+    return _current

hisstrace-2026.10.28/src/hisstrace/cli.py

@@ -0,0 +1,100 @@
+"""hisstrace command line: raw tracing and scenario files."""
+
+import argparse
+import errno
+import sys
+
+from . import __version__
+from .scenario import arg_names, post
+from .scenario import load as load_scenario
+from .scenario import run as run_scenario
+from .trace import signed
+
+# argument names whose values read better as the tracee's string
+PATHLIKE = {"path", "pathname", "filename", "oldname", "newname", "oldpath", "newpath"}
+
+
+def fmt_arg(value):
+    value = signed(value)
+    return str(value) if -0xFFFF <= value <= 0xFFFF else hex(value)
+
+
+def fmt_retval(raw):
+    value = signed(raw)
+    if -4095 <= value <= -1:
+        name = errno.errorcode.get(-value)
+        return f"-1 {name}" if name else str(value)
+    return str(value)
+
+
+def fmt_call(done):
+    parts = []
+    for name, value in zip(arg_names(done.name), done.args.raw):
+        if name in PATHLIKE:
+            text = done.string(name)
+            if text:
+                parts.append(f'{name}="{text}"')
+                continue
+        parts.append(f"{name}={fmt_arg(value)}")
+    suffix = "" if done.tid == done.pid else f"  [tid {done.tid}]"
+    return f"{done.name}({', '.join(parts)}) = {fmt_retval(done.retval)}{suffix}"
+
+
+def run(argv=None, pid=None):
+    """strace, built from the scenario API: watch every syscall completion."""
+
+    async def trace_all():
+        while True:
+            print(fmt_call(await post.any()))
+
+    return run_scenario(trace_all, argv=argv, pid=pid)
+
+
+def strip_ddash(argv):
+    return argv[1:] if argv[:1] == ["--"] else argv
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="hisstrace", description="strace, with fangs.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    run_p = sub.add_parser("run", help="trace a command and print its syscalls")
+    run_p.add_argument("--pid", "-p", type=int, help="attach to a running process and its threads (before CMD)")
+    run_p.add_argument("argv", metavar="CMD", nargs=argparse.REMAINDER)
+    sc_p = sub.add_parser("scenario", help="drive a scenario coroutine against a command")
+    sc_p.add_argument("--pid", "-p", type=int, help="attach to a running process and its threads (before SCENARIO.py)")
+    sc_p.add_argument("file", metavar="SCENARIO.py")
+    sc_p.add_argument("argv", metavar="CMD", nargs=argparse.REMAINDER)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "run":
+            if args.pid:
+                if strip_ddash(args.argv):
+                    parser.error("run takes either --pid or a command, not both")
+                run(pid=args.pid)
+                return 0
+            cmd = strip_ddash(args.argv)
+            if not cmd:
+                parser.error("run needs a command or --pid")
+            run(cmd)
+            return 0
+        if args.pid:
+            if strip_ddash(args.argv):
+                parser.error("scenario takes either --pid or a command, not both")
+            return run_scenario(load_scenario(args.file), pid=args.pid)
+        cmd = strip_ddash(args.argv)
+        if not cmd:
+            parser.error("scenario needs a command or --pid")
+        return run_scenario(load_scenario(args.file), cmd)
+    except PermissionError as exc:
+        sys.exit(
+            f"hisstrace: {exc}\n"
+            "attach was refused: under kernel.yama.ptrace_scope you may trace your own\n"
+            "descendant processes (or run as root). Your shell's other children are off limits."
+        )
+    except KeyboardInterrupt:
+        return 130  # attached traces end with Ctrl-C; the tracee was detached above
+
+
+if __name__ == "__main__":
+    sys.exit(main())