@checkstack/backend-api 0.19.0 → 0.21.0

package/src/script-sandbox/observability.ts

@@ -0,0 +1,168 @@
+import {
+  detectSandboxCapabilities,
+  type SandboxCapabilities,
+} from "./capabilities";
+import { buildSpawnHardening } from "./wrapper";
+import { pickSafeEnv } from "./env-guard";
+import {
+  resolveDefaultSandboxProfile,
+  type SandboxPolicy,
+} from "./policy";
+import type { EffectiveSandbox } from "./report";
+
+/**
+ * Observability for the script sandbox (plan §5.7 / Phase 4).
+ *
+ * Two surfaces:
+ *  1. A single startup capability-log line per pod/satellite so operators can
+ *     see what THIS host actually enforces for the configured global default
+ *     (capability detection is per-host and may legitimately differ between a
+ *     Linux pod and a macOS satellite — see {@link SandboxCapabilities}).
+ *  2. A compact per-run downgrade summary the call sites log (and may surface
+ *     in the run record) whenever a layer degraded, so a degradation is never
+ *     silent.
+ */
+
+/** A logger surface narrow enough for the test mocks but matching the real one. */
+export interface SandboxLogger {
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Human-readable summary of what a host can enforce, derived purely from its
+ * detected capabilities. Exported so tests can assert the shape without
+ * scraping a log string.
+ */
+export function summarizeCapabilities(
+  caps: SandboxCapabilities,
+): Record<string, string | boolean | null> {
+  return {
+    platform: caps.platform,
+    // The supervisor's euid. The shipped images run NON-root (false here): the
+    // script then inherits non-root by construction and can never be host-root.
+    // A root supervisor (true) relies on the namespace wrapper's `--uid` to
+    // drop. Reported as-is so operators can see which model this host uses.
+    supervisorEuidIsRoot: caps.euidIsRoot,
+    rlimits: caps.rlimitNative,
+    wrapper: caps.wrapper,
+    // userNamespaces is now the LIVE clone verdict (not the static sysctl), so
+    // operators see what actually works on this host. userNsCreatable is the
+    // same probe surfaced explicitly for the capability log.
+    userNamespaces: caps.userNamespaces,
+    userNsCreatable: caps.userNsCreatable,
+    netNamespaces: caps.netNamespaces,
+    netEgressIface: caps.netEgressIface,
+    netEgressRootless: caps.netEgressRootless,
+  };
+}
+
+/**
+ * Compute the effective enforcement for a given global default on THIS host,
+ * by running the (pure, synchronous) hardening builder against the detected
+ * capabilities. No spawn, no I/O — used only to report at startup.
+ */
+export function describeEffectiveDefault({
+  policy,
+  caps,
+}: {
+  policy: SandboxPolicy;
+  caps: SandboxCapabilities;
+}): EffectiveSandbox {
+  // The builder may throw under `onUnavailable: "fail"`; the startup probe must
+  // never throw, so force a degrade-mode copy purely for reporting.
+  const reportPolicy: SandboxPolicy = { ...policy, onUnavailable: "degrade" };
+  const hardening = buildSpawnHardening({
+    policy: reportPolicy,
+    caps,
+    baseEnv: pickSafeEnv(),
+  });
+  return hardening.effective;
+}
+
+/**
+ * Emit the one-time startup capability log line for this pod/satellite. Logs
+ * the detected primitives AND the effective enforcement of the supplied global
+ * default (so operators see "what my host actually does", not just "what I
+ * asked for"). Falls back to the shipped safe default when no global default is
+ * supplied.
+ */
+export function logSandboxCapabilitiesAtStartup({
+  logger,
+  globalDefault,
+  caps = detectSandboxCapabilities(),
+}: {
+  logger: SandboxLogger;
+  globalDefault?: SandboxPolicy;
+  caps?: SandboxCapabilities;
+}): void {
+  const policy = globalDefault ?? resolveDefaultSandboxProfile();
+  const effective = describeEffectiveDefault({ policy, caps });
+  logger.info("script sandbox capabilities", {
+    capabilities: summarizeCapabilities(caps),
+    enabled: policy.enabled,
+    enforced: effective.enforced,
+    downgrades: effective.downgrades,
+  });
+}
+
+/**
+ * Build a compact, loggable summary of the per-run downgrades, or `undefined`
+ * when every requested layer was fully enforced (nothing to surface). The call
+ * sites log this as a structured warning and may attach it to the run record so
+ * an operator can see, per run, which layer degraded and why (e.g. the
+ * metadata block being unenforceable on a bwrap-only host).
+ */
+export function summarizeRunDowngrades(
+  effective: EffectiveSandbox | undefined,
+): { layers: string[]; reasons: Record<string, string>; platform: string } | undefined {
+  if (effective === undefined || effective.downgrades.length === 0) {
+    return undefined;
+  }
+  const reasons: Record<string, string> = {};
+  for (const d of effective.downgrades) {
+    // Last reason per layer wins; layers can have at most a couple of entries.
+    reasons[d.layer] = d.reason;
+  }
+  return {
+    layers: effective.downgrades.map((d) => d.layer),
+    reasons,
+    platform: effective.platform,
+  };
+}
+
+/**
+ * Surface per-run sandbox downgrades through the supplied logger as a single
+ * structured warning. A no-op when the run was fully enforced. Centralized so
+ * every call site surfaces degradation identically (plan §5.7: degrade
+ * surfaces, never hides).
+ */
+export function surfaceRunDowngrades({
+  logger,
+  effective,
+}: {
+  logger: SandboxLogger;
+  effective: EffectiveSandbox | undefined;
+}): void {
+  const summary = summarizeRunDowngrades(effective);
+  if (summary !== undefined) {
+    logger.warn(
+      `script sandbox degraded: ${summary.layers.join(", ")} not fully enforced on ${summary.platform}`,
+      summary.reasons,
+    );
+  }
+  // Non-fatal notes (e.g. shell per-run memory bounded by the cgroup, or
+  // RLIMIT_NPROC not applied under a non-root supervisor) are surfaced at INFO,
+  // separate from downgrades: they are accepted, expected states, not failures
+  // to enforce the requested policy.
+  if (effective !== undefined && effective.notes.length > 0) {
+    const noteReasons: Record<string, string> = {};
+    for (const n of effective.notes) {
+      noteReasons[n.layer] = n.note;
+    }
+    logger.info(
+      `script sandbox notes (${effective.notes.map((n) => n.layer).join(", ")}) on ${effective.platform}`,
+      noteReasons,
+    );
+  }
+}

package/src/script-sandbox/output-truncation.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "bun:test";
+import { truncateCapturedOutput } from "./output-truncation";
+
+describe("truncateCapturedOutput", () => {
+  it("passes through unchanged when no cap is set", () => {
+    const r = truncateCapturedOutput({
+      stdout: "a".repeat(100),
+      stderr: "b".repeat(100),
+      maxOutputBytes: undefined,
+    });
+    expect(r.truncated).toBe(false);
+    expect(r.stdout.length).toBe(100);
+    expect(r.stderr.length).toBe(100);
+  });
+
+  it("passes through unchanged when under the cap", () => {
+    const r = truncateCapturedOutput({
+      stdout: "hello",
+      stderr: "world",
+      maxOutputBytes: 100,
+    });
+    expect(r.truncated).toBe(false);
+    expect(r.stdout).toBe("hello");
+    expect(r.stderr).toBe("world");
+  });
+
+  it("trims and flags when combined output exceeds the cap", () => {
+    const r = truncateCapturedOutput({
+      stdout: "a".repeat(80),
+      stderr: "b".repeat(80),
+      maxOutputBytes: 100,
+    });
+    expect(r.truncated).toBe(true);
+    const total = Buffer.byteLength(r.stdout) + Buffer.byteLength(r.stderr);
+    expect(total).toBeLessThanOrEqual(100);
+    // stdout is preserved first.
+    expect(r.stdout.length).toBe(80);
+    expect(r.stderr.length).toBe(20);
+  });
+
+  it("does not split a multi-byte code point", () => {
+    // Each emoji is 4 UTF-8 bytes.
+    const r = truncateCapturedOutput({
+      stdout: "😀😀😀😀😀", // 20 bytes
+      stderr: "",
+      maxOutputBytes: 10, // fits 2 full emoji (8 bytes)
+    });
+    expect(r.truncated).toBe(true);
+    expect(Buffer.byteLength(r.stdout)).toBeLessThanOrEqual(10);
+    // No replacement char / partial byte: re-encoding must be lossless.
+    expect(Buffer.byteLength(r.stdout) % 4).toBe(0);
+  });
+});

package/src/script-sandbox/output-truncation.ts

@@ -0,0 +1,69 @@
+/**
+ * Portable runner-side output truncation. Enforces `maxOutputBytes` by
+ * counting the combined byte length of captured stdout+stderr and trimming
+ * once the cap is exceeded. Works identically on every platform (pure JS),
+ * so it is the portable-subset fallback for the resource layer (plan §5.1).
+ */
+
+const encoder = new TextEncoder();
+
+export interface TruncateOutputResult {
+  stdout: string;
+  stderr: string;
+  /** True when the combined output exceeded the cap and was trimmed. */
+  truncated: boolean;
+}
+
+/**
+ * Trim `stdout`/`stderr` so their combined UTF-8 byte length does not exceed
+ * `maxOutputBytes`. stdout is preserved first; stderr gets whatever budget
+ * remains. When `maxOutputBytes` is undefined the inputs pass through
+ * unchanged.
+ */
+export function truncateCapturedOutput({
+  stdout,
+  stderr,
+  maxOutputBytes,
+}: {
+  stdout: string;
+  stderr: string;
+  maxOutputBytes: number | undefined;
+}): TruncateOutputResult {
+  if (maxOutputBytes === undefined) {
+    return { stdout, stderr, truncated: false };
+  }
+
+  const stdoutBytes = encoder.encode(stdout).length;
+  const stderrBytes = encoder.encode(stderr).length;
+  if (stdoutBytes + stderrBytes <= maxOutputBytes) {
+    return { stdout, stderr, truncated: false };
+  }
+
+  // Give stdout up to the full budget, then stderr the remainder.
+  const trimmedStdout = trimToBytes(stdout, maxOutputBytes);
+  const stdoutFinalBytes = encoder.encode(trimmedStdout).length;
+  const stderrBudget = Math.max(0, maxOutputBytes - stdoutFinalBytes);
+  const trimmedStderr = trimToBytes(stderr, stderrBudget);
+
+  return { stdout: trimmedStdout, stderr: trimmedStderr, truncated: true };
+}
+
+/**
+ * Trim a string to at most `maxBytes` UTF-8 bytes without splitting a
+ * multi-byte code point. Falls back to a character-wise walk only when a
+ * fast slice would land mid-character.
+ */
+function trimToBytes(value: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  if (encoder.encode(value).length <= maxBytes) return value;
+
+  let result = "";
+  let bytes = 0;
+  for (const char of value) {
+    const charBytes = encoder.encode(char).length;
+    if (bytes + charBytes > maxBytes) break;
+    result += char;
+    bytes += charBytes;
+  }
+  return result;
+}

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

@@ -0,0 +1,189 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  DEFAULT_SANDBOX_PROFILE,
+  mergeSandboxPolicy,
+  resolveDefaultSandboxProfile,
+  SANDBOX_GID_ENV,
+  SANDBOX_UID_ENV,
+  sandboxPolicySchema,
+} from "./policy";
+
+describe("sandboxPolicySchema", () => {
+  it("defaults enabled to true (D1: on-by-default)", () => {
+    const parsed = sandboxPolicySchema.parse({});
+    expect(parsed.enabled).toBe(true);
+  });
+
+  it("applies conservative bare field defaults", () => {
+    const parsed = sandboxPolicySchema.parse({});
+    expect(parsed.onUnavailable).toBe("degrade");
+    expect(parsed.filesystem.mode).toBe("off");
+    expect(parsed.network.mode).toBe("unrestricted");
+    expect(parsed.network.denyLinkLocalAndMetadata).toBe(true);
+    expect(parsed.privilege.mode).toBe("inherit");
+    expect(parsed.resources).toEqual({});
+  });
+
+  it("rejects unknown top-level keys (.strict)", () => {
+    expect(() =>
+      sandboxPolicySchema.parse({ bogus: true }),
+    ).toThrow();
+  });
+
+  it("rejects unknown nested keys (.strict)", () => {
+    expect(() =>
+      sandboxPolicySchema.parse({ resources: { bogus: 1 } }),
+    ).toThrow();
+  });
+
+  it("enforces resource bounds", () => {
+    expect(() =>
+      sandboxPolicySchema.parse({ resources: { cpuSeconds: 0 } }),
+    ).toThrow();
+    expect(() =>
+      sandboxPolicySchema.parse({ resources: { cpuSeconds: 99999 } }),
+    ).toThrow();
+  });
+
+  it("DEFAULT_SANDBOX_PROFILE round-trips through the schema", () => {
+    const reparsed = sandboxPolicySchema.parse(DEFAULT_SANDBOX_PROFILE);
+    expect(reparsed).toEqual(DEFAULT_SANDBOX_PROFILE);
+    expect(reparsed.filesystem.mode).toBe("scratch-plus-ro");
+    expect(reparsed.privilege.mode).toBe("drop-to-uid");
+  });
+
+  it("DEFAULT_SANDBOX_PROFILE is secure-by-default (deny egress until allowlisted)", () => {
+    // Network is an allowlist with an EMPTY allow list = egress denied until an
+    // operator adds entries (NOT unrestricted); plus the always-on
+    // metadata/link-local block. Generous resource caps sized as headroom, not
+    // work limits; FS confined to scratch + RO node_modules.
+    expect(DEFAULT_SANDBOX_PROFILE.enabled).toBe(true);
+    // Fail-closed by default: refuse the run when a layer can't be enforced.
+    expect(DEFAULT_SANDBOX_PROFILE.onUnavailable).toBe("fail");
+    expect(DEFAULT_SANDBOX_PROFILE.network.mode).toBe("allowlist");
+    expect(DEFAULT_SANDBOX_PROFILE.network.allow).toEqual([]);
+    expect(DEFAULT_SANDBOX_PROFILE.network.denyLinkLocalAndMetadata).toBe(true);
+    expect(DEFAULT_SANDBOX_PROFILE.filesystem.mode).toBe("scratch-plus-ro");
+    expect(DEFAULT_SANDBOX_PROFILE.resources.cpuSeconds).toBe(60);
+    expect(DEFAULT_SANDBOX_PROFILE.resources.memoryBytes).toBe(512 * 1024 * 1024);
+    expect(DEFAULT_SANDBOX_PROFILE.resources.maxProcesses).toBe(256);
+    // No UID baked into the constant; the dedicated target is seeded at runtime.
+    expect(DEFAULT_SANDBOX_PROFILE.privilege.uid).toBeUndefined();
+  });
+
+  it("DEFAULT_SANDBOX_PROFILE fails closed (onUnavailable=fail, never silent degrade)", () => {
+    // The shipped global default REFUSES a run when a requested layer cannot be
+    // enforced rather than silently dropping to a weaker subset. This is the
+    // single most security-relevant default: a malicious script must not slip
+    // through on a host missing a sandbox primitive.
+    expect(DEFAULT_SANDBOX_PROFILE.onUnavailable).toBe("fail");
+  });
+});
+
+describe("resolveDefaultSandboxProfile", () => {
+  afterEach(() => {
+    delete process.env[SANDBOX_UID_ENV];
+    delete process.env[SANDBOX_GID_ENV];
+  });
+
+  it("returns the base profile (no UID) when the env is unset", () => {
+    delete process.env[SANDBOX_UID_ENV];
+    delete process.env[SANDBOX_GID_ENV];
+    const resolved = resolveDefaultSandboxProfile();
+    expect(resolved.privilege.uid).toBeUndefined();
+    expect(resolved.privilege.gid).toBeUndefined();
+    expect(resolved.privilege.mode).toBe("drop-to-uid");
+  });
+
+  it("seeds the dedicated low-priv UID/GID from the environment", () => {
+    process.env[SANDBOX_UID_ENV] = "65534";
+    process.env[SANDBOX_GID_ENV] = "65534";
+    const resolved = resolveDefaultSandboxProfile();
+    expect(resolved.privilege.uid).toBe(65534);
+    expect(resolved.privilege.gid).toBe(65534);
+  });
+
+  it("ignores a GID with no UID (a gid-only drop is not meaningful)", () => {
+    delete process.env[SANDBOX_UID_ENV];
+    process.env[SANDBOX_GID_ENV] = "65534";
+    const resolved = resolveDefaultSandboxProfile();
+    expect(resolved.privilege.uid).toBeUndefined();
+    expect(resolved.privilege.gid).toBeUndefined();
+  });
+
+  it("treats a malformed UID as unconfigured (no crash, degrades later)", () => {
+    process.env[SANDBOX_UID_ENV] = "not-a-number";
+    const resolved = resolveDefaultSandboxProfile();
+    expect(resolved.privilege.uid).toBeUndefined();
+  });
+
+  it("still validates against the schema", () => {
+    process.env[SANDBOX_UID_ENV] = "1000";
+    const resolved = resolveDefaultSandboxProfile();
+    expect(() => sandboxPolicySchema.parse(resolved)).not.toThrow();
+  });
+});
+
+describe("mergeSandboxPolicy", () => {
+  it("returns base unchanged when override is undefined", () => {
+    const merged = mergeSandboxPolicy({ base: DEFAULT_SANDBOX_PROFILE });
+    expect(merged).toEqual(DEFAULT_SANDBOX_PROFILE);
+  });
+
+  it("per-item override wins per-field without re-widening other layers", () => {
+    const merged = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: { network: { mode: "deny" } },
+    });
+    // network.mode overridden...
+    expect(merged.network.mode).toBe("deny");
+    // ...but the metadata block + other layers stay from the base, NOT the
+    // bare zod defaults.
+    expect(merged.network.denyLinkLocalAndMetadata).toBe(true);
+    expect(merged.resources.cpuSeconds).toBe(60);
+    expect(merged.filesystem.mode).toBe("scratch-plus-ro");
+    expect(merged.privilege.mode).toBe("drop-to-uid");
+  });
+
+  it("a single resource field override keeps the other caps", () => {
+    const merged = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: { resources: { memoryBytes: 2 * 1024 * 1024 * 1024 } },
+    });
+    expect(merged.resources.memoryBytes).toBe(2 * 1024 * 1024 * 1024);
+    expect(merged.resources.cpuSeconds).toBe(60);
+    expect(merged.resources.maxProcesses).toBe(256);
+  });
+
+  it("enabled:false override opts out without touching the rest", () => {
+    const merged = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: { enabled: false },
+    });
+    expect(merged.enabled).toBe(false);
+  });
+
+  it("onUnavailable override is honored", () => {
+    const merged = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: { onUnavailable: "fail" },
+    });
+    expect(merged.onUnavailable).toBe("fail");
+  });
+
+  it("a fully-resolved override (the global durable default) replaces every layer", () => {
+    // This is the call-site shape: the global durable default is itself a
+    // fully-resolved SandboxPolicy passed as the override; merging it over the
+    // runner's DEFAULT_SANDBOX_PROFILE base must yield exactly that override
+    // (idempotent), so the global setting wins end-to-end.
+    const globalDefault = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: { network: { mode: "deny" }, resources: { cpuSeconds: 30 } },
+    });
+    const merged = mergeSandboxPolicy({
+      base: DEFAULT_SANDBOX_PROFILE,
+      override: globalDefault,
+    });
+    expect(merged).toEqual(globalDefault);
+  });
+});