dsh-cmd-guard 0.0.0-stage → 0.1.0

package/lib/src/guard/entry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Layer 0: tool identity.
+ *
+ * This layer exists because of one concrete near-miss. The first draft assumed
+ * the command tool was called `run_command` and took `cmd`. The shipped tools
+ * are `bash` and `pwsh`, and they take `command`. A guard written against the
+ * assumed names installs cleanly, activates cleanly, and intercepts nothing -
+ * which is worse than failing to install, because it looks like it is working.
+ *
+ * So: anything that is not a known execution tool, but is passed a
+ * command-shaped string, is an ask. Not a deny - a new shell tool is a
+ * legitimate thing for the harness to grow. Just not something this parser
+ * has any evidence about.
+ */
+import type { Finding, GuardInput, GuardState } from './types.js';
+/**
+ * Tool names DSH dispatches commands through.
+ *
+ * Verified against the shipped type declarations of 0.2.x: the POSIX shell
+ * tool registers as `bash`, the Windows one as `pwsh`, and the persistent
+ * variant reuses `bash` (same registered name, so name matching covers it).
+ *
+ * The rest of the set is deliberate over-inclusion. A tool that runs a command
+ * and is named something obvious here should be treated as a command source,
+ * even if this build never registers it.
+ */
+export declare const EXEC_TOOLS: ReadonlySet<string>;
+/**
+ * Keys the command legitimately arrives under, per tool.
+ *
+ * `command` is the shipped key for the shell tools. Anything outside the set
+ * for that tool is drift and gets surfaced rather than trusted.
+ */
+export declare function primaryKeysFor(tool: string): ReadonlySet<string>;
+/** Keys every execution tool may carry without it being drift. */
+export declare const PRIMARY_COMMAND_KEYS: ReadonlySet<string>;
+/**
+ * Keys whose value is document or payload data, never a command line.
+ *
+ * Two independent reasons this lives here rather than only in the mount:
+ *
+ * 1. The unknown-tool scan reads every string argument. Without an exclusion,
+ *    `write_file` with a README that mentions `del /s /q` was surfaced as a
+ *    command, and so was writing this package's own test corpus. With no
+ *    approval UI composed, ask degrades to deny, which made `write_file`
+ *    effectively unusable.
+ * 2. `verify()` is exported and tests call it directly with a `commandSource`.
+ *    The exclusion has to hold at the layer, not only at the seam, or the same
+ *    false positive comes back through the library entry point.
+ *
+ * This is a name-based exclusion and therefore a residual risk: a tool that
+ * genuinely executes the string in `content` would be skipped. Stated in the
+ * README, not papered over.
+ */
+export declare const DATA_KEYS: ReadonlySet<string>;
+export declare function check(input: GuardInput, _state: GuardState): Finding | null;

package/lib/src/guard/entry.js

@@ -0,0 +1,133 @@
+import { looksLikeCommandString } from './shape.js';
+/**
+ * Tool names DSH dispatches commands through.
+ *
+ * Verified against the shipped type declarations of 0.2.x: the POSIX shell
+ * tool registers as `bash`, the Windows one as `pwsh`, and the persistent
+ * variant reuses `bash` (same registered name, so name matching covers it).
+ *
+ * The rest of the set is deliberate over-inclusion. A tool that runs a command
+ * and is named something obvious here should be treated as a command source,
+ * even if this build never registers it.
+ */
+export const EXEC_TOOLS = new Set([
+    'bash',
+    'sh',
+    'zsh',
+    'fish',
+    'pwsh',
+    'powershell',
+    'powershell.exe',
+    'pwsh.exe',
+    'cmd',
+    'cmd.exe',
+    'shell',
+    'terminal',
+    'run_command',
+    'exec',
+]);
+/**
+ * Tools that historically carried the command under `cmd`.
+ *
+ * Only these tolerate the short key. `bash` and `pwsh` are verified to take
+ * `command`; accepting `cmd` for them would mean a call that renames the key
+ * - the exact silent-rename failure this layer exists to catch - slides
+ * through as if nothing happened. Measured: `pwsh` handed `{cmd: "git status"}`
+ * passed, because `cmd` was globally tolerated.
+ */
+const LEGACY_CMD_TOOLS = new Set(['run_command', 'exec']);
+/**
+ * Keys the command legitimately arrives under, per tool.
+ *
+ * `command` is the shipped key for the shell tools. Anything outside the set
+ * for that tool is drift and gets surfaced rather than trusted.
+ */
+export function primaryKeysFor(tool) {
+    return LEGACY_CMD_TOOLS.has(tool.toLowerCase())
+        ? new Set(['command', 'cmd'])
+        : new Set(['command']);
+}
+/** Keys every execution tool may carry without it being drift. */
+export const PRIMARY_COMMAND_KEYS = new Set(['command', 'cmd']);
+/**
+ * Keys whose value is document or payload data, never a command line.
+ *
+ * Two independent reasons this lives here rather than only in the mount:
+ *
+ * 1. The unknown-tool scan reads every string argument. Without an exclusion,
+ *    `write_file` with a README that mentions `del /s /q` was surfaced as a
+ *    command, and so was writing this package's own test corpus. With no
+ *    approval UI composed, ask degrades to deny, which made `write_file`
+ *    effectively unusable.
+ * 2. `verify()` is exported and tests call it directly with a `commandSource`.
+ *    The exclusion has to hold at the layer, not only at the seam, or the same
+ *    false positive comes back through the library entry point.
+ *
+ * This is a name-based exclusion and therefore a residual risk: a tool that
+ * genuinely executes the string in `content` would be skipped. Stated in the
+ * README, not papered over.
+ */
+export const DATA_KEYS = new Set([
+    'content',
+    'contents',
+    'body',
+    'text',
+    'new_string',
+    'old_string',
+    'new_str',
+    'old_str',
+    'patch',
+    'diff',
+    'message',
+    'query',
+    'prompt',
+    'note',
+    'summary',
+    'explanation',
+    'description',
+    'why',
+    'reason',
+    'intent',
+    'purpose',
+]);
+function ask(code, reason) {
+    return { layer: 'entry', verdict: 'ask', code, reason };
+}
+export function check(input, _state) {
+    // The string came from a payload key, so it is a document, not a command
+    // line - whatever the tool name is. Checked before the tool-name branch on
+    // purpose: `write_file` must not be flagged for what its `content` says.
+    const source = input.commandSource;
+    if (source !== undefined && DATA_KEYS.has(source.toLowerCase()))
+        return null;
+    // Shape, not identity: how many command keys a call carries does not
+    // depend on whether a tool name is set. This sat after the tool guard, so a
+    // direct verify() call carrying both \`cmd\` and \`command\` was never checked.
+    // Two command keys in one call: the parser read one of them, and the
+    // tool may run the other. This is not drift, it is divergence, and no
+    // token analysis of a single string can resolve it. Checked before the
+    // tool-name branch because an unfamiliar tool returned early and the
+    // comparison never happened.
+    if (input.commandKeys !== undefined && input.commandKeys.length > 1) {
+        return ask('ENTRY_COMMAND_KEY_AMBIGUOUS', `The call carries more than one command key (${input.commandKeys.join(', ')}). The string below was read from "${source ?? 'an unnamed key'}", but which one runs is not something this parser can establish.`);
+    }
+    // Direct calls (tests, the exported verify()) carry no tool name. Layer 0
+    // has nothing to say about those, and inventing an opinion would make the
+    // pipeline unusable as a library.
+    if (input.tool === undefined)
+        return null;
+    const tool = input.tool.toLowerCase();
+    if (!EXEC_TOOLS.has(tool)) {
+        // Not every bare string argument is a command. `read_file` carries a path,
+        // and with no approval UI composed ask degrades to deny, so a shape-free
+        // scan made every file read impossible. Measured false positive; the shape
+        // heuristic now decides instead of the argument's existence.
+        if (!looksLikeCommandString(input.cmd))
+            return null;
+        return ask('ENTRY_UNKNOWN_EXEC_TOOL', `"${input.tool}" is not a shell tool this parser knows, yet it was handed a command-shaped argument. A new or renamed execution tool fails open, so it is surfaced instead.`);
+    }
+    if (source !== undefined && !primaryKeysFor(tool).has(source.toLowerCase())) {
+        return ask('ENTRY_COMMAND_KEY_DRIFT', `The command arrived under "${source}", which is not a key "${tool}" takes. Either the tool schema changed or a wrapper is reshaping arguments; both invalidate the assumption that the string below is the whole command.`);
+    }
+    return null;
+}

package/lib/src/guard/interp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Layer 5: interpreters.
+ *
+ * The plugin performs no IO and never opens the script. "The file exists" is
+ * therefore not an audit, and a rule based on existence would hand out a
+ * complete bypass: write a file, then run it. The only defensible line is
+ * where the path comes from.
+ *
+ * Two identity rules here are not cosmetic. Both were measured bypasses
+ * against the first draft:
+ *
+ *   - `INTERPRETERS.has(head)` compared the entire first token, so
+ *     `C:\Python39\python.exe`, `python3.11`, `node18` and `/usr/bin/python3`
+ *     all fell through as if they were ordinary programs.
+ *   - `INLINE_FLAGS` was an exact-match set, so bundled short flags (`-uc`,
+ *     `-pe`, `-ep`) read as an ordinary script call with no script.
+ */
+import type { Finding, GuardInput, GuardState } from './types.js';
+/**
+ * Resolve the interpreter behind a token: strip the path, the `.exe` suffix
+ * and a version suffix, then look for a known name.
+ *
+ * `C:\Python39\python.exe` -> python
+ * `python3.11`             -> python3
+ * `node18`                 -> node
+ * `py`                     -> py
+ */
+export declare function interpreterOf(token: string): string | undefined;
+/**
+ * Bundled short flags. `-uc` is `-u -c`, `-pe` is `-p -e`. Only `c` and `e`
+ * matter: they are the ones that carry a program body. `-Bu` carries none, so
+ * treating every bundle as inline would be a false positive on normal runs.
+ */
+export declare function isInlineFlag(token: string): boolean;
+export declare function check(input: GuardInput, state: GuardState): Finding | null;

package/lib/src/guard/interp.js

@@ -0,0 +1,199 @@
+import { baseName, hasParentEscape, isAbsolutePath, isInsideWorkspace, isVolatilePath, normalizePath, tokenize, } from './lexical.js';
+const INTERPRETERS = new Set([
+    'python',
+    'python3',
+    'py',
+    'node',
+    'nodejs',
+    'deno',
+    'bun',
+    'ruby',
+    'perl',
+    'php',
+    'lua',
+    'npx',
+    'pnpx',
+    'bunx',
+    'pip',
+    'pip3',
+    'pipx',
+]);
+/** Fetch-and-execute hosts: the payload does not exist on disk yet. */
+const FETCH_EXEC = new Set(['npx', 'pnpx', 'bunx']);
+/**
+ * Packages that are a local build toolchain rather than an arbitrary fetch.
+ *
+ * This is a measured false positive, not a convenience: `npx tsc -p
+ * tsconfig.json` is this project's own build, and asking for approval on every
+ * run teaches the operator to click through. The allowlist is deliberately
+ * short and excludes anything that downloads and runs a package's own scripts
+ * (there is no `npm` here, no `create-*`, no `vite create`).
+ */
+const LOCAL_TOOLCHAIN = new Set([
+    'tsc',
+    'tsc-alias',
+    'typescript',
+    'eslint',
+    'prettier',
+    'vitest',
+    'jest',
+    'tsup',
+    'esbuild',
+    'vite',
+    'rollup',
+    'rimraf',
+    'tsx',
+    'ts-node',
+]);
+const INLINE_FLAGS = new Set(['-c', '-e', '--eval', '-command', 'eval']);
+const STDIN_TARGETS = new Set(['-', 'con', '/dev/stdin', '/dev/fd/0']);
+const QUERY_FLAGS = new Set(['-v', '--version', '-h', '--help']);
+function ask(code, reason) {
+    return { layer: 'interp', verdict: 'ask', code, reason };
+}
+/**
+ * Resolve the interpreter behind a token: strip the path, the `.exe` suffix
+ * and a version suffix, then look for a known name.
+ *
+ * `C:\Python39\python.exe` -> python
+ * `python3.11`             -> python3
+ * `node18`                 -> node
+ * `py`                     -> py
+ */
+export function interpreterOf(token) {
+    const base = baseName(token).toLowerCase();
+    const noExt = base.endsWith('.exe') ? base.slice(0, -4) : base;
+    const candidates = [noExt];
+    // python3.11 -> python3 (keep the major, drop the patch series)
+    const noPatch = noExt.replace(/(\.\d+)+$/, '');
+    if (noPatch !== noExt)
+        candidates.push(noPatch);
+    // node18 -> node
+    const noDigits = noPatch.replace(/\d+$/, '');
+    if (noDigits !== noPatch)
+        candidates.push(noDigits);
+    for (const c of candidates) {
+        if (INTERPRETERS.has(c))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Bundled short flags. `-uc` is `-u -c`, `-pe` is `-p -e`. Only `c` and `e`
+ * matter: they are the ones that carry a program body. `-Bu` carries none, so
+ * treating every bundle as inline would be a false positive on normal runs.
+ */
+export function isInlineFlag(token) {
+    if (INLINE_FLAGS.has(token))
+        return true;
+    if (!/^-[a-z]{2,}$/i.test(token))
+        return false;
+    return /[ce]/i.test(token.slice(1));
+}
+/**
+ * A local toolchain invocation, as opposed to fetching and running a package.
+ *
+ * The first non-flag word is the package. npx's own options must come before
+ * that word, so a local package name in first position means every later flag
+ * belongs to the package, not to npx. That distinction is not cosmetic:
+ * `tsc -p tsconfig.json` uses `-p` for "project", while npx's `-p` means
+ * "package". Reading them as the same thing made this project's own build ask
+ * on every run.
+ */
+function isLocalToolchain(rest) {
+    let i = 0;
+    while (i < rest.length && rest[i]?.startsWith('-') === true)
+        i += 1;
+    const pkg = rest[i]?.toLowerCase();
+    if (pkg === undefined || !LOCAL_TOOLCHAIN.has(pkg))
+        return false;
+    // Options before the package name belong to npx itself; `-c` / `--call` run
+    // an arbitrary shell command and `-p` / `--package` swaps the package.
+    return !rest.slice(0, i).some((t) => {
+        const l = t.toLowerCase();
+        return l === '-c' || l === '--call' || l === '-p' || l === '--package';
+    });
+}
+/**
+ * Modules reachable through `-m` whose effect is not "run this file".
+ *
+ * The set is about capability, not about the module's name: installing a
+ * package runs its build backend, a `*.server` module publishes the working
+ * directory, and a debugger is an interactive shell by another route.
+ */
+const RISKY_MODULE = /^(?:pip\d*|ensurepip|http\.server|simplehttpserver|smtpd|cgi\.?httpserver|pdb|pty|rlcompleter)$/;
+export function check(input, state) {
+    const tokens = tokenize(input.cmd);
+    const rawHead = tokens[0];
+    if (rawHead === undefined)
+        return null;
+    const head = interpreterOf(rawHead);
+    if (head === undefined)
+        return null;
+    const rest = tokens.slice(1);
+    const lowered = rest.map((t) => t.toLowerCase());
+    // `node -v` prints a version and runs nothing. This is the one shape that
+    // may pass without inspecting a path.
+    if (rest.length === 1 && QUERY_FLAGS.has(lowered[0] ?? ''))
+        return null;
+    if (FETCH_EXEC.has(head) && !isLocalToolchain(rest)) {
+        return ask('INTERP_FETCH_EXECUTE', `"${head}" downloads and runs a package that does not exist on disk yet. There is nothing local to audit.`);
+    }
+    const inline = lowered.find((t) => isInlineFlag(t));
+    if (inline !== undefined) {
+        return ask('INTERP_INLINE_BODY', `Inline program body ("${inline}"). The shape is unauditable by definition, regardless of what the body does.`);
+    }
+    if (lowered.some((t) => STDIN_TARGETS.has(t))) {
+        return ask('INTERP_STDIN', 'Program text arrives on stdin or a device path. There is no file argument, so an existence check would miss this entirely.');
+    }
+    // `-m` names an installed module. Unlike `-c` it cannot carry a body, so
+    // there is no code to audit and no path to check - which is why asking on
+    // every `-m` was a false positive: `python -m pytest` is an ordinary
+    // read-only test run, and with no approval UI composed ask means deny.
+    // The module is judged by what it can do instead: install, serve, or open a
+    // shell. Everything else is a normal program invocation.
+    const moduleAt = lowered.indexOf('-m');
+    if (moduleAt >= 0) {
+        const mod = lowered[moduleAt + 1] ?? '';
+        if (RISKY_MODULE.test(mod)) {
+            return ask('INTERP_MODULE_SELECTOR', `"-m ${mod}" runs a module that installs, serves the network, or opens an interactive shell, rather than a local script.`);
+        }
+    }
+    const workspaceRoot = state.workspaceRoot ?? process.cwd();
+    if (head === 'pip' || head === 'pip3' || head === 'pipx') {
+        const isInstall = lowered.includes('install');
+        const localSource = rest.some((t) => t === '.' || t === './' || /^[\\/]/.test(t));
+        if (isInstall && localSource) {
+            return ask('INTERP_LOCAL_BUILD', 'Local install runs the package build backend, which is arbitrary code at install time.');
+        }
+    }
+    // The first non-flag argument is the script target.
+    const target = rest.find((t) => !t.startsWith('-'));
+    if (target === undefined)
+        return null;
+    if (isVolatilePath(target)) {
+        return ask('INTERP_VOLATILE_PATH', `"${target}" lives under a temp root any process on the machine can write to. That is not a provenance claim.`);
+    }
+    if (isAbsolutePath(target)) {
+        if (!isInsideWorkspace(target, workspaceRoot)) {
+            return ask('INTERP_OUTSIDE_WORKSPACE', `"${target}" is outside the workspace. The operator cannot see the target without leaving the project.`);
+        }
+    }
+    else if (hasParentEscape(target)) {
+        return ask('INTERP_PARENT_ESCAPE', `"${target}" climbs above the workspace root with "..". It only looks relative.`);
+    }
+    // TOCTOU: write-then-run in the same session. Judging the two independently
+    // is a complete bypass, so the guard keeps a short-lived write ledger.
+    const recent = state.recentWrites ?? [];
+    const wanted = normalizePath(target);
+    const written = recent.some((w) => {
+        const n = normalizePath(w);
+        return n === wanted || n.endsWith('/' + wanted);
+    });
+    if (written) {
+        return ask('INTERP_RECENT_WRITE', `"${target}" was written earlier in this session and is being executed immediately. Write-then-run defeats any per-command check.`);
+    }
+    // Falls through: workspace-relative explicit script, no escape. Note what
+    // this does NOT assert: the file was never opened.
+    return null;
+}

package/lib/src/guard/lexical.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Lexical helpers. Pure string handling, no IO, no process access.
+ *
+ * Everything here is deliberately naive about shell grammar. The goal is not
+ * to emulate cmd.exe; it is to make sure that anything whose shape we cannot
+ * confidently read surfaces as an ask instead of sliding through as a pass.
+ */
+/** Split into whitespace-separated tokens, keeping quoted runs intact. */
+export declare function tokenize(cmd: string): string[];
+/**
+ * A newline outside quotes. Both shells treat it as a statement separator, so
+ * it chains exactly like `;` - but scanOperators covered only punctuation, and
+ * the chain therefore reached the rules layer as one command.
+ *
+ * Quoted newlines are data: `git commit -m "line one\nline two"` is one
+ * command, and treating it as two would be a false positive on every
+ * multi-line commit message.
+ */
+export declare function hasUnquotedNewline(cmd: string): boolean;
+/**
+ * Operators found outside quotes. Chaining is what hides a second stage
+ * behind a harmless first one, so any operator at all is worth surfacing.
+ */
+export declare function scanOperators(cmd: string): string[];
+/**
+ * Command substitution: `$(...)` and paired backticks.
+ *
+ * Measured bypass: `echo $(rm -rf /)` and a backtick-wrapped `rm -rf /` both
+ * passed with nothing objecting. Substitution was never in scanOperators, and
+ * the rules layer only ever reads tokens[0], so the inner command was invisible
+ * to every layer.
+ *
+ * Single quotes suppress substitution in POSIX shells, so their contents are
+ * skipped. Double quotes do not, so they are not.
+ *
+ * Backticks are ambiguous: in PowerShell a lone backtick is an escape
+ * (`"a`tb"` is a tab). A backtick with a closing partner is treated as
+ * substitution, a lone one as an escape. That keeps normal PowerShell strings
+ * from being flagged while closing the POSIX channel.
+ */
+export declare function hasCommandSubstitution(cmd: string): boolean;
+/**
+ * Bodies of every command substitution, so the split layer can run the hard
+ * rules against the inner text. Without this, `echo $(rm -rf /)` would only
+ * ever be an ask; the delete itself is what should decide the verdict.
+ */
+export declare function substitutionBodies(cmd: string): string[];
+/**
+ * Split into the individual statements a chain would run. Used only to escalate
+ * a hard deny that sits behind a separator: `git status && rm -rf /` used to be
+ * an ask from the split layer, which hid the deny the rules layer would have
+ * produced for the second statement. Deny must win.
+ *
+ * Quotes are honoured, so `echo "a;b"` stays one segment.
+ */
+export declare function splitSegments(cmd: string): string[];
+/**
+ * Process substitution. The path handed to the tool is an anonymous pipe that
+ * never exists on disk, so no provenance check can apply to it. Checked with
+ * quotes ignored on purpose: it is legal inside a quoted shell argument.
+ */
+export declare function hasProcessSubstitution(cmd: string): boolean;
+/**
+ * A caret wedged inside a word (`d^e^l`). Outside the word, `^|` is an
+ * escaped operator and belongs to the split layer instead.
+ */
+export declare function hasCaretInsideWord(cmd: string): boolean;
+/** Forward slashes, lowercase. Used for every path comparison. */
+export declare function normalizePath(p: string): string;
+/** Last segment of a Windows or POSIX path, quotes already stripped. */
+export declare function baseName(p: string): string;
+/** True when `p` is `root` itself or sits underneath it. */
+export declare function isInsideWorkspace(p: string, root: string): boolean;
+/** `C:\x`, `C:/x`, `\\server\share`, `/usr/x`. */
+export declare function isAbsolutePath(p: string): boolean;
+/** Any `..` segment, which may climb above the workspace root. */
+export declare function hasParentEscape(p: string): boolean;
+/** Roots any process on the machine can write to. Not a provenance claim. */
+export declare function isVolatilePath(p: string): boolean;