diff --git a/deploy/managed-target/README.md b/deploy/managed-target/README.md new file mode 100644 index 0000000..8a85ed1 --- /dev/null +++ b/deploy/managed-target/README.md @@ -0,0 +1,83 @@ +# Isolated managed-test definition — deployment deferred + +This definition is **not autonomous acceptance-ready**: no `managed monitor` +or integrated recovery loop exists. Do not build/pull/start it as part of this +change. Existing containers, production and Xray configuration are out of scope. + +For a later approved deployment, from this directory: + +1. Copy `.env.example` to `.env` and restrict it to `0600`; it sets only the + host loopback SOCKS port. Generate a **new independent** secret locally: + `(umask 077; set -C; openssl rand -hex 32 > ss_password)`. + This refuses to overwrite an existing file. Never copy existing secrets or + put the password in `.env`, environment variables or command arguments. + `ss_password`, `.env` and state are gitignored and excluded from the build + context. Do not commit the secret file. Compose mounts it read-only at + `/run/secrets/ss_password`; keep the host file owned by the invoking user + with mode `0600` (no deploy-time chown or world-readable permissions). + Use only this newly generated regular file at `./ss_password`, not a symlink + or a reused secret. Do not mount its parent directory or other host secrets. +2. Provision a **new empty** `./target-state`, owned by host UID 0 (runtime + user), mode `0700`. Rootless/user-remapped Docker needs the mapped owner. + Never reuse mounts/state. Compose refuses a missing bind source. Retain + state for recreation; deletion loses identity, journal, backups and DB. +3. Orchestrator may validate without deploying: + `docker compose --env-file .env -f compose.yaml config --quiet`. + Rendered Compose config contains only the secret file path, not its value. Build/run require + separate approval and runtime validation gates. + +Offline static guard (from repository root): +`python3 deploy/managed-target/check_static.py`. It pins the capability allowlist +and single-secret/single-state mount shape; it does not prove runtime readability. + +Only SOCKS TCP/UDP is published on host +`127.0.0.1:${ZAPRET_AUTOTUNE_HOST_SOCKS_PORT:-11080}` for same-host Xray; +no Xray edits are supplied. SS port `8388` is internal, never published. +The server binds `0.0.0.0:8388` only inside the dedicated bridge namespace; +ss-local binds `0.0.0.0:1080`. Startup requires a hex-only secret of at least +32 characters and writes JSON configs to the dedicated target-owned tmpfs +`/run/zapret-autotune-ss` (directory `0700`, files `0600`). Both Shadowsocks +processes receive only `-c `, never a password in argv or env. +Docker administrators/root can still read mounted secrets and runtime configs; +file-backed Compose secrets are not encrypted storage. +The dedicated bridge is not shared with existing services. No host networking, +Docker socket, existing mounts, host Lua/fakes or privileged mode; all +capabilities are dropped except `NET_ADMIN`, `NET_RAW`, `SETUID`, `SETGID` +and `DAC_OVERRIDE`. +`NET_ADMIN` covers nft/NFQUEUE; `NET_RAW` covers nfqws2 raw sends. Zapret2's +`nfqws2 --user=tpws` needs `SETUID`/`SETGID` for UID/GID switching, then retains +only `CAP_NET_RAW` and `CAP_NET_ADMIN`. `DAC_OVERRIDE` lets the root entrypoint +read the invoking user's mode-`0600` file-backed secret despite its different +host UID; it does not make the host file world-readable or writable through +the read-only secret mount. This capability is container-wide, not restricted +to one pathname: its safe scope depends on exposing only +`./ss_password` → `/run/secrets/ss_password` (read-only) and the fresh +`./target-state` → `/var/lib/zapret-autotune/target` bind, plus dedicated runtime +tmpfs. Never add host directories, other secrets or existing state to this +container. No default-all capability set is used. Rootless/user-remapped Docker +must validate secret readability separately; this does not bypass user-namespace +or host filesystem restrictions. + +Go builder matches `Dockerfile`; runtime digest is pinned and image-owned +Lua/fakes retained. Startup: ss-server/ss-local → internal listener 1080 +(30-second bound) → guarded managed init on fresh state (status on recreation) +→ zapret2 start using target config. Drift/pending state refuses startup; +no automatic adoption/reconciliation. SIGTERM/SIGINT stop only target-local +zapret firewall and the entrypoint's own Shadowsocks children. Process +supervision is **not** health/recovery; no restart policy hides fail-closed exits. + +Inside target, `zapret-autotune health youtube` uses +`socks5://127.0.0.1:1080`, never the host port. It is one-shot Player API health, +not playback or scheduling. + +The supplied remote read-only inspection verified shadowsocks-libev 3.3.5 +and `ss-server -h` supports `-c `; runtime JSON loading remains +unverified. Before deployment acceptance, validate Lua/fakes, +`ZAPRET_CONFIG` binding and full zapret start/stop/restart with only +the explicit `NET_ADMIN`, `NET_RAW`, `SETUID`, `SETGID`, `DAC_OVERRIDE` capability set (including +the `tpws` user drop). Prove target-local routing, +NFQUEUE activation/rollback, signal cleanup and persistent recreation on the +new target only. Compose syntax, build and runtime integration are unverified +by this producer. Do not widen capabilities or reuse existing config/network +as a workaround. Autonomous acceptance also needs monitor/recovery integration +and crash reconciliation. diff --git a/deploy/managed-target/check_static.py b/deploy/managed-target/check_static.py new file mode 100644 index 0000000..8965d8e --- /dev/null +++ b/deploy/managed-target/check_static.py @@ -0,0 +1,28 @@ +"""Static deployment guard; run with python3 deploy/managed-target/check_static.py.""" + +from pathlib import Path + + +directory = Path(__file__).resolve().parent +compose = (directory / "compose.yaml").read_text() +entrypoint = (directory.parents[1] / "managed-target-entrypoint.sh").read_text() +readme = (directory / "README.md").read_text() + +# ponytail: checks the committed Compose shape, not arbitrary YAML; use a YAML +# parser if this definition grows beyond its single service and single secret. +assert " privileged: false\n" in compose +assert " cap_drop: [ALL]\n" in compose +assert " cap_add: [NET_ADMIN, NET_RAW, SETUID, SETGID, DAC_OVERRIDE]\n" in compose +assert compose.count(" - type: bind\n") == 1 +assert " source: ./target-state\n" in compose +assert " target: /var/lib/zapret-autotune/target\n" in compose +assert " create_host_path: false\n" in compose +assert " secrets: [ss_password]\n" in compose +assert compose.endswith("secrets:\n ss_password:\n file: ./ss_password\n") +assert "SS_PASSWORD" not in compose +assert "ss_password=$(cat /run/secrets/ss_password) || exit 1" in entrypoint +assert "export ss_password" not in entrypoint +assert "export SS_PASSWORD" not in entrypoint +assert "container-wide, not restricted" in readme +assert "mode `0600`" in readme +assert "not a symlink" in readme