From bbb25074c492676b2fb1f13490da281a20c3c4f3 Mon Sep 17 00:00:00 2001 From: kadinho Date: Tue, 29 Sep 2026 13:34:44 +0100 Subject: [PATCH] Add agent instructions and project handoff --- AGENTS.md | 115 ++++++++++++++++++++++++++ README.md | 7 +- docs/HANDOFF.md | 215 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 335 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/HANDOFF.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d2a4b23 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,115 @@ +# AGENTS.md + +## Scope + +These instructions apply to the complete `relapse-exploit-docker` repository. +Treat this repository as the primary workspace for all future work related to the +Docker packaging, deployment, PS5 usage documentation, and operational support. + +Read `docs/HANDOFF.md` and `docs/PS5_SETUP.md` before making changes. + +## Purpose + +This repository packages the upstream PS5 Relapse Exploit as a small, hardened +container. The upstream source is the `app` Git submodule. The wrapper must serve +only the files required by the exploit and must verify the executable payloads +before including them in an image. + +## Repository layout + +- `app/`: upstream Relapse Exploit submodule; do not edit it as ordinary wrapper code. +- `Dockerfile`: runtime image and payload-integrity checks. +- `compose.yaml`: hardened local deployment. +- `docker/server.py`: static HTTP server and security headers. +- `payloads.sha256`: approved payload digests for the pinned submodule commit. +- `docs/PS5_SETUP.md`: user and operator guide. +- `docs/HANDOFF.md`: current infrastructure state and durable session handoff. + +## Working rules + +1. Preserve the separation between this wrapper and the upstream `app` submodule. +2. Do not update the submodule or payload hashes implicitly. An upstream update + requires explicit review of source changes and binary payloads. +3. Never weaken or bypass a payload checksum failure merely to make a build pass. +4. Keep `.git`, credentials, environment files, documentation, and development + metadata outside the runtime image. +5. Preserve non-root execution, read-only runtime filesystem, dropped capabilities, + and `no-new-privileges` unless a documented requirement proves otherwise. +6. Do not expose the service or PS5 payload ports to the public Internet. +7. Do not add secrets to the repository. Use local environment/configuration for + any future credentials. +8. Keep instructions in `docs/HANDOFF.md` current whenever deployment topology, + ports, remotes, submodule commit, or operational procedures change. +9. Use `kadinho ` as the repository-local Git identity. + Do not change global Git configuration. + +## Required validation + +For documentation-only changes: + +```sh +git diff --check +docker compose config +``` + +For runtime, Dockerfile, Compose, server, submodule, or payload changes: + +```sh +git submodule status +(cd app && sha256sum -c ../payloads.sha256) +docker compose config +docker compose build +``` + +Then perform a disposable smoke test and verify: + +- `/` returns HTTP 200; +- JavaScript is served as `text/javascript`; +- `.elf` and `.bin` are served as `application/octet-stream`; +- `/.git/config` returns 404; +- the process runs as UID/GID `65532:65532`; +- the configured security headers remain present. + +Do not leave smoke-test containers running. + +## Git and publishing + +The primary branch is `main`. The normal push remote is: + +```text +gitea@192.168.20.20:TinyBacklog/relapse-exploit-docker.git +``` + +The public read-only clone URL used by deployment hosts is: + +```text +http://192.168.20.20:3000/TinyBacklog/relapse-exploit-docker.git +``` + +Before committing, inspect the diff and confirm the worktree contains no generated +files. After pushing, synchronize the deployment only when the requested change is +intended for the live host. + +## Deployment + +The current deployment is documented in `docs/HANDOFF.md`. It runs on +`net-utils01` from `/opt/relapse-exploit-docker` and is reachable on the LAN at +`http://192.168.20.30:8000/`. + +Use fast-forward-only pulls: + +```sh +ssh net-utils01 +cd /opt/relapse-exploit-docker +git pull --ff-only +git submodule update --init --recursive +``` + +Documentation-only changes do not require an image rebuild. Runtime changes require: + +```sh +docker compose up -d --build +docker compose ps +``` + +Verify health and HTTP access after every live deployment. diff --git a/README.md b/README.md index 06db1d3..7d85257 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,11 @@ Use this only on consoles you own or are authorized to test. The exploit can pan the console, corrupt kernel state, expose administrative services, and execute arbitrary code with elevated privileges. -For the complete PS5, DNS, deployment, operation, and troubleshooting guide, see -[docs/PS5_SETUP.md](docs/PS5_SETUP.md). +Documentation: + +- [PS5 setup, DNS, deployment, and troubleshooting](docs/PS5_SETUP.md) +- [Maintainer and agent handoff](docs/HANDOFF.md) +- [Repository instructions for coding agents](AGENTS.md) ## Clone and build diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..3b5b91f --- /dev/null +++ b/docs/HANDOFF.md @@ -0,0 +1,215 @@ +# Maintainer and agent handoff + +Last updated: 2026-09-29 + +This file is the durable handoff for future sessions. Start work from this +repository rather than from the upstream Relapse Exploit checkout. + +## Current status + +The Docker wrapper has been created, committed, pushed to the local Gitea, and +deployed successfully. The user confirmed that the exploit worked on the PS5 and +that opening the PS5 User Guide reached an exploit page directly. + +The exact destination selected by the external DNS was not independently verified. +Do not assume that the User Guide page came from the local container merely because +it displayed Relapse. The local container is confirmed at the raw IP URL below. + +## Repositories + +Primary local workspace: + +```text +/var/www/code/others/relapse-exploit-docker +``` + +Gitea push remote: + +```text +gitea@192.168.20.20:TinyBacklog/relapse-exploit-docker.git +``` + +Gitea public clone URL: + +```text +http://192.168.20.20:3000/TinyBacklog/relapse-exploit-docker.git +``` + +Upstream submodule: + +```text +https://github.com/ntfargo/Relapse-Exploit.git +``` + +Pinned upstream commit: + +```text +09f10f5b58fab8a9ae9e8df214da37271290b13e +``` + +Repository-local Git identity: + +```text +kadinho +``` + +## Live deployment + +- host: `net-utils01`; +- host IP: `192.168.20.30`; +- SSH user used during setup: `root`; +- checkout: `/opt/relapse-exploit-docker`; +- service URL: `http://192.168.20.30:8000/`; +- image name: `relapse-exploit:local`; +- Compose service: `relapse-exploit`; +- container name generated by Compose: + `relapse-exploit-docker-relapse-exploit-1`; +- host port: `8000/TCP`; +- container port: `8080/TCP`; +- restart policy: `unless-stopped`. + +Port `8080` on the host is already used by `unifi-network-application`; do not move +this service there. At the last verification, the Relapse container was healthy, +ran as `65532:65532`, used a read-only root filesystem, and returned HTTP 200 over +the LAN. `/.git/config` returned 404. + +No firewall management tool was detected on `net-utils01` during setup. + +## Deployment authentication detail + +`net-utils01` does not currently have a Gitea SSH client key authorized for cloning. +The deployment clone therefore uses the public HTTP URL. Do not copy personal SSH +private keys to the server or enable SSH agent forwarding as a workaround. If write +or authenticated access becomes necessary, create a repository-scoped deploy key. + +The Gitea server's SSH fingerprints were compared with the already trusted local +host before its host keys were added to `/root/.ssh/known_hosts` on `net-utils01`. + +## Runtime design + +The image is based on `python:3.14-alpine` and uses only Python's standard library. +It copies these upstream assets into `/srv/public`: + +- `index.html`; +- `src/`; +- `offsets/`; +- `payloads/`. + +The build validates every payload listed in `payloads.sha256`. The server disables +directory listing and caching, sends restrictive browser headers, and runs under +numeric UID/GID 65532. Compose additionally makes the root filesystem read-only, +drops all Linux capabilities, and enables `no-new-privileges`. + +The base image tag is not digest-pinned in the Dockerfile. A prior successful build +resolved `python:3.14-alpine` to: + +```text +sha256:9e9fde4d32eedce0b661d9ab91e826b62dddf28e928c230ec55f1866cac66b01 +``` + +Treat that as historical build information, not as an instruction to pin it without +checking architecture support and update policy. + +## Approved payload hashes + +At the pinned upstream commit: + +```text +de5dd480d12637527ba2d75e35de851adbb59c455293fa32588c492ef6b44b81 payloads/elfldr-ps5-1360.elf +26034dfbb88dd8be344fee1876c387bfcba0386edb079014e18ec25580368f6d payloads/etaHEN.elf +7cfb3a8cb86db67893c360ae3531f460f800e9f24039797038e6e81fc50f18a9 payloads/kexp_2026_05_25.bin +858880a8adbedaabfaced025384f4f6f908cfe44f1a049070ad8df911c22b972 payloads/kstuff.elf +0b30a1c23b83ebb2aa6523c8caaa5801ee89bde00e90cb36f392a29bb0bdb403 payloads/shadowmountplus.elf +``` + +The payloads are precompiled, stripped binaries. Hash matching proves consistency +with the reviewed snapshot; it does not prove that the binaries are safe. + +## PS5 and DNS state + +The local HTTP endpoint is available and verified at: + +```text +http://192.168.20.30:8000/ +``` + +The upstream project recommends public primary DNS `45.56.67.85`. The user reported +successful access through the User Guide. No DNS container was installed on +`net-utils01`, and this repository's Compose publishes no DNS service. + +A local DNS service and an HTTP/HTTPS reverse proxy for the PS5 User Guide are +possible future improvements, but must be designed separately. DNS only maps names +to IP addresses; it cannot redirect the User Guide from ports 80/443 to port 8000. +Before binding ports 53, 80, or 443 on `net-utils01`, inspect for conflicts and agree +on the desired DNS forwarding and logging policy. + +Full PS5 instructions and DNS options are in `docs/PS5_SETUP.md`. + +## Common operations + +Inspect the live service: + +```sh +ssh net-utils01 +cd /opt/relapse-exploit-docker +docker compose ps +docker compose logs -f +``` + +Synchronize documentation-only changes: + +```sh +cd /opt/relapse-exploit-docker +git pull --ff-only +git submodule update --init --recursive +``` + +Deploy runtime changes: + +```sh +cd /opt/relapse-exploit-docker +git pull --ff-only +git submodule update --init --recursive +docker compose up -d --build +docker compose ps +curl -I http://127.0.0.1:8000/ +``` + +Stop or restart: + +```sh +docker compose down +docker compose up -d +# or +docker compose restart +``` + +## Known risks and review findings + +The upstream project deliberately exploits WebKit and the PS5 kernel, escalates the +browser process to root, escapes its sandbox, and executes ELF payloads. + +Important upstream findings from the initial static review: + +1. Payloads are executable privileged binaries without upstream signature + verification or reproducible-build evidence. +2. The AIO cleanup path marks groups as defused even when cleanup reports failure, + which can leave risky kernel state behind. +3. Some early kernel failures return a result that the UI can misreport as root and + sandbox escape success. +4. The ELF loader on port 9021 is an arbitrary-payload interface by design. +5. ShadowMount+ includes an HTTP/JSON administration API; keep it on loopback or a + trusted LAN and never expose it publicly. + +The wrapper's checksum and container hardening mitigate host-side packaging risks; +they do not correct these upstream kernel or payload risks. + +## Next-session checklist + +1. Read this file, `AGENTS.md`, and `docs/PS5_SETUP.md`. +2. Run `git status --short --branch` and `git submodule status`. +3. Confirm the requested task's scope before changing the upstream submodule. +4. Preserve the payload-integrity and container-hardening invariants. +5. Validate proportionally to the change. +6. Update this handoff if infrastructure or operational state changes. +7. Push `main` to Gitea and, when appropriate, synchronize `net-utils01`.