v9.4.0

README.md

@@ -1,4 +1,4 @@
-# Dockwatch v9.3.2
+# Dockwatch v9.4
 
 > Go module: `git.send.nrw/sendnrw/dockwatch`
 
@@ -132,6 +132,98 @@ Ownership repair can operate on only the bind root or recursively. `chmod` is se
 
 Docker positional arguments and Compose service names are validated before invoking the CLI so option-like values cannot be interpreted as Docker CLI flags.
 
+### Host Security layer
+
+Dockwatch can optionally act as a host-security control plane for the selected local or remote-agent environment. The feature is **disabled by default** and uses three independent capabilities so that audit, configuration changes and package management can be granted separately.
+
+The **System → Host Security** page provides a posture overview and managed workflows for:
+
+**Firewall (nftables)**
+
+- detect whether nftables is installed and whether Dockwatch's policy is active
+- configure an isolated `table inet dockwatch` INPUT policy
+- default inbound `ACCEPT` or `DROP`
+- stateful established/related allowance, loopback and invalid-state handling
+- optional ICMP/ICMPv6 allowance
+- trusted IPv4/IPv6 CIDRs
+- typed TCP/UDP allow/deny port and port-range rules
+- server-side `nft -c` validation before apply
+- conflict detection for active UFW/firewalld; Dockwatch refuses to become a second competing firewall owner
+- persistence through a Dockwatch-owned systemd unit or OpenRC local script
+- **timed rollback** (30–600 seconds, UI default 90 seconds) after apply; changes must be explicitly kept after management connectivity is verified
+- no `flush ruleset`, no changes to Docker NAT/FORWARD chains and no arbitrary nftables text accepted from the browser
+
+**Fail2Ban**
+
+- package/runtime/boot status
+- package installation/upgrade when separately enabled
+- managed global ban/find/max-retry/backend settings
+- ignore IP/CIDR list
+- configurable jails with filter, port, backend, log path and per-jail retry threshold
+- server-side `fail2ban-client -t` validation before activation/reload
+- Dockwatch owns only `/etc/fail2ban/jail.d/dockwatch.local`; distro and administrator configuration is preserved
+
+**Linux Audit (auditd)**
+
+- package/runtime/boot status
+- managed watches for identity files, sudoers, SSH configuration, Docker socket/configuration, systemd units and kernel-module configuration
+- additional explicitly configured file watches
+- path/key/permission validation
+- `augenrules --check` validation and `augenrules --load` activation
+- Dockwatch owns only `/etc/audit/rules.d/90-dockwatch.rules`; unrelated audit rules remain untouched
+
+**Installation and maintenance**
+
+- install or upgrade `nftables`, `fail2ban` and `auditd`/`audit` using the detected host package manager
+- supported package-manager families: apt, dnf, yum, zypper, apk and pacman
+- enable, disable, restart and (where meaningful) reload the corresponding host services
+- current package/service/config-drift information in the UI
+- backups of Dockwatch-managed host configuration before replacement
+- all mutation endpoints are administrator-only and flow through Dockwatch's existing origin/CSRF guard and activity audit log
+
+Dockwatch intentionally manages its own drop-in/configuration scope rather than rewriting the host's entire security configuration. It is a focused administration layer, not a replacement for a complete CIS/STIG benchmark, SELinux/AppArmor policy management, an enterprise EDR, or distro-specific security tooling.
+
+#### Capability modes
+
+Read-only file/configuration audit:
+
+```yaml
+services:
+  dockwatch:
+    environment:
+      HOST_ROOT: /host
+      HOST_SECURITY_ENABLED: "true"
+      ALLOW_HOST_SECURITY_CHANGES: "false"
+      ALLOW_HOST_PACKAGE_MANAGEMENT: "false"
+    volumes:
+      - /:/host:ro
+```
+
+A ready-to-use example is `examples/compose-host-security-audit.override.yml`. In this mode Dockwatch cannot mutate the host. Runtime/service checks that require entering the host namespaces may be unavailable and are reported as such.
+
+Full host-security management is intentionally high privilege:
+
+```yaml
+services:
+  dockwatch:
+    pid: host
+    privileged: true
+    environment:
+      HOST_ROOT: /host
+      HOST_SECURITY_ENABLED: "true"
+      ALLOW_HOST_SECURITY_CHANGES: "true"
+      ALLOW_HOST_PACKAGE_MANAGEMENT: "true"
+      HOST_SECURITY_HOST_PID: "1"
+    volumes:
+      - /:/host:rw
+```
+
+See `examples/compose-host-security.override.yml`. Dockwatch verifies that `HOST_ROOT` and `/proc/<HOST_SECURITY_HOST_PID>/root` refer to the same host before enabling its namespace executor. Host commands are executed through `nsenter` in the target host namespaces; the browser can select only predefined operations and cannot submit arbitrary shell commands.
+
+Because this mode grants Dockwatch broad host-administration capability, use OIDC, restrict the `admin` role carefully, protect the Dockwatch database/`APP_SECRET`, and do not expose an agent token or the UI to untrusted networks.
+
+The same security APIs are available through the existing master/agent relay, so each agent can audit/manage **its own host** when that agent has been configured with the appropriate host-security capability. A master does not silently inherit host privileges on an agent.
+
 ### Monitoring
 
 Probe types:
@@ -254,6 +346,7 @@ Remote-capable features include:
 - container identity analysis, bind-mount permission repair and optional host-account creation on the agent host
 - monitoring probes
 - Git clone/sync/deploy
+- host-security audit/management when explicitly enabled on that agent
 
 See `examples/compose-master.yml` and `examples/compose-agent.yml`.
 
@@ -323,6 +416,10 @@ AUDIT_RETENTION_DAYS=180
 HOST_ROOT=
 ALLOW_HOST_USER_MANAGEMENT=false
 ALLOW_HOST_PERMISSION_MANAGEMENT=false
+HOST_SECURITY_ENABLED=false
+ALLOW_HOST_SECURITY_CHANGES=false
+ALLOW_HOST_PACKAGE_MANAGEMENT=false
+HOST_SECURITY_HOST_PID=1
 ```
 
 `AUTH_DISABLED=true` is for local development only. Do not expose that configuration publicly.
@@ -374,17 +471,17 @@ SQLite database:
 
 The artifact-building environment cannot reach `proxy.golang.org`, so it cannot download the real external modules or generate a trustworthy `go.sum` here. The repository intentionally does **not** ship fake checksums or test stubs.
 
-For quality control, the project is copied into a temporary test workspace where API-compatible local stubs replace only the external dependencies. Those stubs are not included in the ZIP. The checks used for v9 include:
+For quality control, the project is copied into a temporary test workspace where API-compatible local stubs replace only the external dependencies. Those stubs are not included in the ZIP. The checks used for this source snapshot include:
 
 ```text
 # all packages type/compile checked with temporary external-module stubs
 go test -run='^$' ./...
 
 go test ./internal/config ./internal/gitops ./internal/httpapi \
-        ./internal/monitor ./internal/nodes ./internal/notify ./internal/stacks
+        ./internal/monitor ./internal/nodes ./internal/notify ./internal/stacks ./internal/hostsecurity
 
 go vet ./...
-go test -race ./internal/config ./internal/gitops ./internal/httpapi ./internal/monitor ./internal/nodes ./internal/notify ./internal/stacks
+go test -race ./internal/config ./internal/gitops ./internal/httpapi ./internal/monitor ./internal/nodes ./internal/notify ./internal/stacks ./internal/hostsecurity
 node --check web/app.js
 ```