ps5dbg 0.1.1

Cross-platform Python client and CLI for the ps5debug-NG wire protocol on jailbroken PS5 consoles.

ps5dbg

A cross-platform Python client and CLI for the ps5debug-NG wire protocol on jailbroken PS5 consoles. Speak to your console from any OS — build trainers, debuggers, and tooling on a clean library instead of reimplementing the protocol.

ps5dbg lets a developer talk to a PS5 running the ps5debug-NG command payload (the debugger that lives in SceShellCore and listens on port 744). It implements the full v1.3.0 wire protocol — process inspection, memory scanning, kernel R/W, software & hardware breakpoints, live disassembly/assembly, and console control — and exposes it as both an importable Python library and a ps5dbg command-line tool.

It runs anywhere Python 3.10+ runs (Linux, macOS, Windows) with zero runtime dependencies.

---

Why it exists

Every reusable client for the ps5debug/ps5debug-NG protocol today is C# / .NET, Windows-oriented, and predates the v1.3.0 protocol additions — the canonical reference (Ctn's PS4DBG.cs) has been dormant since 2023. Mac and Linux users who want to scan memory or apply trainers over this protocol have no working open tool.

ps5dbg fills that gap: a clean, tested, dependency-free Python implementation of the full v1.3.0 protocol — framing, bit-swapped status words, the xorshift-128 auth handshake, the turbo-scan family, kernel R/W, breakpoints, and the port-755 async interrupt channel. It's the foundation that makes a cross-platform scanner GUI or unified toolbox feasible later.

---

Install

# when published
pip install ps5dbg
# or
pipx install ps5dbg

# from source (development)
git clone https://github.com/Darkatek7/ps5dbg.git
cd ps5dbg
pip install -e ".[dev]"

Requires a PS5 running ps5debug-NG and reachable on your LAN. Set the address via --host/--port or the PS5_HOST/PS5_PORT env vars (default unset).

---

Quick start

CLI:

$ ps5dbg ping
ps5debug-NG v1.3 (ps5debug-NG by OSR v1.3.0)  FW=5.50  rtt=3ms

$ ps5dbg procs
PID    NAME
  0    kernel
  1    init
...
 47    SceShellCore
 91    eboot.bin             # the foreground game

$ ps5dbg read 91 0x0000004b3a8c0000 16 --hex
4b3a8c0000  7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00

$ ps5dbg notify "hello from ps5dbg"

Library:

from ps5dbg import PS5Debug

with PS5Debug("192.168.1.10") as ps5:
    print(ps5.fw_version())              # 550
    print(ps5.branding().brand)          # 'ps5debug-NG by OSR v1.3.0'
    for p in ps5.procs():
        print(f"{p.pid:4d}  {p.name}")
    data = ps5.read(pid=91, addr=0x4b3a8c0000, length=16)

Build a trainer in a few lines (full scan API lands with v0.1):

# pseudo — see examples/build_a_trainer.py once scan lands
with PS5Debug("192.168.1.10") as ps5:
    fg = ps5.foreground_app()
    hits = ps5.scan_aob(fg.pid, addr, length, pattern=b"\x01\x00\x00\x00", mask=b"\xff\xff\xff\xff")
    ps5.write(fg.pid, hits[0], (999).to_bytes(4, "little"))   # risky: needs --yes-equivalent in CLI

---

Features

Full coverage of the ps5debug-NG v1.3.0 command surface:

Area	What you can do
Info / ping	protocol version, firmware version, branding, platform id, liveness NOP
Processes	list, memory read/write (auto-chunked past 1 MiB), write-multi, VM maps, metadata (name/path/titleId/contentId), alloc/free, RPC function call (6 SysV args), ELF load (run or RPC), mprotect, foreground-app detect
Memory scanning	one-shot value scan, AOB + multi-AOB, iterative trio (START/COUNT/GET, auth-gated), turbo scan family (SIMD compare, server-resident sets, snapshot, aliasing, parallel) with capability detection + automatic fallback to the iterative trio
Kernel	kernel base, arbitrary kernel memory read/write
Disasm / asm	server-side Zydis region disassembly, RIP-relative xref extraction, xrefs-to-target, server-side RBP-chain stack walk, server-side Keystone x86-64 assembly
Debugger	attach/detach, up to 30 software breakpoints, up to 4 hardware watchpoints, full register access (GP/FPU+YMM/debug/FS-GS base), thread list/suspend/resume, continue/stop/step, async interrupt packets via the port-755 outbound channel
Console	reboot, on-screen notification, kernel-console print
Discovery & logs	UDP 0xFFFFAAAA discovery to find consoles without hardcoding IPs, kernel-log tailer (port 9081)

---

CLI reference

ps5dbg [--host H] [--port P] [--json] SUBCOMMAND

Connection / info:
  ping                         NOP round-trip + fw version
  version                      protocol version + branding + fw + platform id
  discover                     UDP broadcast, list responding consoles
  klog [-f]                    tail kernel log (port 9081)
  notify "<text>"              on-screen toast
  reboot                       (confirm required)

Process & memory:
  procs                        process list
  fg                           foreground app
  info <pid>                   name/path/titleid/contentid
  maps <pid>                   VM maps
  read  <pid> <addr> <len> [--hex|--bytes|--ascii]
  write <pid> <addr> <hex|@file>          (--yes required)
  write-multi <pid> <addr>:<hex> ...      (--yes required)
  alloc <pid> <len>
  free  <pid> <addr> <len>

Kernel:
  kbase                        kernel base address
  kread  <addr> <len>
  kwrite <addr> <hex|@file>                (--yes required)

Reverse engineering:
  disasm <pid> <addr> <len>    server-side Zydis
  asm "<text>" [--base 0x..]   server-side Keystone
  stack <pid> [<rbp> <rsp>]    server-side stack walk

Scanning:
  scan value <pid> <addr> <len> <type> <cmp> <value>
  scan aob   <pid> <addr> <len> <pattern> [--mask ..]
  scan start|count|get <pid> ...   (iterative, auth-gated)
  scan turbo ...                    (caps-detected)

Debugger:
  dbg attach <pid>
  dbg threads
  dbg regs <lwpid>
  dbg bp <index> <addr>
  dbg wp <index> <addr> <len> <rw>
  dbg continue|stop|step
  dbg detach

Use --json on any subcommand for machine-readable output. Mutating/risky commands (write, kwrite, reboot, protect, load_elf, attach) require --yes or an interactive confirm.

---

Protocol coverage

ps5dbg implements every opcode in the ps5debug-NG v1.3.0 table (66 commands across the info / process / debug / kernel / console namespaces). Notes on the non-obvious bits:

• Status words are bit-swapped on the wire (adjacent even/odd bits swapped). CMD_SUCCESS arrives as 0x80000000. The library handles this internally; you compare against ps5dbg.Status.SUCCESS.
• 1 MiB max body — read, write, and load_elf auto-chunk transparently.
• Auth handshake (CMD_PROC_AUTH) uses an xorshift-128 keystream seeded [200,300,400,500]; ps5dbg runs it for you and sets the scan-enabled bit.
• Turbo scan is capability-detected via CMD_PROC_TURBOSCAN_CAPS with automatic fallback to the iterative trio when the server predates it.
• Debugger interrupts arrive over a separate TCP channel (port 755, PS5 dials out) as 1184-byte packets; ps5dbg runs a background listener and surfaces them via callback/queue.

Full protocol notes and gotchas: see docs/protocol_notes.md and the upstream PROTOCOL.md.

---

Requirements & compatibility

• Python 3.10 or newer. No runtime dependencies.
• OS any (Linux / macOS / Windows).
• Console any PS5 running ps5debug-NG v1.x (the library targets v1.3.0). Verified against FW 5.50.

---

Roadmap

• v0.1 — full protocol coverage ✅ (this release: all 66 opcodes across info/process/scan+turbo/kernel/disasm/asm/debugger/console/discovery/klog)
• v0.2 — memory-scanner GUI on top of ps5dbg (cross-platform "Cheat Engine for PS5")
• v0.3 — unified PC toolbox (klog tail + elfldr deploy + ps5dbg control + PKG install + console discovery in one app)

Contributions welcome — see AGENTS.md for architecture and conventions.

Testing

pytest                       # unit tests (anywhere; no PS5 needed)
pytest -m live               # + live tests against PS5_HOST (default unset; set PS5_HOST)
pytest -m live --risky --yes # + risky live tests (notify, debug attach) — be prepared to reboot

Unit tests cover: bitswap involution, status-code mapping, framing layout, opcode top-byte, interrupt-packet parsing, GP-register indexing. Live tests exercise the real console on safe ops (ping, version, procs, maps, read, kern_base, AOB scan, turbo scan resident round-trip). No test ever reboots the console. The debug-attach test is gated behind --risky because attaching to SceShellCore can freeze the system UI.

See examples/ for read_game_memory.py, build_a_trainer.py, and watch_foreground.py.

---

Acknowledgments

• OpenSourcereR-dev/ps5debug-NG — the debugger payload and the definitive PROTOCOL.md this library implements.
• Ctn — the original ps5debug, whose wire protocol ps5debug-NG extends and which this library remains compatible with.
• ps5-payload-dev — the SDK and payload ecosystem that made PS5 homebrew possible.
• etaHEN — the HEN chain that loads the debugger.

License

GPL-3.0-only — matching ps5debug-NG, whose wire protocol this library implements.