@sagentlab/navarch-runtime 0.1.32 → 0.1.33

package/README.md

@@ -299,6 +299,8 @@ unchanged across the deployment.
 | `NAVARCH_WORKTREE_STALE_AFTER_MS` | `86400000` (24 hours) | Minimum inactivity age before an abandoned session worktree is removed. Active sessions are always protected. |
 | `NAVARCH_GIT_AUTHOR_NAME` / `NAVARCH_GIT_AUTHOR_EMAIL` | `sagentlab` / `z@sagentlab.com` | Git identity forced into session commits so host-level personal config is not inherited; override both for a project-authorized bot. |
 | `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
+| `NAVARCH_SANDBOX_PROFILE` | `trusted-development` | Named security profile for Docker sessions (`src/sandbox-profile.cts`): `trusted-development` (image-default user, uncapped, open egress), `untrusted-code` (non-root, 2 CPU / 4g / 512 PIDs, deny-by-default egress, read-only shared git), `elevated-verification` (non-root, 4 CPU / 8g / 2048 PIDs, egress limited to GitHub plus package registries). The default is the exact pre-profile flag set. |
+| `NAVARCH_SANDBOX_EGRESS_NETWORK` | _(unset)_ | Docker network that enforces a profile's egress allowlist. Docker cannot filter by domain itself, so an allowlist profile without this fails closed to `--network=none` and records the denial. |
 | `NAVARCH_DOCKER_IMAGE` | `ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0` | Version-pinned per-session image with Node 20, git, GitHub CLI, ripgrep, jq, SSH, and Claude Code 2.1.218. Override with an image tag or digest you control. |
 | `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code`, `codex`, `gemini`, or `opencode`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_RUNTIMES` | selected `NAVARCH_AGENT` | Comma list of installed/authenticated adapters advertised to dispatch. The control plane chooses among these per project/task. |

package/dist/config.cjs

@@ -8,6 +8,7 @@ exports.isRuntimeAgentType = isRuntimeAgentType;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+const sandbox_profile_cjs_1 = require("./sandbox-profile.cjs");
 /** Published image containing git, GitHub CLI, and the pinned Claude Code CLI. */
 exports.DEFAULT_SANDBOX_IMAGE = "ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0";
 function isRuntimeAgentType(value) {
@@ -86,6 +87,13 @@ function loadRuntimeConfig(env = process.env) {
         gitAuthorEmail: env.NAVARCH_GIT_AUTHOR_EMAIL ?? "z@sagentlab.com",
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
         sandboxMode,
+        // An unrecognized profile name falls back to the default rather than
+        // failing startup: a typo must not silently drop a machine out of the
+        // dispatch pool, and the default is the posture sessions already had.
+        sandboxProfile: (0, sandbox_profile_cjs_1.isSandboxProfileId)(env.NAVARCH_SANDBOX_PROFILE)
+            ? env.NAVARCH_SANDBOX_PROFILE
+            : sandbox_profile_cjs_1.DEFAULT_SANDBOX_PROFILE_ID,
+        sandboxEgressNetwork: env.NAVARCH_SANDBOX_EGRESS_NETWORK?.trim() || null,
         dockerImage: env.NAVARCH_DOCKER_IMAGE ?? exports.DEFAULT_SANDBOX_IMAGE,
         // Multiple sessions share one machine; keeping each agent inside its own
         // worktree is the safe default, so disabling is the explicit opt-out.

package/dist/sandbox-profile.cjs

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Named sandbox security profiles (issue #660).
+ *
+ * A profile is the *declared* security posture of one session: which user the
+ * agent runs as, what resources it may consume, which host paths it may see,
+ * and where it may reach on the network. `dockerRunFlags()` /
+ * `resolveMounts()` / `resolveNetwork()` turn that declaration into concrete
+ * `docker run` arguments, so the policy is written once and audited in one
+ * place rather than being spread across ad-hoc flags in sandbox.cts.
+ *
+ * NOTE ON NAMING: `SandboxPolicyDenial` here is a *security policy* denial (a
+ * mount outside the allowlist, an unenforceable egress allowlist). It is
+ * deliberately NOT the same concept as `SandboxDenialReason` in
+ * lib/navarch/sandbox.ts, which is free-tier billing/eligibility. Do not
+ * conflate the two.
+ *
+ * DEFAULT: `trusted-development` reproduces the pre-#660 Docker flags exactly
+ * — root user, no resource caps, Docker's default bridge network — so
+ * adopting profiles is a pure refactor for every existing session. The
+ * hardened postures are opt-in via NAVARCH_SANDBOX_PROFILE until the default
+ * flip is validated on real workloads.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SANDBOX_PROFILE_ID = exports.GITHUB_EGRESS_ALLOWLIST = exports.SANDBOX_PROFILE_IDS = void 0;
+exports.isSandboxProfileId = isSandboxProfileId;
+exports.resolveSandboxProfile = resolveSandboxProfile;
+exports.resolveMounts = resolveMounts;
+exports.resolveNetwork = resolveNetwork;
+exports.dockerRunFlags = dockerRunFlags;
+const node_path_1 = __importDefault(require("node:path"));
+exports.SANDBOX_PROFILE_IDS = [
+    "trusted-development",
+    "untrusted-code",
+    "elevated-verification",
+];
+function isSandboxProfileId(value) {
+    return exports.SANDBOX_PROFILE_IDS.includes(value ?? "");
+}
+/** tmpfs mounts every profile shares: injected secrets must never hit a disk. */
+const SECRET_TMPFS = ["/tmp", "/run"];
+const BASE_SECRETS = {
+    allowEnvFlagInjection: false,
+    tmpfs: SECRET_TMPFS,
+};
+/**
+ * The GitHub egress worktree-guard.cts already grants host-mode Codex
+ * sessions (`**.github.com` / `**.githubusercontent.com`). Container profiles
+ * reuse the same set so a session cannot reach more from inside the sandbox
+ * than the host-mode guard would have allowed.
+ */
+exports.GITHUB_EGRESS_ALLOWLIST = [
+    "**.github.com",
+    "**.githubusercontent.com",
+];
+/** Registries an elevated verification run needs to install dependencies from. */
+const PACKAGE_REGISTRY_ALLOWLIST = [
+    "registry.npmjs.org",
+    "**.pypi.org",
+    "**.crates.io",
+];
+const PROFILES = {
+    // Byte-for-byte the pre-#660 flag set. Changing anything here changes the
+    // behavior of every existing dispatch — see sandbox.test.cts, which pins
+    // the resulting argv exactly.
+    "trusted-development": {
+        id: "trusted-development",
+        description: "First-party repositories run by the operator's own agents. Image-default user, no resource caps, unrestricted egress — the pre-#660 Docker posture.",
+        user: null,
+        memory: null,
+        cpus: null,
+        pidsLimit: null,
+        capDrop: ["ALL"],
+        securityOpt: ["no-new-privileges"],
+        network: { mode: "open", allow: [] },
+        mounts: { allow: ["workspace", "shared-git"], readOnly: [] },
+        secrets: BASE_SECRETS,
+    },
+    // Tightest posture: non-root, capped, GitHub-only egress that fails closed,
+    // and the shared bare repo mounted read-only so a hostile checkout cannot
+    // rewrite objects other sessions' worktrees depend on.
+    "untrusted-code": {
+        id: "untrusted-code",
+        description: "Third-party or unreviewed code. Non-root, hard CPU/memory/PID caps, deny-by-default egress with a GitHub allowlist, read-only shared git.",
+        user: "1000:1000",
+        memory: "4g",
+        cpus: "2",
+        pidsLimit: 512,
+        capDrop: ["ALL"],
+        securityOpt: ["no-new-privileges"],
+        network: { mode: "allowlist", allow: exports.GITHUB_EGRESS_ALLOWLIST },
+        mounts: { allow: ["workspace", "shared-git"], readOnly: ["shared-git"] },
+        secrets: BASE_SECRETS,
+    },
+    // Verification workloads (build + full test suite) need real resources and
+    // package registries, but stay non-root and stay off the open internet.
+    "elevated-verification": {
+        id: "elevated-verification",
+        description: "Build/test verification of reviewed code. Non-root with raised CPU/memory/PID caps and egress limited to GitHub plus package registries.",
+        user: "1000:1000",
+        memory: "8g",
+        cpus: "4",
+        pidsLimit: 2048,
+        capDrop: ["ALL"],
+        securityOpt: ["no-new-privileges"],
+        network: {
+            mode: "allowlist",
+            allow: [...exports.GITHUB_EGRESS_ALLOWLIST, ...PACKAGE_REGISTRY_ALLOWLIST],
+        },
+        mounts: { allow: ["workspace", "shared-git"], readOnly: [] },
+        secrets: BASE_SECRETS,
+    },
+};
+exports.DEFAULT_SANDBOX_PROFILE_ID = "trusted-development";
+/**
+ * The profile for `id`, with the operator's egress network (if any) bound in.
+ * Returns a fresh object each call so callers cannot mutate the shared table.
+ */
+function resolveSandboxProfile(id = exports.DEFAULT_SANDBOX_PROFILE_ID, options = {}) {
+    const base = PROFILES[id];
+    return {
+        ...base,
+        network: { ...base.network, egressNetwork: options.egressNetwork ?? null },
+        mounts: { ...base.mounts },
+        secrets: { ...base.secrets },
+    };
+}
+/**
+ * `-v` arguments for the requests this profile permits, plus a denial for
+ * each one it refuses. Denied mounts are dropped, not fatal: the session
+ * still starts with the mounts it is entitled to, and the refusal is recorded.
+ */
+function resolveMounts(profile, requests) {
+    const args = [];
+    const denials = [];
+    for (const request of requests) {
+        if (!profile.mounts.allow.includes(request.kind)) {
+            denials.push({
+                policy: "mount",
+                code: "mount_kind_not_allowed",
+                detail: `profile ${profile.id} does not allow "${request.kind}" mounts (${request.hostPath})`,
+            });
+            continue;
+        }
+        if (!isInside(request.hostPath, request.allowedRoot)) {
+            denials.push({
+                policy: "mount",
+                code: "mount_outside_allowed_root",
+                detail: `${request.hostPath} is outside the allowed root ${request.allowedRoot} for "${request.kind}" mounts`,
+            });
+            continue;
+        }
+        const suffix = profile.mounts.readOnly.includes(request.kind) ? ":ro" : "";
+        args.push("-v", `${request.hostPath}:${request.containerPath}${suffix}`);
+    }
+    return { args, denials };
+}
+/** Same containment test worktree-guard.cts uses for its allowed roots. */
+function isInside(candidate, root) {
+    const relative = node_path_1.default.relative(node_path_1.default.resolve(root), node_path_1.default.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative));
+}
+/**
+ * `--network` argument for this policy. An `allowlist` policy with no
+ * enforcing network degrades to `--network=none` (deny-by-default) and
+ * records the denial — it never degrades to open egress.
+ */
+function resolveNetwork(policy) {
+    switch (policy.mode) {
+        case "open":
+            // No flag at all: Docker's default bridge, identical to pre-#660.
+            return { args: [], denials: [] };
+        case "isolated":
+            return { args: ["--network=none"], denials: [] };
+        case "allowlist": {
+            const network = policy.egressNetwork?.trim();
+            if (network)
+                return { args: ["--network", network], denials: [] };
+            return {
+                args: ["--network=none"],
+                denials: [
+                    {
+                        policy: "network",
+                        code: "egress_allowlist_unenforceable",
+                        detail: `no egress network configured (NAVARCH_SANDBOX_EGRESS_NETWORK); denying all egress instead of allowing ${policy.allow.join(", ")}`,
+                    },
+                ],
+            };
+        }
+    }
+}
+/**
+ * Hardening + resource + network flags for `docker run`, in a fixed order.
+ * Mounts are resolved separately (they need per-session paths) and appended
+ * by the backend.
+ *
+ * Order matters only for the equivalence test that pins the default profile's
+ * argv against the pre-#660 command line; Docker itself is order-insensitive
+ * among these.
+ */
+function dockerRunFlags(profile) {
+    const args = [];
+    for (const cap of profile.capDrop)
+        args.push(`--cap-drop=${cap}`);
+    for (const opt of profile.securityOpt)
+        args.push(`--security-opt=${opt}`);
+    for (const mount of profile.secrets.tmpfs)
+        args.push("--tmpfs", mount);
+    if (profile.user)
+        args.push("--user", profile.user);
+    if (profile.memory)
+        args.push("--memory", profile.memory);
+    if (profile.cpus)
+        args.push("--cpus", profile.cpus);
+    if (profile.pidsLimit !== null)
+        args.push("--pids-limit", String(profile.pidsLimit));
+    const network = resolveNetwork(profile.network);
+    args.push(...network.args);
+    return { args, denials: network.denials };
+}

package/dist/sandbox.cjs

@@ -8,6 +8,7 @@ exports.isDockerAvailable = isDockerAvailable;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
+const sandbox_profile_cjs_1 = require("./sandbox-profile.cjs");
 class SandboxUnavailableError extends Error {
 }
 exports.SandboxUnavailableError = SandboxUnavailableError;
@@ -85,45 +86,92 @@ function containerName(sessionId) {
  * helper, so the literal secret value never appears in any argv the host's
  * `ps` can see and is never written to the container's persistent layer
  * (tmpfs only) — it disappears with the container on wipe().
+ *
+ * Since #660 every one of those flags comes from a named security profile
+ * (sandbox-profile.cts) rather than being hard-coded here, and this class is
+ * the `SandboxBackend` implementation for Docker rather than the only sandbox
+ * there can be. The default profile (`trusted-development`) emits exactly the
+ * flag set above, so nothing about an existing session changed.
  */
 class DockerSandbox {
+    id = "docker";
     name;
+    image;
+    profile;
     runner;
+    workspaceRoot;
     workDir;
-    image;
     containerWorkDir;
     sharedGitDir;
+    appliedFlags = [];
+    denials = [];
     constructor(opts) {
         this.name = containerName(opts.sessionId);
         this.runner = opts.runner ?? exports.nodeCommandRunner;
+        this.workspaceRoot = opts.workspaceRoot;
         this.workDir = node_path_1.default.join(opts.workspaceRoot, opts.sessionId);
         this.image = opts.image;
         this.containerWorkDir = opts.containerWorkDir ?? null;
         this.sharedGitDir = opts.sharedGitDir ?? null;
+        this.profile = opts.profile ?? (0, sandbox_profile_cjs_1.resolveSandboxProfile)(sandbox_profile_cjs_1.DEFAULT_SANDBOX_PROFILE_ID);
+    }
+    /**
+     * Host paths this session wants mounted, each pinned to the root it must
+     * stay under so resolveMounts() can refuse anything else.
+     *
+     * - workspace  ⊂ the sessions root this sandbox was constructed with, so a
+     *   crafted session id containing `..` cannot mount a sibling session or
+     *   escape the workspace entirely.
+     * - shared-git ⊂ the Navarch workspace root (the sessions root's parent).
+     *   session.cts passes `<workspaceRoot>/sessions` here and GitWorktree puts
+     *   the bare repo cache at the sibling `<workspaceRoot>/repositories/...`
+     *   (or inside the session root for repo-local-token sessions), so both
+     *   legitimate locations are covered while `~/.ssh` or `/` are not.
+     */
+    mountRequests() {
+        const sessionsRoot = node_path_1.default.resolve(this.workspaceRoot);
+        const navarchRoot = node_path_1.default.dirname(sessionsRoot);
+        if (!this.containerWorkDir) {
+            return [
+                {
+                    kind: "workspace",
+                    hostPath: this.workDir,
+                    containerPath: "/workspace",
+                    allowedRoot: sessionsRoot,
+                },
+            ];
+        }
+        const requests = [
+            {
+                kind: "workspace",
+                hostPath: this.workDir,
+                containerPath: this.workDir,
+                allowedRoot: sessionsRoot,
+            },
+        ];
+        if (this.sharedGitDir) {
+            requests.push({
+                kind: "shared-git",
+                hostPath: this.sharedGitDir,
+                containerPath: this.sharedGitDir,
+                allowedRoot: navarchRoot,
+            });
+        }
+        return requests;
     }
     async create() {
         await node_fs_1.promises.mkdir(this.workDir, { recursive: true });
-        const mounts = this.containerWorkDir
-            ? [
-                "-v",
-                `${this.workDir}:${this.workDir}`,
-                ...(this.sharedGitDir ? ["-v", `${this.sharedGitDir}:${this.sharedGitDir}`] : []),
-                "-w",
-                this.containerWorkDir,
-            ]
-            : ["-v", `${this.workDir}:/workspace`, "-w", "/workspace"];
+        const policy = (0, sandbox_profile_cjs_1.dockerRunFlags)(this.profile);
+        const mounts = (0, sandbox_profile_cjs_1.resolveMounts)(this.profile, this.mountRequests());
+        this.denials.push(...policy.denials, ...mounts.denials);
+        const workdir = this.containerWorkDir ?? "/workspace";
+        this.appliedFlags = [...policy.args, ...mounts.args, "-w", workdir];
         const result = await this.runner.run("docker", [
             "run",
             "-d",
             "--name",
             this.name,
-            "--cap-drop=ALL",
-            "--security-opt=no-new-privileges",
-            "--tmpfs",
-            "/tmp",
-            "--tmpfs",
-            "/run",
-            ...mounts,
+            ...this.appliedFlags,
             this.image,
             "tail",
             "-f",
@@ -164,6 +212,39 @@ class DockerSandbox {
             : `git clone --depth 1 ${shellQuote(url)} repo`;
         return this.exec(command);
     }
+    /**
+     * Copies one container path out to `<workDir>/artifacts/<artifactName>` and
+     * returns that host path, or null when it could not be retrieved.
+     * Best-effort by contract: evidence collection never fails a session, and
+     * the artifact root lives beside the workspace so wipe() removes it too.
+     */
+    async collectArtifact(containerPath, artifactName) {
+        const artifactRoot = node_path_1.default.join(this.workDir, "artifacts");
+        const destination = node_path_1.default.join(artifactRoot, artifactName);
+        try {
+            await node_fs_1.promises.mkdir(artifactRoot, { recursive: true });
+            const result = await this.runner.run("docker", [
+                "cp",
+                `${this.name}:${containerPath}`,
+                destination,
+            ]);
+            return result.code === 0 ? destination : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Profile/flag/denial metadata for run evidence and the sessions audit columns. */
+    describe() {
+        return {
+            backend: this.id,
+            profile: this.profile.id,
+            image: this.image,
+            name: this.name,
+            appliedFlags: [...this.appliedFlags],
+            denials: [...this.denials],
+        };
+    }
     /** Force-removes the container and the host-side workspace mount. Best-effort: never throws. */
     async wipe() {
         await this.stop();

package/dist/session.cjs

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
 const api_cjs_1 = require("./api.cjs");
 const sandbox_cjs_1 = require("./sandbox.cjs");
+const sandbox_profile_cjs_1 = require("./sandbox-profile.cjs");
 const index_cjs_1 = require("./adapters/index.cjs");
 const exit_conditions_cjs_1 = require("./exit-conditions.cjs");
 const redact_cjs_1 = require("./redact.cjs");
@@ -109,10 +110,19 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     : "best",
         reasoning_effort: "medium",
     };
+    // Isolation posture reported on every completion so `sessions` records what
+    // a run actually executed under (#660). Derived from config alone, so the
+    // pre-start failure paths below can stamp it too. Host mode records
+    // "host" — an honest answer to "what isolated this run?", not a profile id.
+    const sandboxReport = {
+        sandbox_profile: config.sandboxMode === "docker" ? config.sandboxProfile : "host",
+        ...(config.sandboxMode === "docker" ? { sandbox_image: config.dockerImage } : {}),
+    };
     const executionReport = {
         model: execution.model,
         execution_profile: execution.profile,
         reasoning_effort: execution.reasoning_effort,
+        ...sandboxReport,
     };
     // The session's identity is the pre-allocated session id sent at claim time
     // (recorded on the lease by the dispatcher). Lease-scoped API calls
@@ -252,6 +262,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             image: config.dockerImage,
             containerWorkDir: gitWorktree.worktreePath,
             sharedGitDir: gitWorktree.repositoryPath,
+            profile: (0, sandbox_profile_cjs_1.resolveSandboxProfile)(config.sandboxProfile, {
+                egressNetwork: config.sandboxEgressNetwork,
+            }),
         })
         : null;
     // Platform MCP config (implementation-plan.md WP-07: "--mcp-config
@@ -333,6 +346,12 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         await gitWorktree.prepare();
         if (sandbox) {
             await sandbox.create();
+            // Security-policy refusals (a mount outside the allowlist, an egress
+            // allowlist with no network able to enforce it). Unrelated to the
+            // billing-tier SandboxDenialReason in lib/navarch/sandbox.ts.
+            for (const denial of sandbox.describe().denials) {
+                log.warn(`sandbox policy denial [${denial.policy}/${denial.code}]: ${denial.detail}`);
+            }
             await sandbox.injectEnv(sessionEnv);
         }
         // The control plane returns the agent type selected for this worker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
   "type": "commonjs",
   "license": "MIT",