Shane
183012196f
kernel-offset: versioned readiness handshake with nonce challenge and legacy-cookie fallback; host validator enforces the evidence. validate_probe now returns (text, readiness) so the readiness check runs once per probe instead of twice. process-debugger: INT3 software breakpoints with shadowed memory I/O, software-breakpoint step-over, and hardened all-stop breakpoint transactions. Bound the post-disconnect detach-retry loop (DETACH_RETRIES): a poisoned or un-detachable target is left stopped and alive for manual recovery instead of spinning and flooding the log forever. Bound the credential-restore loop (CREDENTIAL_RETRIES) and exit afterward so process teardown drops the elevated ucred instead of leaking it under an endless retry. host: session-health classifier, connect-failure classification in send_payload, plus readiness-resident tests and docs.
PS5 Homebrew Tools
Console diagnostics and host utilities for PS5 homebrew development. Watch processes during an app launch, capture thread records, and inspect logs from an instrumented kstuff resident.
Status: source collection and local build tooling, based on PS5 Pro firmware 13.60 research. All included payloads compile locally; the standalone builds and native app still need console validation. See compatibility and validation results before running them.
Features
Choose a tool for the question you want to answer:
| Tool | Use it to |
|---|---|
| Kernel offset backend | Resolve checked kernel offsets and inspect the exec-join bytes; execution control unfinished, no console validation |
| Process debugger | Attach by PID, inspect registers/memory, step instructions, and set hardware execution breakpoints; partial console validation |
| Process snapshot | Take one snapshot of shell and app-related processes |
| Process watch | Watch process births, disappearances, and zombie transitions over three minutes |
| Resident snapshot | Read three snapshots of counters and event rings from a matching instrumented kstuff resident |
| Thread probe v1 | Capture raw sysctl records and check which selectors are available |
| Thread probe v2 | Capture selected processes' kernel thread records on firmware 13.60, SoC 0x840fd0 |
| Kernel capture and capture export | Collect and transfer a bounded kernel-text capture on the matching PS5 Pro 13.60 setup |
| Native app starter | Build a controller, logging, and notification app folder and ZIP |
The host utilities send payloads, preserve raw output, and provide log decoding, binary analysis, and thread summaries. The minimal payload template provides a starting point for your own diagnostic.
Historical resident variants—xlog, rdlog, xin, xslot, and xapp—are documented in Resident experiments. Recovered patches are archived there; resident builds are not included in the tool targets.
Installation
You need Python 3.9+, Make, the public
PS5 Payload SDK, and LLVM 18. Newer LLVM
releases produce different payload bytes, so the build refuses them. Python
utilities use the standard library. Follow the build guide for
SDK and LLVM configuration, or run make container-build with Docker for the
pinned reproducible build.
From a checkout or extracted source directory:
export PS5_PAYLOAD_SDK=/path/to/ps5-payload-sdk
make process-snapshot process-watch
Built ELF files appear in out/. Use make all to build every included payload,
including the starter template; make bundle packages them with source and hashes. Builds do not upload or run anything on the
console. Prebuilt downloads and an automatic console installer are not yet
provided.
Usage
Your console must already have a working homebrew environment and a reachable
ELF loader. Replace the address below with your console's address; the sender
uses port 9021 by default.
Take a process snapshot
export PS5_HOST=your-console-address
mkdir -p captures
python3 host/send_payload.py out/process-snapshot.elf \
--host "$PS5_HOST" --log captures/process-snapshot-001.log
Look for shellshot: ready, the process records, and
shellshot: complete procs=.... Received output is displayed in the terminal and
saved to the log.
Watch an app launch
python3 host/send_payload.py out/process-watch.elf \
--host "$PS5_HOST" --idle-timeout 240 --log captures/process-watch-001.log
Wait for the baseline before opening the app. The watch runs for 180 seconds and
ends with procwatch: complete births=... deaths=....
Use a new log filename for every run. The sender sends once and never retries.
Its exit status describes the host connection; check the payload's output for
completion. A timeout can leave the payload running. After a failed connect,
the sender pings once and records a session class; host/session_health.py
classifies ping vs a send that already ran and never opens port 9021. See the
host reference and
black-session classes.
Documentation
- Getting started — first build, capture, and result check.
- Build reference — SDK configuration, targets, and bundles.
- Native app, capture tools, log tools, and analysis tools.
- Troubleshooting — build failures, connection issues, and incomplete captures.
- Documentation index — all tool guides, architecture, compatibility, and source provenance.
- Context7 guide — index these docs for coding agents.
Development
make help # List build and test targets
make check # Run host tests without an SDK or console
make native-check # Rebuild the native runtime and verify pinned checksums
Continuous integration runs both checks on Linux and macOS for every push and pull request; it never builds payloads or contacts a console. Generated binaries and local captures are ignored by Git. To start a new tool, copy the minimal payload template; it builds independently of this repository.
Contributing
See Contributing for adding tools, documenting compatibility, and recording verification. Preserve source identities and distinguish build results from console testing.
License
New repository code and diagnostics carrying GPL notices use GPL-3.0-or-later; see COPYING. Imported files retain their own notices. The third-party notices cover the BSD header and the imported kstuff files' licensing status.