116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 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.
|