Metadata-Version: 2.4
Name: ps5dbg
Version: 0.1.0
Summary: Cross-platform Python client and CLI for the ps5debug-NG wire protocol on jailbroken PS5 consoles.
Author: Darkatek7
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/Darkatek7/ps5dbg
Project-URL: Repository, https://github.com/Darkatek7/ps5dbg
Project-URL: Issues, https://github.com/Darkatek7/ps5dbg/issues
Keywords: ps5,playstation5,ps5debug,ps5debug-ng,debugger,homebrew,jailbreak
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Dynamic: license-file

# 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.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE)
[![Tests](https://img.shields.io/badge/tests-31%20pass%20%2B%2015%20live-brightgreen.svg)](#testing)
[![Protocol](https://img.shields.io/badge/protocol-v1.3.0-blue.svg)](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/PROTOCOL.md)

`ps5dbg` lets a developer talk to a PS5 running the [ps5debug-NG](https://github.com/OpenSourcereR-dev/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

```bash
# 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](https://github.com/OpenSourcereR-dev/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:**
```bash
$ 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:**
```python
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):
```python
# 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`](./docs/protocol_notes.md) and the upstream [`PROTOCOL.md`](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/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`](./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/`](./examples) for `read_game_memory.py`, `build_a_trainer.py`,
and `watch_foreground.py`.

---

## Acknowledgments

- **[OpenSourcereR-dev/ps5debug-NG](https://github.com/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](https://github.com/ps5-payload-dev)** — the SDK and payload ecosystem that made PS5 homebrew possible.
- **[etaHEN](https://github.com/etaHEN/etaHEN)** — the HEN chain that loads the debugger.

## License

[GPL-3.0-only](./LICENSE) — matching ps5debug-NG, whose wire protocol this library implements.
