@checkstack/satellite 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @checkstack/satellite
 
+## 0.5.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.
+
+### 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]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/common@0.13.0
+  - @checkstack/script-packages-backend@0.3.0
+  - @checkstack/satellite-common@0.8.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [a57f7db]
+  - @checkstack/backend-api@0.20.0
+  - @checkstack/script-packages-backend@0.2.1
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -11,9 +11,9 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/satellite-common": "0.6.0",
-    "@checkstack/backend-api": "0.18.0",
-    "@checkstack/script-packages-backend": "0.1.0",
+    "@checkstack/satellite-common": "0.7.0",
+    "@checkstack/backend-api": "0.20.0",
+    "@checkstack/script-packages-backend": "0.2.1",
     "@checkstack/common": "0.12.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -2,13 +2,15 @@ import type {
   SatelliteAssignment,
   ResultMessage,
 } from "@checkstack/satellite-common";
-import type {
-  ConnectedClient,
-  TransportClient,
-  CollectorRunContext,
+import {
+  registerSandboxPolicyProvider,
+  type ConnectedClient,
+  type TransportClient,
+  type CollectorRunContext,
 } from "@checkstack/backend-api";
 import { resolveScriptPackagesDir } from "@checkstack/script-packages-backend";
 import { SatelliteClient } from "./satellite-client";
+import { SatelliteSandboxPolicyCache } from "./sandbox-policy-cache";
 import { Scheduler } from "./scheduler";
 import { loadStrategies } from "./strategy-loader";
 import { buildRunContext } from "./run-context";
@@ -58,6 +60,27 @@ const logger = {
 // =============================================================================
 
 logger.info(`Starting Checkstack Satellite v${VERSION}`);
+
+// Wire the process-wide GLOBAL sandbox policy provider for the satellite
+// runtime. The script runners (shell + ESM) resolve the active policy through
+// this provider and FAIL CLOSED if none is registered, so it MUST be set before
+// any health-check script runs.
+//
+// The satellite has no ConfigService, so it cannot read the durable cluster
+// policy directly. Instead the core RELAYS the resolved global policy over the
+// already-authenticated WS channel: on connect (carried in the `authenticated`
+// message) and on change (a `sandbox_policy` push). The cache holds the last
+// relayed policy and the provider resolves through it.
+//
+// FAIL CLOSED UNTIL RELAY: before the first policy is received, the cache's
+// provider returns the FAIL_CLOSED profile (deny egress, scratch filesystem +
+// read-only managed packages, privilege drop) - NEVER the permissive shipped
+// default. A satellite must never run a script with a looser policy than core
+// relayed; before the first relay there is none, so it denies. Trust is
+// established by the authenticated WS connection.
+const sandboxPolicyCache = new SatelliteSandboxPolicyCache();
+registerSandboxPolicyProvider(sandboxPolicyCache.toProvider());
+
 logger.info("Loading health check strategies...");
 
 const { healthCheckRegistry, collectorRegistry } = await loadStrategies({
@@ -292,6 +315,12 @@ const client = new SatelliteClient({
   onScriptPackagesLockfileHash: (lockfileHash) => {
     void scriptPackages.reconcile(lockfileHash);
   },
+  onSandboxPolicy: (policy) => {
+    // Cache the relayed cluster-wide policy; the runner's provider resolves
+    // through this cache. Fail-closed until the first relay arrives.
+    sandboxPolicyCache.set(policy);
+    logger.info("Applied relayed global sandbox policy");
+  },
   onDisconnect: () => {
     scheduler.stop();
   },

package/src/sandbox-policy-cache.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+import {
+  FAIL_CLOSED_SANDBOX_PROFILE,
+  resolveDefaultSandboxProfile,
+  sandboxPolicySchema,
+} from "@checkstack/backend-api";
+import { SatelliteSandboxPolicyCache } from "./sandbox-policy-cache";
+
+const RELAYED = sandboxPolicySchema.parse({
+  enabled: true,
+  onUnavailable: "degrade",
+  resources: { cpuSeconds: 42 },
+  filesystem: { mode: "scratch-plus-ro" },
+  network: { mode: "deny", allow: [], denyLinkLocalAndMetadata: true },
+  privilege: { mode: "drop-to-uid" },
+});
+
+describe("SatelliteSandboxPolicyCache fail-closed-until-relay", () => {
+  it("resolves the FAIL-CLOSED profile BEFORE any policy is relayed", async () => {
+    const cache = new SatelliteSandboxPolicyCache();
+    const policy = await cache.resolve();
+    expect(policy).toEqual(FAIL_CLOSED_SANDBOX_PROFILE);
+    // Crucially NOT the permissive shipped default.
+    expect(policy).not.toEqual(resolveDefaultSandboxProfile());
+    expect(policy.network.mode).toBe("deny");
+  });
+
+  it("resolves the CACHED relayed policy once one has been received", async () => {
+    const cache = new SatelliteSandboxPolicyCache();
+    cache.set(RELAYED);
+    const policy = await cache.resolve();
+    expect(policy).toEqual(RELAYED);
+    expect(policy.resources.cpuSeconds).toBe(42);
+  });
+
+  it("a later relay replaces the cached policy", async () => {
+    const cache = new SatelliteSandboxPolicyCache();
+    cache.set(RELAYED);
+    const next = sandboxPolicySchema.parse({
+      ...RELAYED,
+      network: { mode: "allowlist", allow: ["10.0.0.1"], denyLinkLocalAndMetadata: true },
+    });
+    cache.set(next);
+    const policy = await cache.resolve();
+    expect(policy.network.mode).toBe("allowlist");
+    expect(policy.network.allow).toEqual(["10.0.0.1"]);
+  });
+
+  it("the provider closure fails closed until the first relay, then returns the cache", async () => {
+    const cache = new SatelliteSandboxPolicyCache();
+    const provider = cache.toProvider();
+    expect(await provider()).toEqual(FAIL_CLOSED_SANDBOX_PROFILE);
+    cache.set(RELAYED);
+    expect(await provider()).toEqual(RELAYED);
+  });
+});

package/src/sandbox-policy-cache.ts

@@ -0,0 +1,49 @@
+import {
+  FAIL_CLOSED_SANDBOX_PROFILE,
+  type SandboxPolicy,
+  type SandboxPolicyProvider,
+} from "@checkstack/backend-api";
+
+/**
+ * Pod-local cache of the GLOBAL sandbox policy relayed to this satellite by the
+ * core over the authenticated WS channel.
+ *
+ * State-and-scale note: this is NOT a queryable global source of truth - the
+ * core's durable policy row is. It is genuinely satellite-local transport state
+ * (the policy this specific satellite was last told to enforce), exactly like
+ * the pod-local live-socket registry on the core side. The satellite has no
+ * database connection, so it cannot read the durable policy directly; it trusts
+ * the already-authenticated WS connection to relay it.
+ *
+ * SECURITY - FAIL CLOSED UNTIL RELAY: before the first policy is received,
+ * {@link resolve} returns {@link FAIL_CLOSED_SANDBOX_PROFILE} (deny egress,
+ * scratch filesystem + read-only managed packages, privilege drop) - NEVER the
+ * permissive shipped default. A satellite must never run a script with a looser
+ * policy than core relayed, and before the first relay there is no relayed
+ * policy, so it denies. The policy is delivered on connect (in the
+ * `authenticated` message) and on change (a `sandbox_policy` push), so the
+ * fail-closed window is only the brief interval before the first authenticated
+ * message is processed.
+ */
+export class SatelliteSandboxPolicyCache {
+  private policy: SandboxPolicy | undefined;
+
+  /** Replace the cached policy with the latest relayed value. */
+  set(policy: SandboxPolicy): void {
+    this.policy = policy;
+  }
+
+  /**
+   * Resolve the policy to enforce for a run: the cached relayed policy, or the
+   * fail-closed profile if nothing has been relayed yet. Bound so it can be
+   * handed directly to {@link registerSandboxPolicyProvider} as the provider.
+   */
+  resolve = async (): Promise<SandboxPolicy> => {
+    return this.policy ?? FAIL_CLOSED_SANDBOX_PROFILE;
+  };
+
+  /** A {@link SandboxPolicyProvider} closure bound to this cache. */
+  toProvider(): SandboxPolicyProvider {
+    return this.resolve;
+  }
+}

package/src/satellite-client.ts

@@ -10,6 +10,7 @@ import type {
   ResultMessage,
   ScriptPackageSyncStateMessage,
 } from "@checkstack/satellite-common";
+import type { SandboxPolicy } from "@checkstack/backend-api";
 import { ResultBuffer } from "./result-buffer";
 
 interface ManifestEntryWire {
@@ -31,6 +32,13 @@ interface SatelliteClientConfig {
    * `refresh_script_packages` push. The satellite reconciles to it.
    */
   onScriptPackagesLockfileHash?: (lockfileHash: string | null) => void;
+  /**
+   * Called with the relayed GLOBAL sandbox policy - on connect (carried in the
+   * `authenticated` message) and on a `sandbox_policy` push. The satellite
+   * caches it and resolves every script run through it. Until the first call
+   * the satellite FAILS CLOSED (denies egress).
+   */
+  onSandboxPolicy?: (policy: SandboxPolicy) => void;
   logger?: {
     info: (msg: string) => void;
     warn: (msg: string) => void;
@@ -249,6 +257,12 @@ export class SatelliteClient {
             msg.scriptPackagesLockfileHash,
           );
         }
+        // Sandbox policy relay (durable backstop): cache the policy carried on
+        // (re)connect so runs enforce the operator's cluster-wide policy. Until
+        // this arrives the satellite stays fail-closed (deny egress).
+        if (msg.sandboxPolicy !== undefined) {
+          this.config.onSandboxPolicy?.(msg.sandboxPolicy);
+        }
         break;
       }
 
@@ -280,6 +294,14 @@ export class SatelliteClient {
         break;
       }
 
+      case "sandbox_policy": {
+        // Push-on-change: replace the cached global sandbox policy so the next
+        // run enforces it immediately.
+        this.config.logger?.info("Received updated global sandbox policy");
+        this.config.onSandboxPolicy?.(msg.policy);
+        break;
+      }
+
       case "script_package_manifest": {
         // The pending callback is looked up by a message-supplied key. Validate
         // that what we got back is actually callable before invoking it, so an