Skip to content

Commit a8eceb3

Browse files
committed
feat(policy): add declarative host mount schema, validation, and CLI (NVIDIA#1045)
- Add mounts: section to openclaw-sandbox.yaml policy schema - Add MountConfig type, validateMountPath, loadPolicyMounts in runner.ts - Refactor buildPlan() as single source of truth for plan construction - Add bin/lib/mounts.js for policy YAML mount management - Add mount-list and mount-add CLI commands to nemoclaw CLI - Emit warning when mounts declared but OpenShell lacks --volume support - Add test coverage for validation and YAML parsing - Runtime enforcement pending upstream NVIDIA/OpenShell#500
1 parent bdd61da commit a8eceb3

7 files changed

Lines changed: 591 additions & 36 deletions

File tree

‎bin/lib/mounts.js‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
//
4+
// Mount management — read and write the mounts: section of the policy YAML.
5+
6+
const fs = require("fs");
7+
const path = require("path");
8+
const { ROOT } = require("./runner");
9+
10+
const POLICY_FILE = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
11+
12+
/**
13+
* Validate an absolute Unix path: must start with /, no null bytes, no .. components.
14+
* Returns the path unchanged on success; throws on failure.
15+
*/
16+
// Keep in sync with nemoclaw/src/blueprint/runner.ts:validateMountPath
17+
function validateMountPath(p, label) {
18+
if (!p || typeof p !== "string") throw new Error(`${label} is required`);
19+
if (!p.startsWith("/")) throw new Error(`${label} must be an absolute path: ${p}`);
20+
if (p.includes("\0")) throw new Error(`${label} must not contain null bytes`);
21+
if (p.split("/").some((s) => s === "..")) {
22+
throw new Error(`${label} must not contain path traversal: ${p}`);
23+
}
24+
return p;
25+
}
26+
27+
/**
28+
* Parse the mounts: section from raw policy YAML using a line-oriented state
29+
* machine. Returns an array of { host_path, container_path, read_only } objects.
30+
* Returns [] if the section is absent or empty.
31+
*/
32+
function parseMountsFromYaml(content) {
33+
const mounts = [];
34+
const lines = content.split("\n");
35+
let inMounts = false;
36+
let current = null;
37+
38+
for (const line of lines) {
39+
// Top-level mounts: key (possibly with inline empty list)
40+
if (/^mounts\s*:/.test(line)) {
41+
inMounts = true;
42+
// Inline empty: mounts: [] — nothing to collect
43+
continue;
44+
}
45+
46+
// Any non-indented, non-empty, non-comment line ends the section
47+
if (inMounts && line !== "" && /^\S/.test(line) && !line.startsWith("#")) {
48+
if (current) { mounts.push(current); current = null; }
49+
inMounts = false;
50+
continue;
51+
}
52+
53+
if (!inMounts) continue;
54+
55+
const trimmed = line.trim();
56+
if (!trimmed || trimmed.startsWith("#")) continue;
57+
58+
// New list item: " - host_path: ..."
59+
if (/^\s+-\s+\w/.test(line)) {
60+
if (current) mounts.push(current);
61+
current = {};
62+
parseKv(trimmed.replace(/^-\s+/, ""), current);
63+
continue;
64+
}
65+
66+
// Continuation key inside current item
67+
if (current && /^\s+\w/.test(line)) {
68+
parseKv(trimmed, current);
69+
}
70+
}
71+
72+
if (current) mounts.push(current);
73+
74+
return mounts.filter(
75+
(m) => typeof m.host_path === "string" && typeof m.container_path === "string",
76+
);
77+
}
78+
79+
function parseKv(line, obj) {
80+
const m = line.match(/^([\w]+)\s*:\s*(.*)$/);
81+
if (!m) return;
82+
const key = m[1];
83+
const raw = m[2].trim();
84+
if (raw === "true") obj[key] = true;
85+
else if (raw === "false") obj[key] = false;
86+
else obj[key] = raw;
87+
}
88+
89+
/**
90+
* Append a new mount entry to the mounts: section of the policy YAML in-place.
91+
* Returns true if written, false if the entry was already present.
92+
* Throws if the policy file does not exist.
93+
*/
94+
function addMountToPolicy(hostPath, containerPath, readOnly) {
95+
if (!fs.existsSync(POLICY_FILE)) {
96+
throw new Error(`Policy file not found: ${POLICY_FILE}`);
97+
}
98+
99+
const content = fs.readFileSync(POLICY_FILE, "utf-8");
100+
const existing = parseMountsFromYaml(content);
101+
102+
if (existing.some((m) => m.host_path === hostPath && m.container_path === containerPath)) {
103+
return false;
104+
}
105+
106+
const roLine = readOnly ? "\n read_only: true" : "";
107+
const newEntry = ` - host_path: ${hostPath}\n container_path: ${containerPath}${roLine}`;
108+
109+
const updated = insertMountEntry(content, newEntry);
110+
fs.writeFileSync(POLICY_FILE, updated, { encoding: "utf-8" });
111+
return true;
112+
}
113+
114+
/**
115+
* Insert a new mount entry into raw policy YAML content.
116+
* Handles: empty mounts: [], existing list, and missing section.
117+
*/
118+
function insertMountEntry(content, newEntry) {
119+
const lines = content.split("\n");
120+
let mountsIdx = -1;
121+
let sectionEndIdx = -1;
122+
123+
for (let i = 0; i < lines.length; i++) {
124+
if (/^mounts\s*:/.test(lines[i])) {
125+
mountsIdx = i;
126+
for (let j = i + 1; j < lines.length; j++) {
127+
const l = lines[j];
128+
if (l !== "" && /^\S/.test(l) && !l.startsWith("#")) {
129+
sectionEndIdx = j;
130+
break;
131+
}
132+
}
133+
break;
134+
}
135+
}
136+
137+
if (mountsIdx === -1) {
138+
// No mounts section — append at end
139+
return content.trimEnd() + "\n\nmounts:\n" + newEntry + "\n";
140+
}
141+
142+
const entryLines = newEntry.split("\n");
143+
144+
// Replace inline empty: mounts: []
145+
if (/^mounts\s*:\s*\[\s*\]/.test(lines[mountsIdx])) {
146+
lines[mountsIdx] = "mounts:";
147+
lines.splice(mountsIdx + 1, 0, ...entryLines);
148+
return lines.join("\n");
149+
}
150+
151+
// Insert before next top-level key, or at end of file
152+
const insertAt = sectionEndIdx === -1 ? lines.length : sectionEndIdx;
153+
lines.splice(insertAt, 0, ...entryLines);
154+
return lines.join("\n");
155+
}
156+
157+
/**
158+
* Load the mounts declared in the shared policy YAML.
159+
* Returns [] if the policy file is missing or the section is empty.
160+
*/
161+
function loadMountsFromPolicy() {
162+
if (!fs.existsSync(POLICY_FILE)) return [];
163+
return parseMountsFromYaml(fs.readFileSync(POLICY_FILE, "utf-8"));
164+
}
165+
166+
module.exports = {
167+
POLICY_FILE,
168+
validateMountPath,
169+
parseMountsFromYaml,
170+
insertMountEntry,
171+
loadMountsFromPolicy,
172+
addMountToPolicy,
173+
};

‎bin/nemoclaw.js‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ const _RD = _useColor ? "\x1b[1;31m" : "";
2121
const YW = _useColor ? "\x1b[1;33m" : "";
2222

2323
const { ROOT, SCRIPTS, run, runCapture: _runCapture, runInteractive, shellQuote, validateName } = require("./lib/runner");
24+
const mounts = require("./lib/mounts");
2425
const { resolveOpenshell } = require("./lib/resolve-openshell");
2526
const { startGatewayForRecovery } = require("./lib/onboard");
2627
const {
@@ -689,6 +690,62 @@ function sandboxPolicyList(sandboxName) {
689690
console.log("");
690691
}
691692

693+
function sandboxMountList(sandboxName) {
694+
const list = mounts.loadMountsFromPolicy();
695+
696+
console.log("");
697+
console.log(` Mounts for sandbox '${sandboxName}':`);
698+
if (list.length === 0) {
699+
console.log(" (none configured)");
700+
console.log("");
701+
console.log(` To add a mount: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`);
702+
} else {
703+
for (const m of list) {
704+
const ro = m.read_only ? " [read-only]" : "";
705+
console.log(` ${m.host_path} → ${m.container_path}${ro}`);
706+
}
707+
console.log("");
708+
console.log(" Note: mounts take effect on the next sandbox creation.");
709+
console.log(` To add more: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`);
710+
}
711+
console.log("");
712+
}
713+
714+
function sandboxMountAdd(sandboxName, args) {
715+
const hostPath = args[0];
716+
const containerPath = args[1];
717+
const readOnly = args.includes("--read-only");
718+
719+
if (!hostPath || !containerPath) {
720+
console.error(" Usage: nemoclaw <name> mount-add <host-path> <container-path> [--read-only]");
721+
console.error("");
722+
console.error(" Examples:");
723+
console.error(" nemoclaw openclaw mount-add /home/user/datasets /data/datasets --read-only");
724+
console.error(" nemoclaw openclaw mount-add /home/user/projects /workspace/projects");
725+
process.exit(1);
726+
}
727+
728+
try {
729+
mounts.validateMountPath(hostPath, "host-path");
730+
mounts.validateMountPath(containerPath, "container-path");
731+
} catch (err) {
732+
console.error(` ${err.message}`);
733+
process.exit(1);
734+
}
735+
736+
const added = mounts.addMountToPolicy(hostPath, containerPath, readOnly);
737+
if (!added) {
738+
console.log(` Mount already configured: ${hostPath} → ${containerPath}`);
739+
return;
740+
}
741+
742+
const roNote = readOnly ? " (read-only)" : "";
743+
console.log(` ${G}✓${R} Added mount${roNote}: ${hostPath} → ${containerPath}`);
744+
console.log(" This mount will take effect on the next sandbox creation.");
745+
console.log(` Note: --volume support is pending (NVIDIA/OpenShell#500). The mount is`);
746+
console.log(` recorded in the policy now so it takes effect automatically once supported.`);
747+
}
748+
692749
async function sandboxDestroy(sandboxName, args = []) {
693750
const skipConfirm = args.includes("--yes") || args.includes("--force");
694751
if (!skipConfirm) {
@@ -737,6 +794,10 @@ function help() {
737794
nemoclaw <name> policy-add Add a network or filesystem policy preset
738795
nemoclaw <name> policy-list List presets ${D}(● = applied)${R}
739796
797+
${G}Host Mounts:${R}
798+
nemoclaw <name> mount-list List host→sandbox bind mounts
799+
nemoclaw <name> mount-add Add a bind mount ${D}(--read-only optional)${R}
800+
740801
${G}Deploy:${R}
741802
nemoclaw deploy <instance> Deploy to a Brev VM and start services
742803
@@ -812,10 +873,12 @@ const [cmd, ...args] = process.argv.slice(2);
812873
case "logs": sandboxLogs(cmd, actionArgs.includes("--follow")); break;
813874
case "policy-add": await sandboxPolicyAdd(cmd); break;
814875
case "policy-list": sandboxPolicyList(cmd); break;
876+
case "mount-list": sandboxMountList(cmd); break;
877+
case "mount-add": await sandboxMountAdd(cmd, actionArgs); break;
815878
case "destroy": await sandboxDestroy(cmd, actionArgs); break;
816879
default:
817880
console.error(` Unknown action: ${action}`);
818-
console.error(` Valid actions: connect, status, logs, policy-add, policy-list, destroy`);
881+
console.error(` Valid actions: connect, status, logs, policy-add, policy-list, mount-list, mount-add, destroy`);
819882
process.exit(1);
820883
}
821884
return;

‎nemoclaw-blueprint/policies/openclaw-sandbox.yaml‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,22 @@ filesystem_policy:
3636
- /dev/null
3737
- /sandbox/.openclaw-data # Writable agent/plugin state (symlinked from .openclaw)
3838

39+
# Host filesystem mounts — bind-mounted into the sandbox at creation time.
40+
# Each entry is translated into a Docker --volume flag (host_path:container_path[:ro]).
41+
# Mount paths must be absolute. Container paths must also appear in
42+
# filesystem_policy.read_write (or read_only) for Landlock to permit access.
43+
# Static mounts are applied once at sandbox creation and cannot be hot-added.
44+
#
45+
# Example:
46+
# mounts:
47+
# - host_path: /home/user/datasets
48+
# container_path: /data/datasets
49+
# read_only: true
50+
# - host_path: /home/user/projects
51+
# container_path: /workspace/projects
52+
53+
mounts: []
54+
3955
landlock:
4056
compatibility: best_effort
4157

@@ -53,15 +69,18 @@ network_policies:
5369
enforcement: enforce
5470
tls: terminate
5571
rules:
56-
- allow: { method: "*", path: "/**" }
72+
- allow: { method: GET, path: "/**" }
73+
- allow: { method: POST, path: "/**" }
5774
- host: statsig.anthropic.com
5875
port: 443
5976
rules:
60-
- allow: { method: "*", path: "/**" }
77+
- allow: { method: GET, path: "/**" }
78+
- allow: { method: POST, path: "/**" }
6179
- host: sentry.io
6280
port: 443
6381
rules:
64-
- allow: { method: "*", path: "/**" }
82+
- allow: { method: GET, path: "/**" }
83+
- allow: { method: POST, path: "/**" }
6584
binaries:
6685
- { path: /usr/local/bin/claude }
6786

@@ -74,14 +93,16 @@ network_policies:
7493
enforcement: enforce
7594
tls: terminate
7695
rules:
77-
- allow: { method: "*", path: "/**" }
96+
- allow: { method: GET, path: "/**" }
97+
- allow: { method: POST, path: "/**" }
7898
- host: inference-api.nvidia.com
7999
port: 443
80100
protocol: rest
81101
enforcement: enforce
82102
tls: terminate
83103
rules:
84-
- allow: { method: "*", path: "/**" }
104+
- allow: { method: GET, path: "/**" }
105+
- allow: { method: POST, path: "/**" }
85106
binaries:
86107
- { path: /usr/local/bin/claude }
87108
- { path: /usr/local/bin/openclaw }

0 commit comments

Comments
 (0)