v9.3.1

README.md

@@ -1,8 +1,4 @@
-
-## v9.1 packaging fix
-
-v9.1 fixes the v9 source archive packaging. The v9 ZIP accidentally omitted `internal/stacks/`, which could leave an older local copy of that package in place when extracting over an existing checkout and cause method-signature build errors. v9.1 is a complete source archive and includes `internal/stacks/stacks.go` and its tests. Always extract it into a fresh directory.
-# Dockwatch v9.1
+# Dockwatch v9.3.1
 
 > Go module: `git.send.nrw/sendnrw/dockwatch`
 
@@ -57,6 +53,64 @@ Symlink stack destinations and symlink paths inside Git-managed writes are rejec
 - operator-only inspect
 - one-shot CPU/memory/network/block stats
 
+### Container identity / host UID-GID checks
+
+Container rows include an **Identity** action. Dockwatch inspects the selected container and reports:
+
+- configured Compose/image user and the effective runtime UID/GID where resolvable
+- whether the process currently runs as UID 0
+- a conservative root assessment based on `privileged`, Docker socket mounts, passed-through devices and added Linux capabilities
+- bind-mount sources and their host UID/GID ownership when host access is configured
+- single-container detail checks plus a throttled **Identity audit** across all containers in the selected environment
+- whether the container UID/GID already maps to a local host account/group
+
+Dockwatch deliberately does **not** claim that a root container can always be converted to non-root. Application-internal filesystem permissions, entrypoints and image-specific `PUID`/`PGID` conventions cannot be proven from Docker metadata alone. It also never rewrites Compose `user:` automatically.
+
+A matching local host username is **not required by Docker**. Linux file ownership is numeric; creating a host account can nevertheless make bind-mount ownership, backups and administration easier.
+
+Host inspection is opt-in. For read-only inspection, set:
+
+```env
+HOST_ROOT=/host
+ALLOW_HOST_USER_MANAGEMENT=false
+ALLOW_HOST_PERMISSION_MANAGEMENT=false
+```
+
+and mount the host root read-only at `/host`. `examples/compose-host-identity.override.yml` shows this setup.
+
+Admins may optionally create a locked/non-login local host account using the container's server-side re-resolved UID/GID. This requires both a writable host-root mount and:
+
+```env
+ALLOW_HOST_USER_MANAGEMENT=true
+```
+
+See `examples/compose-host-user-management.override.yml`. The browser cannot supply an arbitrary UID/GID: Dockwatch re-inspects the container immediately before the change and derives the IDs itself. Existing numeric users/groups are reused and UID/name collisions are refused. Docker rootless/user-namespace remapping is detected where possible; automatic same-numbered host-account creation is refused when IDs are remapped. This operation is intentionally admin-only and disabled by default.
+
+### Identity & Bind Mount Permissions
+
+Dockwatch can now diagnose the actual bind-mount permission problem instead of stopping at "container runs as UID X". The container **Identity** dialog and each stack's **Permissions** tab show, per bind mount:
+
+- effective PID 1 UID/GID and a separate expected **bind UID/GID**
+- `PUID/PGID` or `USER_ID/GROUP_ID` when the image exposes those paired conventions
+- host owner UID/GID and POSIX mode bits
+- static writeability (`w+x` for directories, `w` for files)
+- extended POSIX ACL detection when `getfacl` is available
+- an optional non-mutating runtime `test -w` using the expected numeric identity
+- read-only mounts, rootless/userns remapping and unsafe symlinked host paths as hard repair blockers
+
+The repair flow is **Analyze → Preview → Repair → Verify**. For recursive ownership repair Dockwatch scans the tree first and shows how many files/directories differ. Automatic recursive repair is refused above 200,000 entries. Symlinks are never followed or chowned. `:ro` mounts are never repaired automatically.
+
+Permission repair is a separate high-trust opt-in from host-user creation:
+
+```env
+HOST_ROOT=/host
+ALLOW_HOST_PERMISSION_MANAGEMENT=true
+```
+
+and `/` must intentionally be mounted read-write at `/host`. See `examples/compose-host-permissions.override.yml`. The browser supplies only the container and its mount destination (for example `/config`); the backend re-reads `docker inspect` and resolves the real host source itself. Arbitrary host paths and arbitrary UID/GID values cannot be submitted for repair.
+
+Ownership repair can operate on only the bind root or recursively. `chmod` is separate, optional, explicit, and only applies to the bind root; Dockwatch never automatically applies `chmod 777` and never recursively rewrites modes. After a repair Dockwatch re-runs the ownership/writeability analysis and reports the result.
+
 **Images**
 
 - list/filter
@@ -197,6 +251,7 @@ Remote-capable features include:
 - Compose graph
 - image update checks
 - containers/images/networks/volumes
+- container identity analysis, bind-mount permission repair and optional host-account creation on the agent host
 - monitoring probes
 - Git clone/sync/deploy
 
@@ -215,7 +270,10 @@ The designer is not limited to a hard-coded subset: arbitrary maps, arrays and s
 
 Server-side save validation still uses Docker Compose itself after all related `.env`, secret, env-file and config files have been staged.
 
-## Reliability and security work in v9
+## Reliability and security work in v9 / v9.2
+
+The v9.2 identity extension is opt-in, admin-gated and preserves the existing least-surprise rule: diagnostics are read-only by default and no container user or host account is changed automatically.
+
 
 The v9 review includes, among other changes:
 
@@ -262,6 +320,9 @@ CHECK_CONCURRENCY=8
 CHECK_RETENTION_DAYS=30
 HTTP_TIMEOUT_SECONDS=10
 AUDIT_RETENTION_DAYS=180
+HOST_ROOT=
+ALLOW_HOST_USER_MANAGEMENT=false
+ALLOW_HOST_PERMISSION_MANAGEMENT=false
 ```
 
 `AUTH_DISABLED=true` is for local development only. Do not expose that configuration publicly.
@@ -283,6 +344,10 @@ Runtime mounts normally include:
 
 Giving Dockwatch access to the Docker socket grants highly privileged control of that Docker host. Protect the UI and agent endpoint accordingly.
 
+## v9.3.1 build-context fix
+
+v9.3 accidentally used the broad ignore pattern `dockwatch` in both `.gitignore` and `.dockerignore`. Because patterns without a slash match path components recursively, that could hide `cmd/dockwatch/` from Git and from the Docker build context. v9.3.1 removes that pattern, writes local Makefile builds to `bin/dockwatch`, ignores only `bin/`/`dist/`, and makes the Dockerfile fail early with a clear message if `cmd/dockwatch/main.go` is ever missing from the build context.
+
 ## Build from source
 
 The pinned OIDC/OAuth2 releases require **Go 1.25**. The Docker build uses `golang:1.25-alpine`.