TinyBacklog/relapse-exploit-docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add agent instructions and project handoff

Browse Source
This commit is contained in:
kadinho
2026-09-29 13:34:44 +01:00
parent 06300ab793
commit bbb25074c4
3 changed files with 335 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+115
View File
@@ -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 <[email protected]>` 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
[email protected]: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.
README.md
+5 -2
View File
@@ -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
docs/HANDOFF.md
+215
View File
@@ -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
[email protected]: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 <[email protected]>
```
## 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`.