@kortix/agent-tunnel 0.15.1 → 0.15.3

package/README.md

@@ -233,11 +233,24 @@ The local config is the maximum boundary. The server cannot widen configured
 filesystem paths, blocked paths, shell commands, timeouts, file sizes, or desktop
 features.
 
-A `shell` grant is local code execution. The allow list matches the executable
-name exactly and the block list also matches every path ending in that name
-(`/bin/rm` is `rm`). Arguments are not restricted: an allowed `git`, `find`, or
-`python` can run any code through its own flags. Grant `shell` only to a session
-you trust with this computer.
+A `shell` grant with no command list is local code execution. Grant it only to
+a session you trust with this computer.
+
+A command list (`allowedCommands` in the local config, `commands` in a
+permission scope) holds whole command lines, and both lists must match:
+
+- `git status` allows `git` with the one argument `status`, and nothing else.
+- A trailing ` *` allows any further arguments: `npm run *` allows
+  `npm run build` but not `npm exec`.
+- `git *`, `node *`, `python3 *`, `sh *`, `find *` and similar entries allow
+  any code: these programs run commands through their own flags
+  (`git -c alias.x=!cmd x`, `node -e`, `find -exec`).
+- A bare `git` allows only `git` with no arguments. Agent Tunnel 0.1.2 and
+  earlier let it take any arguments; write `git *` for that.
+
+Arguments compare one at a time, and no shell parses the command. The block
+list matches executable names, and every path ending in that name (`/bin/rm`
+is `rm`).
 
 ## Computer Use driver
 

package/dist/agent-cli.js

@@ -3209,6 +3209,21 @@ function validateDesktopScope(scope) {
   }
   return { valid: true, sanitized };
 }
+function shellCommandAllowed(entries, command, args) {
+  const argv = [command.trim(), ...args];
+  return entries.some((entry) => {
+    const anyArgs = entry.endsWith(" *");
+    const fixed = (anyArgs ? entry.slice(0, -2) : entry).trim();
+    if (!fixed)
+      return false;
+    if (fixed === argv[0] && (anyArgs || args.length === 0))
+      return true;
+    const tokens = fixed.split(/\s+/);
+    if (anyArgs ? argv.length < tokens.length : argv.length !== tokens.length)
+      return false;
+    return tokens.every((token, index) => token === argv[index]);
+  });
+}
 function operationForMethod(method) {
   if (method === "fs.stat")
     return "read";
@@ -5532,7 +5547,7 @@ import { spawn as spawn5 } from "child_process";
 
 // src/agent/security/command-validator.ts
 var SHELL_METACHAR_REGEX = /[;&|`$(){}[\]<>!#~]/;
-function validateCommand(command, allowedCommands, blockedCommands) {
+function validateCommand(command, args, allowedCommands, blockedCommands) {
   if (!command || typeof command !== "string") {
     throw new Error("Command is required");
   }
@@ -5546,7 +5561,7 @@ function validateCommand(command, allowedCommands, blockedCommands) {
     throw new Error(`Command "${executable}" is blocked`);
   }
   if (allowedCommands.length > 0) {
-    if (!allowedCommands.includes(executable)) {
+    if (!shellCommandAllowed(allowedCommands, executable, args)) {
       throw new Error(`Command "${executable}" is not in the allowed commands list`);
     }
   }
@@ -5577,9 +5592,9 @@ function createShellCapability(config) {
     }
     const timeout = Math.min(requestedTimeout, config.shellMaxTimeout, typeof scope.maxTimeout === "number" ? scope.maxTimeout : config.shellMaxTimeout);
     const scopedCommands = Array.isArray(scope.commands) ? scope.commands.filter((value) => typeof value === "string") : [];
-    const executable = validateCommand(command, config.allowedCommands, config.blockedCommands);
+    const executable = validateCommand(command, args, config.allowedCommands, config.blockedCommands);
     if (scopedCommands.length > 0) {
-      validateCommand(executable, scopedCommands, []);
+      validateCommand(executable, args, scopedCommands, []);
     }
     if (cwd) {
       validatePath(cwd, config.allowedPaths, config.blockedPaths);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kortix-ai/CompanyOS.git",

package/src/agent/capabilities/security.test.ts

@@ -145,12 +145,40 @@ describe('local capability permission enforcement', () => {
         __permission: {
           permissionId: 'permission-1',
           capability: 'shell',
-          scope: { commands: ['node'], workingDir: root },
+          scope: { commands: ['node --version'], workingDir: root },
         },
       }),
     ).rejects.toThrow('outside allowed directories');
   });
 
+  test('an allowed executable cannot take unapproved interpreter arguments', async () => {
+    const marker = join(root, 'pwned');
+    const payload = `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'x')`;
+    const permission = (commands: string[]) => ({
+      permissionId: 'permission-1',
+      capability: 'shell',
+      scope: { commands },
+    });
+    const scoped = createShellCapability(config()).methods.get('shell.exec')!;
+    await expect(
+      scoped({ command: 'node', args: ['-e', payload], __permission: permission(['node']) }),
+    ).rejects.toThrow('not in the allowed commands list');
+    const local = createShellCapability({ ...config(), allowedCommands: ['node --version'] })
+      .methods.get('shell.exec')!;
+    await expect(
+      local({ command: 'node', args: ['-e', payload], __permission: permission(['node *']) }),
+    ).rejects.toThrow('not in the allowed commands list');
+    await expect(readFile(marker, 'utf8')).rejects.toThrow();
+
+    const result = (await local({
+      command: 'node',
+      args: ['--version'],
+      __permission: permission(['node *']),
+    })) as { exitCode: number; stdout: string };
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toStartWith('v');
+  });
+
   test('disjoint local and permission command allowlists fail closed', async () => {
     const handler = createShellCapability({ ...config(), allowedCommands: ['node'] }).methods.get(
       'shell.exec',

package/src/agent/capabilities/shell.ts

@@ -3,7 +3,8 @@
  *
  * Security:
  *   - Commands are executed as array args (no shell interpolation)
- *   - First arg (executable) is validated against allowedCommands / blockedCommands
+ *   - The whole command line (executable + args) is matched against allowedCommands
+ *     and the permission's scope.commands; the executable against blockedCommands
  *   - Working directory is validated against allowedPaths / blockedPaths
  *   - Timeout enforcement
  */
@@ -54,9 +55,9 @@ export function createShellCapability(config: TunnelConfig): Capability {
     const scopedCommands = Array.isArray(scope.commands)
       ? scope.commands.filter((value): value is string => typeof value === 'string')
       : [];
-    const executable = validateCommand(command, config.allowedCommands, config.blockedCommands);
+    const executable = validateCommand(command, args, config.allowedCommands, config.blockedCommands);
     if (scopedCommands.length > 0) {
-      validateCommand(executable, scopedCommands, []);
+      validateCommand(executable, args, scopedCommands, []);
     }
 
     if (cwd) {

package/src/agent/security/command-validator.test.ts

@@ -4,14 +4,14 @@ import { validateCommand } from './command-validator';
 describe('validateCommand blocked commands', () => {
   test('a blocked name blocks its absolute and relative path spellings', () => {
     for (const spelling of ['rm', '/bin/rm', '/usr/bin/rm', './rm']) {
-      expect(() => validateCommand(spelling, [], ['rm'])).toThrow(/is blocked/);
+      expect(() => validateCommand(spelling, [], [], ['rm'])).toThrow(/is blocked/);
     }
   });
   test('an unrelated command with the blocked name inside a directory still runs', () => {
-    expect(validateCommand('/opt/rm-tools/ls', [], ['rm'])).toBe('/opt/rm-tools/ls');
+    expect(validateCommand('/opt/rm-tools/ls', [], [], ['rm'])).toBe('/opt/rm-tools/ls');
   });
   test('an allowlist stays an exact match', () => {
-    expect(() => validateCommand('/usr/bin/git', ['git'], [])).toThrow(/not in the allowed/);
-    expect(validateCommand('git', ['git'], [])).toBe('git');
+    expect(() => validateCommand('/usr/bin/git', [], ['git'], [])).toThrow(/not in the allowed/);
+    expect(validateCommand('git', [], ['git'], [])).toBe('git');
   });
 });

package/src/agent/security/command-validator.ts

@@ -1,9 +1,17 @@
+import { shellCommandAllowed } from '../../shared/permissions';
+
 const SHELL_METACHAR_REGEX = /[;&|`$(){}[\]<>!#~]/;
 
+/**
+ * `allowedCommands` entries are whole command lines (see `shellCommandAllowed`):
+ * `git status` allows only that, `git *` allows any git arguments.
+ * `blockedCommands` entries are executable names.
+ */
 export function validateCommand(
   command: string,
-  allowedCommands: string[],
-  blockedCommands: string[],
+  args: readonly string[],
+  allowedCommands: readonly string[],
+  blockedCommands: readonly string[],
 ): string {
   if (!command || typeof command !== 'string') {
     throw new Error('Command is required');
@@ -18,15 +26,13 @@ export function validateCommand(
   const executable = trimmed;
 
   // A blocked name also blocks every path that ends in it: `/bin/rm` is `rm`.
-  // Arguments stay unrestricted: an allowed `git` or `python` runs code through
-  // its own flags, so a `shell` grant is local code execution, not a sandbox.
   const name = executable.slice(executable.lastIndexOf('/') + 1);
   if (blockedCommands.length > 0 && (blockedCommands.includes(executable) || blockedCommands.includes(name))) {
     throw new Error(`Command "${executable}" is blocked`);
   }
 
   if (allowedCommands.length > 0) {
-    if (!allowedCommands.includes(executable)) {
+    if (!shellCommandAllowed(allowedCommands, executable, args)) {
       throw new Error(`Command "${executable}" is not in the allowed commands list`);
     }
   }

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   normalizeDesktopCall,
   isTunnelCapability,
   operationForMethod,
+  shellCommandAllowed,
   validateTunnelPermissionScope,
   validateFilesystemParams,
 } from './shared';

package/src/shared/index.ts

@@ -38,6 +38,7 @@ export {
   normalizeDesktopCall,
   isTunnelCapability,
   operationForMethod,
+  shellCommandAllowed,
   validateTunnelPermissionScope,
 } from './permissions';
 export type { PermissionScopeValidationResult } from './permissions';

package/src/shared/permissions.ts

@@ -253,6 +253,34 @@ function validateDesktopScope(scope: Record<string, unknown>): PermissionScopeVa
   return { valid: true, sanitized };
 }
 
+/**
+ * A shell allow-list entry is the whole command line the person approved, not
+ * an executable name. `git status` allows exactly `git` with the one argument
+ * `status`. A trailing ` *` allows any further arguments: `git *` is every git
+ * invocation, and `git *`, `node *`, `python3 *` or `sh *` run any code through
+ * their own flags (`git -c alias.x=!cmd x`, `node -e`, `sh -c`).
+ * Arguments compare one token at a time, so an argument never matches a
+ * pattern token by containing whitespace. An entry with no ` *` whose whole
+ * text is the executable (a path with spaces) allows that executable with no
+ * arguments.
+ */
+export function shellCommandAllowed(
+  entries: readonly string[],
+  command: string,
+  args: readonly string[],
+): boolean {
+  const argv = [command.trim(), ...args];
+  return entries.some((entry) => {
+    const anyArgs = entry.endsWith(' *');
+    const fixed = (anyArgs ? entry.slice(0, -2) : entry).trim();
+    if (!fixed) return false;
+    if (fixed === argv[0] && (anyArgs || args.length === 0)) return true;
+    const tokens = fixed.split(/\s+/);
+    if (anyArgs ? argv.length < tokens.length : argv.length !== tokens.length) return false;
+    return tokens.every((token, index) => token === argv[index]);
+  });
+}
+
 export function operationForMethod(method: string): string {
   if (method === 'fs.stat') return 'read';
   const separator = method.indexOf('.');