skilldrop-cli 0.16.27 → 0.16.28

package/bin/governance.js

@@ -16,7 +16,7 @@ const { execFileSync } = require("child_process");
 const SEVERITY = { "🟥": 3, "🟧": 2, "🟨": 1 };          // scan findings; ⚪ (fixtures) never count
 const MAX = { none: 0, low: 1, medium: 2, high: 3 };      // policy scan.max: the worst finding allowed
 const KEYS = {
-  "": ["version", "catalogues", "skills", "scan", "audit", "note"],
+  "": ["version", "catalogues", "skills", "scan", "audit", "require_containment", "note"],
   catalogues: ["allow", "require_pinned"],
   skills: ["allow", "block"],
   scan: ["max"],
@@ -60,6 +60,8 @@ function load(flags) {
   list(p.skills && p.skills.block, "skills.block");
   if (p.catalogues && p.catalogues.require_pinned !== undefined && typeof p.catalogues.require_pinned !== "boolean")
     problems.push("catalogues.require_pinned must be true or false");
+  if (p.require_containment !== undefined && typeof p.require_containment !== "boolean")
+    problems.push("require_containment must be true or false");
   if (p.scan && p.scan.max !== undefined && !(p.scan.max in MAX)) problems.push(`scan.max must be one of ${Object.keys(MAX).join(", ")}`);
   if (p.audit) {
     const a = p.audit.actor;
@@ -209,4 +211,63 @@ function verifyMirror(dir) {
   return { source: m.source, created: m.created, files: Object.keys(want).length, missing, changed, extra };
 }
 
-module.exports = { load, check, prepare, audit, verifyAudit, verifyMirror, sourceKey, tilde, SEVERITY };
+/* ---------- containment (RFC-0051, OWASP AST06) ----------
+   Claude Code's sandbox confines the shell commands a session runs, and every process they
+   start: writes to the working directory and temp, network only to allowed hosts. It applies
+   to a whole project session, not to one skill, so containing a skill means turning the strict
+   sandbox on for the project it is installed into, sized to what its manifest declares
+   (permissions.network, permissions.files). It only ever adds restrictions: it never removes
+   a setting, never sets one to something looser, and never widens a sandbox that is already
+   on. Facts from code.claude.com/docs/en/sandboxing and /permissions, checked 2026-10-19. */
+function readSettings(f) {
+  if (!f || !fs.existsSync(f)) return {};
+  try { return JSON.parse(fs.readFileSync(f, "utf8")); }
+  catch (e) { die(`${tilde(f)} is not valid JSON — fix it before containment changes it; nothing was installed`); }
+}
+const strictIn = (d) => !!(d && d.sandbox && d.sandbox.enabled === true && d.sandbox.allowUnsandboxedCommands === false);
+
+/* units: [{name, perms}]; files: {local, project, user}; opts: {require}.
+   Returns what --contain would change, without writing anything. */
+function containmentPlan(units, files, opts = {}) {
+  const uncontainable = units.filter((u) => u.perms && u.perms.files === "anywhere").map((u) => u.name);
+  const hosts = [...new Set(units.flatMap((u) => (u.perms && u.perms.network) || []))].sort();
+  const local = readSettings(files.local);
+  const others = [files.project, files.user].filter((f) => f && f !== files.local).map(readSettings);
+  const before = JSON.stringify(local);
+  const next = JSON.parse(before);
+  const sb = (next.sandbox = next.sandbox && typeof next.sandbox === "object" ? next.sandbox : {});
+  const alreadyOn = sb.enabled === true || others.some((d) => d.sandbox && d.sandbox.enabled === true);
+  const changes = [], notes = [];
+  if (sb.enabled !== true) { sb.enabled = true; changes.push("sandbox.enabled: true — shell commands and what they start run in the OS sandbox"); }
+  if (sb.allowUnsandboxedCommands !== false) {
+    sb.allowUnsandboxedCommands = false;
+    changes.push("sandbox.allowUnsandboxedCommands: false — a command that fails in the sandbox can't retry outside it");
+  }
+  if (opts.require && sb.failIfUnavailable !== true) {
+    sb.failIfUnavailable = true;
+    changes.push("sandbox.failIfUnavailable: true — Claude Code won't start here if the sandbox can't (the policy requires containment)");
+  }
+  if (hosts.length && alreadyOn)
+    notes.push(`these skills declare network hosts (${hosts.join(", ")}). The sandbox was already on, so they were not added: ` +
+               "adding hosts would widen it. Add them to sandbox.network.allowedDomains yourself if the skills should reach them.");
+  else if (hosts.length) {
+    sb.network = sb.network && typeof sb.network === "object" ? sb.network : {};
+    const have = new Set(sb.network.allowedDomains || []);
+    const add = hosts.filter((h) => !have.has(h));
+    if (add.length) {
+      sb.network.allowedDomains = [...(sb.network.allowedDomains || []), ...add];
+      changes.push(`sandbox.network.allowedDomains: ${add.join(", ")} — the hosts these skills declare; shell commands reach no other host without asking`);
+    }
+  } else if (!alreadyOn) notes.push("these skills declare no network hosts, so shell commands reach none without asking");
+  if ((sb.excludedCommands || []).length)
+    notes.push(`this file's sandbox.excludedCommands (${sb.excludedCommands.join(", ")}) still run outside the sandbox`);
+  notes.push('the sandbox covers shell commands only: Claude Code\'s file tools, web tools, MCP servers and hooks follow permission rules instead. ' +
+             'To keep these skills off the web entirely, add "permissions": {"deny": ["WebFetch", "WebSearch"]} to this file.');
+  return { uncontainable, hosts, changes, notes, next, changed: JSON.stringify(next) !== before };
+}
+
+/* Is a project already contained (strict sandbox on in its own settings)? For inventory and
+   for a policy that requires containment. */
+function contained(files) { return strictIn(readSettings(files.local)) || strictIn(readSettings(files.project)); }
+
+module.exports = { containmentPlan, contained, load, check, prepare, audit, verifyAudit, verifyMirror, sourceKey, tilde, SEVERITY };

package/bin/skilldrop.js

@@ -105,6 +105,9 @@ Install/update/uninstall targets (pick one):
                      repo you don't own without touching its tracked files or .gitignore
 
 Organisation policy (RFC-0050):
+  --contain          Claude Code project installs: turn on the strict sandbox for this project in
+                     .claude/settings.local.json, allowing only the network hosts the skills declare.
+                     Only adds restrictions; refuses a skill that declares writing anywhere (RFC-0051)
   --policy <file>    the policy to enforce; also SKILLDROP_POLICY, else ~/.config/skilldrop/policy.json.
                      It can allow only some catalogues (and require them pinned), allow or block skills,
                      cap the supply-chain scan's findings, and turn on an audit log. A policy that is
@@ -459,6 +462,62 @@ function enforcePolicy(flags, cat, names, kind) {
   return policy;
 }
 
+/* RFC-0051: --contain turns on Claude Code's strict sandbox for the project a skill is installed
+   into, sized to what the skills declare. Planned (and refused) before anything is copied;
+   applied after. Only ever adds restrictions; see gov.containmentPlan. */
+function containmentFor(flags, cat, names, dest, ide, policy) {
+  const require = !!(policy && policy.require_containment);
+  if (!flags.contain && !require) return null;
+  if (ide !== "claude") {
+    if (require) die(`the policy requires containment, which skilldrop sets up for Claude Code project installs; ` +
+                     `${ide === "generic" ? "--dest" : "--ide " + ide} has no sandbox it can configure — nothing was installed`);
+    const want = names.map((s) => { const pm = manifestOf(cat, s).permissions; return pm ? `${s}: network ${(pm.network || []).join(", ") || "none"}, writes ${pm.files}` : `${s}: no scripts`; });
+    console.log(`note: ${ide === "generic" ? "this target" : ide} has no sandbox skilldrop can configure. What the skills expect:\n  ${want.join("\n  ")}`);
+    return null;
+  }
+  const userDir = path.join(os.homedir(), ".claude", "skills");
+  if (path.resolve(dest) === userDir)
+    die("containment applies to one project: install with --project --contain (or --local --contain). A user-scope " +
+        "install reaches every project, and skilldrop won't change your user settings — nothing was installed");
+  const base = path.dirname(dest);
+  const files = { local: path.join(base, "settings.local.json"), project: path.join(base, "settings.json"),
+                  user: path.join(os.homedir(), ".claude", "settings.json") };
+  if (!flags.contain) {
+    if (gov.contained(files)) return null;
+    die("the policy requires containment: re-run with --contain, which turns on Claude Code's strict sandbox for this " +
+        "project — nothing was installed");
+  }
+  const plan = gov.containmentPlan(names.map((s) => ({ name: s, perms: manifestOf(cat, s).permissions })), files, { require });
+  if (plan.uncontainable.length)
+    die(`${plan.uncontainable.join(", ")} declare${plan.uncontainable.length === 1 ? "s" : ""} writing anywhere on disk ` +
+        "(permissions.files), so it can't run inside the sandbox. Install without --contain, or leave it out — nothing was installed");
+  return Object.assign(plan, { files });
+}
+
+function applyContainment(plan, dry) {
+  const f = plan.files.local;
+  const where = path.relative(process.cwd(), f) || f;
+  console.log(`\n${dry ? "would contain" : "Contained"} (RFC-0051): ${where}`);
+  if (!plan.changed) console.log("  already contained: nothing to change");
+  for (const c of plan.changes) console.log(`  ${dry ? "would set" : "set"} ${c}`);
+  for (const n of plan.notes) console.log(`  note: ${n}`);
+  if (dry) return;
+  if (plan.changed) {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(plan.next, null, 2) + "\n");
+  }
+  // settings.local.json is personal: keep it out of git if nothing ignores it already
+  const root = gitRoot(process.cwd());
+  if (root && path.resolve(f).startsWith(path.resolve(root) + path.sep)) {
+    let ignored = false;
+    try { execFileSync("git", ["check-ignore", "-q", f], { cwd: root, stdio: "ignore" }); ignored = true; } catch (e) { /* not ignored */ }
+    if (!ignored) {
+      writeExclude(root, readExclude(root).entries.concat(excludeEntry(root, f, false)));
+      console.log(`  listed it in ${path.relative(process.cwd(), excludePath(root)) || excludePath(root)} so git won't see it`);
+    }
+  }
+}
+
 const auditUnit = (cat, name, kind, version, dest) =>
   ({ kind, name, version: version || null, source: cat.source, commit: cat.commit || null, pinned: !!cat.pinned, target: dest });
 
@@ -1265,7 +1324,8 @@ function install(args) {
   gate(cat, names);
   const policy = enforcePolicy(args.flags, cat, names, "skill");
   const { dest, ide } = target(args.flags);
-  if (args.flags["dry-run"]) return planInstall(cat, names, dest, ide, args.flags);
+  const contain = containmentFor(args.flags, cat, names, dest, ide, policy);
+  if (args.flags["dry-run"]) { planInstall(cat, names, dest, ide, args.flags); if (contain) applyContainment(contain, true); return; }
   fs.mkdirSync(dest, { recursive: true });
   const l = ledger(dest);
   const pipDeps = [], suggestions = new Set(), notes = [];
@@ -1276,7 +1336,8 @@ function install(args) {
     console.log(`installed ${s}@${m.version} -> ${dest}`);
   }
   saveLedger(l);
-  gov.audit(policy, "install", names.map((s) => auditUnit(cat, s, "skill", lver(l.data[s]), dest)));
+  if (contain) applyContainment(contain, false);
+  gov.audit(policy, "install", names.map((s) => Object.assign(auditUnit(cat, s, "skill", lver(l.data[s]), dest), contain ? { contained: true } : {})));
   console.log(`\n${names.length} skill(s) installed (${ide}).`);
   if (notes.length) console.log(`\nCleanup:\n${notes.join("\n")}`);
   const local = !!args.flags.local;
@@ -2253,6 +2314,8 @@ function inventory(args) {
       installs.push({ target: gov.tilde(t.dest), scope: t.scope, ide: t.ide, kind, name, version: lver(e) || null,
                       source: gov.tilde(src), commit: (e && e.commit) || null, pinned,
                       edited: kind === "agent" ? 0 : editedFiles(t.dest, name, e).length,
+                      contained: t.ide === "claude" && t.scope === "project" && kind !== "agent"
+                        ? gov.contained({ local: path.join(path.dirname(t.dest), "settings.local.json"), project: path.join(path.dirname(t.dest), "settings.json") }) : null,
                       policy: policy ? (refused.length ? refused.map((x) => x.why) : "ok") : null });
     }
   }

package/contracts/policy.schema.json

@@ -5,31 +5,67 @@
   "$comment": "RFC-0050. The file an organisation hands out (--policy, SKILLDROP_POLICY, or ~/.config/skilldrop/policy.json). Closed at every level: an unknown key stops the command, because a misspelt rule that is silently ignored is a rule that isn't there. bin/governance.js enforces the same shape; contracts/policy.example.json must satisfy both.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version"],
+  "required": [
+    "version"
+  ],
   "properties": {
-    "version": { "const": 1 },
-    "note": { "type": "string", "description": "Free text: who owns this policy and where to ask about it." },
+    "version": {
+      "const": 1
+    },
+    "note": {
+      "type": "string",
+      "description": "Free text: who owns this policy and where to ask about it."
+    },
     "catalogues": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "allow": { "type": "array", "items": { "type": "string" }, "description": "Catalogue sources allowed: \"bundled\", a git URL (a trailing * matches a prefix, e.g. https://git.example.org/skills/*), or a path. Absent: any." },
-        "require_pinned": { "type": "boolean", "description": "Every catalogue other than the bundled one must be pinned to a commit (--from <url>#<commit>)." }
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Catalogue sources allowed: \"bundled\", a git URL (a trailing * matches a prefix, e.g. https://git.example.org/skills/*), or a path. Absent: any."
+        },
+        "require_pinned": {
+          "type": "boolean",
+          "description": "Every catalogue other than the bundled one must be pinned to a commit (--from <url>#<commit>)."
+        }
       }
     },
     "skills": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "allow": { "type": "array", "items": { "type": "string" }, "description": "Skill, loop and agent names allowed; * matches anything. Absent: any." },
-        "block": { "type": "array", "items": { "type": "string" }, "description": "Names refused even when allowed." }
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Skill, loop and agent names allowed; * matches anything. Absent: any."
+        },
+        "block": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Names refused even when allowed."
+        }
       }
     },
     "scan": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "max": { "enum": ["none", "low", "medium", "high"], "description": "The worst supply-chain scan finding a skill may carry: none, low (🟨), medium (🟧), high (🟥). Findings in eval fixtures and example inputs never count." }
+        "max": {
+          "enum": [
+            "none",
+            "low",
+            "medium",
+            "high"
+          ],
+          "description": "The worst supply-chain scan finding a skill may carry: none, low (🟨), medium (🟧), high (🟥). Findings in eval fixtures and example inputs never count."
+        }
       }
     },
     "audit": {
@@ -37,10 +73,22 @@
       "additionalProperties": false,
       "description": "Present: install, update and uninstall append to a tamper-evident log.",
       "properties": {
-        "log": { "type": "string", "description": "Where the log goes. Default ~/.config/skilldrop/audit.jsonl. Refused inside a git working tree." },
-        "actor": { "description": "Who each entry names: \"pseudonym\" (default; a keyed hash of user and machine, needs the salt), \"none\", \"os-user\", or {\"fixed\": \"<name>\"} such as a team or machine id." },
-        "salt_env": { "type": "string", "description": "The environment variable holding the organisation's secret salt for pseudonyms. Default SKILLDROP_AUDIT_SALT." }
+        "log": {
+          "type": "string",
+          "description": "Where the log goes. Default ~/.config/skilldrop/audit.jsonl. Refused inside a git working tree."
+        },
+        "actor": {
+          "description": "Who each entry names: \"pseudonym\" (default; a keyed hash of user and machine, needs the salt), \"none\", \"os-user\", or {\"fixed\": \"<name>\"} such as a team or machine id."
+        },
+        "salt_env": {
+          "type": "string",
+          "description": "The environment variable holding the organisation's secret salt for pseudonyms. Default SKILLDROP_AUDIT_SALT."
+        }
       }
+    },
+    "require_containment": {
+      "type": "boolean",
+      "description": "RFC-0051. true: an install must be contained (--contain, or a Claude Code project whose own settings already run the strict sandbox); targets that can't be are refused, and --contain also sets sandbox.failIfUnavailable."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.27",
+  "version": "0.16.28",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",