@checkstack/satellite-common 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @checkstack/satellite-common
 
+## 0.8.0
+
+### Minor Changes
+
+- 9dcc848: Layered OS-level script sandbox, secure and fail-closed by default (epic #247).
+
+  Script and shell health checks and the `run_shell` / `run_script` automation actions now run inside a layered OS-level sandbox by default. The sandbox lives in `core/backend-api/src/script-sandbox/` (the single source of truth) and is enforced inside the shared runners, so it applies wherever a job runs.
+
+  Layers:
+
+  - Resource caps (CPU / memory / PID / FD / file-size, via `prlimit` on capable Linux; ESM JS-heap cap via `--max-old-space-size`; portable wall-clock timeout) and an OOM-safe streaming output cap.
+  - Privilege drop via a NON-ROOT supervisor model: the shipped images run the supervisor as non-root uid `65532`, so every sandboxed script inherits non-root and can never be host-root; filesystem + network confinement is delivered by ROOTLESS `bwrap`/`nsjail` via unprivileged user namespaces. `enforced.privilege` is truthful (true only when the child cannot run as host-root). Runners no longer pass `uid`/`gid` to `Bun.spawn` (a silent no-op and a forward-compat hazard).
+  - Filesystem isolation (`scratch-only` / `scratch-plus-ro`) confining the child to its per-run scratch dir over a read-only base; the interpreter path is RO-bound so the runtime execs, and `TMPDIR` is pinned to the in-namespace tmpfs.
+  - Network egress control: `deny` (routeless loopback-only netns), `allowlist` (real plumbed egress via macvlan OR rootless slirp4netns + an in-kernel nftables filter), and an always-on metadata / link-local block (`169.254.0.0/16`, `fe80::/10`, `fc00::/7`). No-blackhole invariant: `enforced.network` is never true when egress is actually severed or unfiltered; unpluggable egress degrades to surfaced host net.
+  - Per-run fork-bomb containment via RLIMIT*NPROC inside the fresh per-run user+PID namespace; a centralized forbidden-env denylist (`LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD*_`, `NODE*OPTIONS`, `BUN*_`, caller `PATH` overrides).
+  - A validated tuned seccomp profile (`deploy/seccomp/checkstack-userns.json`) and a live `clone(CLONE_NEWUSER|CLONE_NEWNET)` capability probe (not the static sysctl), shipped by default in both Dockerfiles, `docker-compose.yml`, and `deploy/k8s/checkstack-sandbox.yaml`.
+
+  Global policy and operator surface:
+
+  - The global sandbox policy lives in ONE durable row owned by `script-packages` (its `ConfigService` row in shared `plugin_configs`). A single process-wide provider serves every runner; the two script plugins no longer register competing providers. A dedicated admin-only `script-sandbox.manage` permission gates both reading and writing the policy. New `getSandboxPolicy` / `setSandboxPolicy` endpoints and a Settings -> Script Sandbox admin UI (`enabled`, `onUnavailable`, network/filesystem/privilege modes, allow list, metadata block, resource caps). The startup capability/readiness log is emitted in-process by `script-packages-backend` (no fragile init-order RPC self-loop), and on a host that cannot enforce a layer a one-time startup warning explains the two local-dev paths (Docker, or set the global policy to `degrade`).
+  - Satellite relay: the WS protocol carries the resolved policy in the `authenticated` message and a `sandbox_policy` push-on-change; a satellite caches the last relayed policy and resolves every run through it.
+
+  BREAKING CHANGES (platform in BETA, shipped as minor):
+
+  - Scripts run sandboxed by default. The shipped global default is FAIL-CLOSED (`onUnavailable: "fail"`): when a requested layer cannot be enforced the run is REFUSED (clean `exitCode: -1`, never an unsandboxed spawn) rather than silently degrading. Deployments on hosts that cannot enforce a layer (no bubblewrap, user namespaces blocked, no `/proc` unmask) must run the official images with the documented runtime flags (the bundled seccomp profile + `systempaths=unconfined`, or k8s `procMount: Unmasked`), or set the global policy to `degrade`. On macOS / restricted containers the strong layers degrade to the portable subset and are surfaced per run.
+  - Default network posture is deny-egress (`allowlist` with an empty allow list, which resolves to the routeless `deny` path). Scripts calling external endpoints fail until those destinations are allowlisted in the global default. The always-on metadata / link-local block applies even under looser modes.
+  - The per-action / per-check `sandbox` config override and the transport `ScriptRequest.sandbox` field are removed; policy is global-only, so an automation/check author can no longer weaken the sandbox on their own item. Stored configs carrying a stray `sandbox` key are tolerated (stripped on parse).
+  - The shared runners' `run()` no longer accepts a `sandbox` option; callers rely on the global policy provider.
+  - A satellite fails closed (most restrictive profile) until it receives the first relayed policy; a relay-read failure or an older core keeps it fail-closed. A relay failure can never loosen a satellite's sandbox.
+
+  State and scale: the global policy is a single durable Postgres row read identically on every pod. Capability detection is per-process, deterministic from the host kernel, and surfaced per run via the `EffectiveSandbox` report (a Linux pod and a macOS satellite may legitimately differ). `CHECKSTACK_SANDBOX_UID/GID` and macvlan addressing are genuinely per-host infrastructure, surfaced per run, not the queryable policy. The satellite's policy cache is satellite-local transport state. No new pod-local current-state.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/common@0.13.0
+  - @checkstack/signal-common@0.2.6
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite-common",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -10,9 +10,9 @@
   },
   "dependencies": {
     "@checkstack/common": "0.12.0",
-    "@checkstack/healthcheck-common": "1.3.0",
+    "@checkstack/healthcheck-common": "1.4.0",
     "@checkstack/signal-common": "0.2.5",
-    "@orpc/contract": "^1.13.14",
+    "@orpc/contract": "^1.14.4",
     "zod": "^4.2.1"
   },
   "devDependencies": {

package/src/protocol.test.ts

@@ -148,3 +148,55 @@ describe("run-secrets request/reply (Phase 3 JIT delivery)", () => {
     }
   });
 });
+
+describe("sandbox-policy protocol extensions", () => {
+  const policy = {
+    enabled: true,
+    onUnavailable: "degrade" as const,
+    resources: { cpuSeconds: 30 },
+    filesystem: { mode: "scratch-plus-ro" as const },
+    network: {
+      mode: "allowlist" as const,
+      allow: ["10.0.0.1"],
+      denyLinkLocalAndMetadata: true,
+    },
+    privilege: { mode: "drop-to-uid" as const },
+  };
+
+  test("authenticated carries an optional sandboxPolicy that round-trips", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+      sandboxPolicy: policy,
+    });
+    if (parsed.type === "authenticated") {
+      expect(parsed.sandboxPolicy?.network.mode).toBe("allowlist");
+      expect(parsed.sandboxPolicy?.network.allow).toEqual(["10.0.0.1"]);
+      expect(parsed.sandboxPolicy?.resources.cpuSeconds).toBe(30);
+    }
+  });
+
+  test("authenticated WITHOUT sandboxPolicy parses (version-skew safety)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+    });
+    if (parsed.type === "authenticated") {
+      expect(parsed.sandboxPolicy).toBeUndefined();
+    }
+  });
+
+  test("sandbox_policy push message round-trips the full policy", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "sandbox_policy",
+      policy,
+    });
+    expect(parsed.type).toBe("sandbox_policy");
+    if (parsed.type === "sandbox_policy") {
+      expect(parsed.policy.network.mode).toBe("allowlist");
+      expect(parsed.policy.privilege.mode).toBe("drop-to-uid");
+    }
+  });
+});

package/src/protocol.ts

@@ -3,6 +3,7 @@ import {
   HealthCheckStatusSchema,
   HealthCheckRunResultSchema,
 } from "@checkstack/healthcheck-common";
+import { sandboxPolicySchema } from "@checkstack/common";
 
 // =============================================================================
 // SATELLITE ASSIGNMENT (Core → Satellite configuration payload)
@@ -187,6 +188,16 @@ const AuthenticatedMessageSchema = z.object({
    * Optional for version-skew safety; null means "no packages installed".
    */
   scriptPackagesLockfileHash: z.string().nullable().optional(),
+  /**
+   * The resolved GLOBAL script-sandbox policy, pushed at auth time so the
+   * satellite enforces the operator's cluster-wide policy from its very first
+   * script run. The satellite caches it and resolves every run through it;
+   * until this arrives it FAILS CLOSED (denies egress) rather than using the
+   * permissive shipped default. Optional for version-skew safety: an older
+   * core omits it, and the satellite then stays fail-closed until a
+   * `sandbox_policy` push or a reconnect against a newer core delivers it.
+   */
+  sandboxPolicy: sandboxPolicySchema.optional(),
 });
 
 const AuthFailedMessageSchema = z.object({
@@ -218,6 +229,19 @@ const RefreshScriptPackagesMessageSchema = z.object({
   lockfileHash: z.string(),
 });
 
+/**
+ * Push the new GLOBAL script-sandbox policy to a connected satellite when an
+ * admin changes it (the push-on-change relay). Sent by each core instance's
+ * `script-sandbox.policy-changed` broadcast handler to its currently-connected
+ * satellites. The satellite replaces its cached policy so subsequent runs
+ * enforce it immediately. Best-effort liveness; the policy carried in the
+ * `authenticated` message on (re)connect is the durable backstop.
+ */
+const SandboxPolicyMessageSchema = z.object({
+  type: z.literal("sandbox_policy"),
+  policy: sandboxPolicySchema,
+});
+
 /** One resolved package in a manifest reply. */
 const ManifestEntryWireSchema = z.object({
   name: z.string(),
@@ -269,6 +293,7 @@ export const CoreToSatelliteMessageSchema = z.discriminatedUnion("type", [
   ConfigUpdatedMessageSchema,
   ShutdownMessageSchema,
   RefreshScriptPackagesMessageSchema,
+  SandboxPolicyMessageSchema,
   ScriptPackageManifestMessageSchema,
   ScriptPackageBlobMessageSchema,
   RunSecretsMessageSchema,
@@ -286,6 +311,7 @@ export type ShutdownMessage = z.infer<typeof ShutdownMessageSchema>;
 export type RefreshScriptPackagesMessage = z.infer<
   typeof RefreshScriptPackagesMessageSchema
 >;
+export type SandboxPolicyMessage = z.infer<typeof SandboxPolicyMessageSchema>;
 export type ScriptPackageManifestMessage = z.infer<
   typeof ScriptPackageManifestMessageSchema
 >;