diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 9c609b0..01e9961 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -69,8 +69,10 @@ The map is read-only and currently contains: - tmux sessions and tmux-managed agents where the session metadata exposes a bounded relationship. - npm projects discovered from `package.json` and lockfiles under the configured project - root, with scripts, framework hints, dependency nodes, and package-update/advisory - metadata kept behind safe bounded collectors. + root, with scripts, framework hints, and dependency nodes. The contracts can represent + package-update/advisory metadata, but no runtime registry or advisory lookup is enabled + today. UI update labels are derived from local model/demo data unless a future opt-in + advisory provider is implemented. - Python projects discovered from common project files as a later application-provider peer to npm. - scheduled jobs from `/etc/crontab`, `/etc/cron.d/*`, and the current user's `crontab -l` when readable. diff --git a/docs/deployment/DEPLOYMENT.md b/docs/deployment/DEPLOYMENT.md index cf91cef..f22577a 100644 --- a/docs/deployment/DEPLOYMENT.md +++ b/docs/deployment/DEPLOYMENT.md @@ -52,6 +52,33 @@ This builds: - `apps/web/dist` - `crates/target/release/dockermap-daemon` +## External Network Behavior + +Separate build-time downloads from DockerMap runtime behavior: + +- Build and maintenance commands can use the network. `npm ci`, Cargo dependency + fetches, and `npm audit --omit=dev` contact npm or Cargo registries/advisory + services as part of installing, building, or validating the project. +- DockerMap runtime does not run package-registry, package-advisory, DNS-provider API, + Cloudflare API, or generic external-API lookups today. Advisory/update fields may + appear in contracts and fixtures, but the daemon does not populate them from a live + registry or advisory service. +- The web UI currently loads Google Fonts from `fonts.googleapis.com` and + `fonts.gstatic.com` when a browser opens it. Package the fonts locally before release + if the review environment must avoid browser egress. + +Current runtime provider behavior: + +| Provider area | Default behavior | Network note | +| --- | --- | --- | +| Docker | Reads the local Docker socket. | Local host socket access, not registry access. | +| Compose and npm/package metadata | Reads bounded files under `DOCKERMAP_PROJECT_ROOT`. | No registry, audit, advisory, or `.npmrc` lookup. | +| systemd, cron, PM2, tmux, listeners | Runs fixed local read-only commands or reads local `/proc`/cron files. | No user-supplied shell and no configured external destination. | +| reverse-proxy and local DNS markers | Checks fixed local marker paths and Docker image/name signals. | Does not read proxy/DNS config contents or call DNS/proxy provider APIs. | +| Tailscale and Headscale | Runs fixed local CLI commands if the tools are installed. | DockerMap does not add tokens, URLs, or user input, but those CLIs inherit the daemon environment and may use the operator's existing daemon/config to contact their configured control plane. | +| Node API to Rust daemon | Uses `DOCKERMAP_DAEMON_URL`, defaulting to `http://127.0.0.1:4100`. | Non-loopback daemon URLs are rejected unless `DOCKERMAP_ALLOW_REMOTE_DAEMON=true`. | +| Public review access | Disabled unless you deploy a reverse proxy. | The proxy, SSO, VPN, or DNS provider may have its own network behavior outside DockerMap. | + ## Environment File Copy the example and edit it: diff --git a/docs/deployment/REVERSE_PROXY.md b/docs/deployment/REVERSE_PROXY.md index 20da52b..52e39d9 100644 --- a/docs/deployment/REVERSE_PROXY.md +++ b/docs/deployment/REVERSE_PROXY.md @@ -11,6 +11,11 @@ Keep the Rust daemon private. If you need remote review access, expose only the and static web app through a reverse proxy. The proxy should control who can see the UI, and it should add the DockerMap API token when it talks to the local Node API. +Reverse-proxy authentication tools, SSO providers, VPNs, DNS providers, and TLS +automation may contact their own services. DockerMap does not manage those calls; it +only receives the proxy request and, by default, talks back to the local Node API and +Rust daemon. + ## Recommended Review Setup 1. Keep the Rust daemon on loopback: diff --git a/docs/release/RELEASE_CHECKLIST.md b/docs/release/RELEASE_CHECKLIST.md index 996c561..885a3f1 100644 --- a/docs/release/RELEASE_CHECKLIST.md +++ b/docs/release/RELEASE_CHECKLIST.md @@ -17,7 +17,11 @@ These tasks must be complete before tagging `v0.1.0-alpha`. - [x] Add Playwright smoke coverage to CI. - [ ] Keep provider commands fixed and read-only for systemd, tmux, package, Python/native-process, reverse-proxy, DNS, and external-API collectors. - [ ] Bound provider filesystem scanning to documented paths, explicit request targets, and hard caps. -- [ ] Make package advisory, registry, or other external-network behavior opt-in or document it explicitly in release notes and deployment docs. +- [x] Make package advisory, registry, or other external-network behavior opt-in or document it explicitly in release notes and deployment docs. + Current runtime docs state that package registry/advisory, DNS-provider API, + Cloudflare API, and generic external-API lookups are disabled or not implemented. + Tailscale/Headscale delegated CLI behavior and Google-hosted browser fonts are + documented as release decisions. - [ ] Verify package, service, process, unit, proxy, and DNS inspection does not leak env vars, secrets, credentials, or inline auth URLs. Fixture evidence now covers current provider outputs and marker boundaries; keep this broader gate open until future native-process and config-content collectors land. @@ -43,9 +47,12 @@ tasks before starting new GUI work: Current coverage is systemd, tmux, npm/package, native-process-shaped output, reverse-proxy marker, and DNS marker fixture coverage. Native process, reverse-proxy config-content, and DNS config-content collectors remain future implementation work. -- [ ] Decide and document package advisory, registry, or other external-network behavior: +- [x] Decide and document package advisory, registry, or other external-network behavior: keep it disabled/opt-in by default, and record the operator-facing setting in release notes and deployment docs. + Documented current behavior: no runtime package registry/advisory/external-API lookup, + build/release tooling may contact registries, Tailscale/Headscale use installed CLI + configuration, and the browser loads Google-hosted fonts unless packaged locally. - [ ] Capture live-Docker evidence on the release host with `npm run test:live-docker`, including Docker and Compose versions. - [ ] Capture reverse-proxy smoke evidence on the release host, including bearer-token @@ -84,6 +91,8 @@ Store this evidence in release notes or the release PR. - Node, npm, Rust, Cargo, Docker, and browser versions. - Reverse-proxy smoke result. - Provider-network behavior note stating whether any package/advisory or other external API calls were enabled. + Current docs record no runtime package registry/advisory/external-API lookup; note the + Tailscale/Headscale delegated CLI caveat and Google Fonts browser egress in release notes. - Provider-redaction evidence for any new systemd, tmux, package, Python/native-process, reverse-proxy, DNS, or external-API routes shipped in the release. Current fixture evidence is `npm run test:rust:daemon`, covering fake systemd, tmux, npm/package, native-process-shaped, reverse-proxy marker, DNS marker, diagnostic, and diff --git a/docs/security/THREAT_MODEL.md b/docs/security/THREAT_MODEL.md index fd3f6f4..eb00db2 100644 --- a/docs/security/THREAT_MODEL.md +++ b/docs/security/THREAT_MODEL.md @@ -33,7 +33,8 @@ changes them: - Compose edit planning is dry-run only and always returns `willWrite: false`. - Filesystem inspection stays bounded to explicit Compose targets, documented provider paths, or fixed config locations; DockerMap must not do unbounded host-wide scans for discovery. -- Package registry, advisory, or other external-network lookups are opt-in or explicitly +- Package registry, advisory, DNS-provider API, and generic external-API lookups are not + enabled in DockerMap runtime by default; any future lookup must be opt-in or explicitly documented before release. - Package, service, process, unit, and proxy inspection must not leak secrets from env vars, command lines, service files, credentials, or inline auth URLs. @@ -72,8 +73,14 @@ Protections: - Provider commands stay fixed and read-only, such as list/status/introspection calls. - Provider discovery stays bounded to explicit request parameters, known config locations, or capped fixture-like scans instead of recursive host crawling. -- Package advisory or registry traffic is disabled by default unless the operator opts in or - the release docs explicitly call out the network behavior. +- Package registry/advisory traffic, DNS-provider API calls, Cloudflare API calls, and + generic external-API lookups are disabled or not implemented in DockerMap runtime today. +- Tailscale and Headscale discovery use fixed local CLI commands when those tools are + installed. DockerMap does not add tokens, URLs, or user input, but those commands inherit + the daemon environment and the installed tools may use the operator's existing daemon/config + to contact their configured control plane. +- The browser UI currently loads Google Fonts from Google-hosted font endpoints. Treat + that as browser asset egress, separate from daemon/provider egress. - Sensitive values from env files, process args, unit files, proxy configs, and package auth settings must be redacted or omitted before returning API responses. - Security validation for provider routes must run locally without Docker, systemd, tmux, or a @@ -125,8 +132,10 @@ Security checks that still require release evidence: - Live-Docker E2E on a Docker-capable Linux host. - Reverse-proxy bearer-token injection and SSE streaming through the public review URL. - Direct remote inaccessibility of the daemon port. +- A release decision on whether Tailscale/Headscale delegated CLI collection and + Google-hosted web fonts are acceptable defaults for the private review environment. - Package/advisory network-egress behavior for package, Python/native-process, DNS, and - external-API collectors once those routes land or become configurable. + external-API collectors if those routes later land or become configurable. ## Out Of Scope Until Write Mode diff --git a/docs/testing/TESTING_PLAN.md b/docs/testing/TESTING_PLAN.md index bf3a21c..ff0bd77 100644 --- a/docs/testing/TESTING_PLAN.md +++ b/docs/testing/TESTING_PLAN.md @@ -97,6 +97,21 @@ external-API collection, the alpha bar is: - Security tests for the provider can run locally without depending on Docker, systemd, tmux, or browser automation. +For provider-network behavior evidence, verify source and docs rather than running +external services with real credentials: + +```bash +rg -n "advisory|registry|external|network|Tailscale|Headscale|token|auth" docs crates apps packages +rg -n "fetch\\(|Command::new|npm audit|npm view|registry|advisory|fonts.googleapis|fonts.gstatic" apps crates packages docs -g '!**/package-lock.json' -g '!**/Cargo.lock' +``` + +Expected current result: DockerMap runtime has no package registry, package advisory, +DNS-provider API, Cloudflare API, or generic external-API lookup. Tailscale and Headscale +are fixed delegated CLI calls when installed, inherit the daemon environment, and may use +the operator's configured control plane. The API talks to a loopback daemon unless remote +daemon access is explicitly enabled, and the browser shell loads Google-hosted fonts unless +assets are packaged locally. + The daemon unit suite includes fake-only provider redaction fixtures for systemd, tmux, npm/package metadata, native-process-shaped command output, reverse-proxy markers, DNS markers, provider diagnostics, and provider edge metadata. These fixtures deliberately use @@ -214,6 +229,7 @@ More detail is in [docs/deployment/REVERSE_PROXY.md](../deployment/REVERSE_PROXY - Run and record live-Docker integration evidence on the release host. - Add reverse-proxy integration tests for bearer-token injection and SSE streaming. - Add OpenAPI schema checks once the versioned API spec exists. -- Add fixture-driven provider redaction tests for systemd, tmux, package inspection, - Python/native processes, reverse proxies, DNS, and any external advisory clients. +- Add fixture-driven provider redaction tests for any future Python/native-process, + reverse-proxy config-content, DNS config-content, package advisory, registry, or + external-API collectors. - Add write-mode tests only after backup, confirmation, and rollback behavior exists.