dsh-cmd-guard 0.0.0-stage → 0.1.1

package/lib/src/guard/capability.js

@@ -0,0 +1,337 @@
+import { effectiveTokens, plainToken, stemVerb, isHuntVerb, WRAPPERS } from './normalize.js';
+import { HUNT_VERBS, SHELL_KEYWORDS } from './verbs.js';
+/**
+ * Heads whose remaining tokens are data and which cannot execute a payload.
+ *
+ * Deliberately narrower than HUNT_STOP: that set also holds `python`, `node`
+ * and `npm`, whose tails are usually data but which can execute on request
+ * (`python -c`). Those are judged, not exempted.
+ *
+ * Membership is a claim that the tail cannot change the machine. `sort`,
+ * `less`, `rg`, `ag` and `man` were added and then removed on measurement:
+ * sort -o writes a file, less -o writes a log, rg --pre and ag --pager run a
+ * program, man -P runs the pager. Each of those passed with a system target.
+ * `tee`,
+ * `touch`, `env`, `date`, `hostname`, `ipconfig` and `ifconfig` all failed
+ * that claim: each writes a file, a variable or host state, and each was
+ * measured carrying a system target through this layer untouched. The
+ * exemption set is an attack surface of its own, so it is now read-only only.
+ */
+const DATA_TAIL = new Set([
+    'echo',
+    'printf',
+    'which',
+    'where',
+    'type',
+    'help',
+    'grep',
+    'cat',
+    'ls',
+    'dir',
+    'head',
+    'tail',
+    'more',
+    'uniq',
+    'wc',
+    'diff',
+    'whoami',
+    'pwd',
+    'ping',
+    'nslookup',
+    'whereis',
+    'findstr',
+]);
+/** Build, packaging and VCS tools: their capability is argued by the why layer. */
+const TOOLCHAINS = new Set([
+    'git',
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    'cargo',
+    'go',
+    'dotnet',
+    'make',
+    'gradle',
+    'mvn',
+    'tsc',
+    'eslint',
+    'prettier',
+    'code',
+]);
+/** Everything this layer declines to judge, for the reasons stated per set. */
+const EXEMPT = new Set([
+    ...DATA_TAIL,
+    ...TOOLCHAINS,
+    ...WRAPPERS,
+    ...HUNT_VERBS,
+    ...SHELL_KEYWORDS,
+    // Policy heads are already judged by the rules layer; repeating them here
+    // would only add a second, weaker verdict for the same command.
+    'reg',
+    'sc',
+    'netsh',
+    'wmic',
+    'bcdedit',
+    'diskpart',
+    'shutdown',
+    'reboot',
+    'taskkill',
+    'format',
+]);
+/**
+ * Where a command is pointed, as opposed to what it is called.
+ *
+ * Anchored on purpose: an argument that merely mentions a system path inside a
+ * sentence ("fix /etc/passwd handling") must not match, or every commit message
+ * that names a file becomes an ask.
+ */
+const SENSITIVE_TARGET = [
+    /^[a-z]:\\windows(?:\\|$)/i,
+    /^[a-z]:\\program files(?: \(x86\))?(?:\\|$)/i,
+    /^[a-z]:\\programdata(?:\\|$)/i,
+    /^[a-z]:\\users\\?$/i,
+    /^[a-z]:\\?$/i,
+    // `-v C:\:C:\` names the drive root as the volume source.
+    /^[a-z]:\\:/i,
+    /^\/{1,3}$/,
+    // `docker run -v /:/host` mounts the machine into the container: the colon
+    // splits source from target, so the root is the part before it.
+    /^\/:/,
+    /^\/(?:etc|bin|sbin|boot|usr|var|lib|lib64|root|home|opt|dev)(?:\/|$)/i,
+    /^hk(?:lm|cr|u|cc)\\/i,
+    /^\\\\\?\\/,
+];
+/** Files whose disclosure or loss is not recoverable by a later step. */
+const CREDENTIAL_TARGET = /(?:^|[\\/])(?:shadow|sudoers|gshadow|passwd|id_rsa|id_ed25519|\.git-credentials|credentials|ntds\.dit|\.bash_history)$/i;
+/** Registry hives and the local account database: readable, not ours to read. */
+const SECRET_STORE = /(?:^|[\\/])config[\\/](?:sam|system|security|default|ntuser\.dat)$/i;
+/** Bulk-mutation flag families. Common alone, not together. */
+const RECURSIVE_FLAG = [
+    /^-[a-z]*r[a-z]*$/i,
+    /^--recursive(?:=.*)?$/i,
+    /^\/s$/i,
+    /^-recurse$/i,
+];
+const FORCE_FLAG = [
+    /^-[a-z]*f[a-z]*$/i,
+    /^--force(?:=.*)?$/i,
+    /^-(?:fo|force)$/i,
+    /^\/[fqy]$/i,
+];
+/** Subcommands that remove the resource they name. */
+const REMOVE_SUBCOMMAND = /^(?:delete|remove|rm|rmi|destroy|drop|purge|prune|uninstall|wipe|evict|terminate)$/i;
+/**
+ * Heads with no scoped use at all.
+ *
+ * `ntdsutil` was measured passing with no argument: the head was unfamiliar
+ * and there was nothing to look at. It is an interactive editor for the
+ * directory database, so being invoked is the whole signal.
+ */
+const ALWAYS_SUSPICIOUS = new Set([
+    'ntdsutil',
+    'dcpromo',
+    'adsi',
+    'dsacls',
+    'vssadmin',
+]);
+/**
+ * Hosts that exist to run a file someone else wrote.
+ *
+ * `wscript payload.vbs` and `mofcomp payload.mof` have no scoped, benign
+ * invocation to fall back on, and neither name nor shape matched anything, so
+ * both passed. Being invoked is the signal.
+ */
+const SCRIPT_HOSTS = new Set([
+    'wscript',
+    'cscript',
+    'installutil',
+    'mofcomp',
+    'msxsl',
+    'regasm',
+    'regsvcs',
+]);
+/** Flags whose value is a destination, not an option. */
+const DEST_FLAG = /^(?:-C|-d|--directory|--prefix|--root|--target-dir|--output-dir|-v|--volume|--mount|-o|--output|--output-file|-O|--out)(?:=|$)/;
+/**
+ * Flags whose value is a program to run rather than a file to read.
+ *
+ * `rg --pre "sh -c id"`, `ag --pager "rm -rf /"` and `man -P "rm -rf /"` all
+ * passed: the head was exempt and the value looked like any other argument.
+ */
+const EXEC_FLAG = /^(?:--pre|--pager|-P)(?:=|$)/;
+/** Flags that pull a payload from the network rather than name a file. */
+const DOWNLOAD_FLAG = /^-(?:urlcache|outfile|outputpath|encodedcommand|enc|e|w|windowstyle|downloadstring|downloadfile)(?:=.*)?$/i;
+/**
+ * Heads that change host identity, clock, volume layout or service state.
+ *
+ * A head is only suspicious when it is followed by an argument that matches,
+ * so the bare forms (`hostname`, `date`) stay silent. Stated as a capability
+ * rather than an intent: renaming a host changes what every later operation
+ * on this machine is talking to.
+ */
+const HOST_STATE = new Map([
+    ['hostname', /./],
+    ['hostnamectl', /^set-/i],
+    ['date', /^(?:-s|--set|-d)$/i],
+    ['timedatectl', /^set-/i],
+    ['w32tm', /^\/config/i],
+    ['tzutil', /^\/s(?:$|\s)/i],
+    ['format-volume', /./],
+    ['clear-disk', /./],
+    ['initialize-disk', /./],
+    ['new-partition', /./],
+    ['remove-partition', /./],
+    ['resize-partition', /./],
+    ['new-service', /./],
+    ['set-service', /./],
+    ['remove-service', /./],
+    ['new-localuser', /./],
+    ['add-localgroupmember', /./],
+    ['wevtutil', /^(?:cl|clear-log)/i],
+    ['auditpol', /^(?:\/set|\/clear|\/remove)/i],
+    ['logman', /^(?:create|delete|update|start|stop)/i],
+    ['mshta', /./],
+    ['rundll32', /./],
+    ['regsvr32', /./],
+    // Service state and scheduled-task removal. `net stop winmgmt` and
+    // `schtasks /delete` were exempt on the argument that the rules layer owns
+    // these heads. It owns the create/add forms; stopping a service and
+    // removing a task are the same class of state change and were unowned.
+    ['net', /^(?:stop|start|pause|continue|config|share|accounts)$/i],
+    ['schtasks', /^\/?(?:delete|change|run|end)$/i],
+    // Persistent environment and file attributes. `setx FOO bar` writes user
+    // environment for every later process; `attrib +s +h` hides a file from
+    // ordinary listings. Both read as harmless and neither had a signal.
+    ['setx', /./],
+    ['attrib', /^\+[a-z]+$/i],
+]);
+/** Flags whose next argument is code, not a file. */
+const INLINE_FLAG = [
+    /^-[ce]$/i,
+    /^-r$/i,
+    /^--eval(?:=.*)?$/i,
+    /^-(?:command|encodedcommand|exec|execdir|eval)$/i,
+    /^\/c$/i,
+];
+/**
+ * Strip an option's leading `--name=` so the value is compared, not the flag.
+ * `--prefix=/etc/x` writes under /etc; `/^\/(?:etc)/` never sees it otherwise.
+ */
+function valueOf(token) {
+    return token.replace(/^-{1,2}[A-Za-z][A-Za-z0-9_-]*=/, '');
+}
+function isSensitive(token) {
+    const v = valueOf(token);
+    if (v.length === 0)
+        return false;
+    if (CREDENTIAL_TARGET.test(v))
+        return true;
+    return SENSITIVE_TARGET.some((re) => re.test(v));
+}
+export function check(input, _state) {
+    const raw = effectiveTokens(input.cmd);
+    const first = raw[0];
+    if (first === undefined)
+        return null;
+    const head = stemVerb(first);
+    if (head.length === 0)
+        return null;
+    // Reading a credential file is worth a question whether or not the head is
+    // exempt: `cat /etc/shadow` is a read, and the read is the whole problem.
+    // This check sits before the exemption return on purpose.
+    const plain = raw.map(plainToken).filter((t) => t.length > 0);
+    const secret = plain.find((t) => {
+        const v = valueOf(t);
+        return SECRET_STORE.test(v) || CREDENTIAL_TARGET.test(v);
+    });
+    if (secret !== undefined) {
+        return {
+            layer: 'capability',
+            verdict: 'ask',
+            code: 'UNKNOWN_CAPABILITY',
+            reason: `"${head}" reads "${secret}", a credential store. Reading it is the disclosure.`,
+        };
+    }
+    if (EXEMPT.has(head))
+        return null;
+    // A token that came out of quotes keeps its spaces; one that did not is a
+    // word the shell would pass as a single argument. Sentences are not targets.
+    const tokens = raw.map(plainToken).filter((t) => t.length > 0 && !/\s/.test(t));
+    if (tokens.length === 0)
+        return null;
+    const signals = [];
+    const target = tokens.find(isSensitive);
+    if (target !== undefined) {
+        signals.push(`points at "${target}", a system, volume or credential location`);
+    }
+    const recursive = tokens.some((t) => RECURSIVE_FLAG.some((re) => re.test(t)));
+    const force = tokens.some((t) => FORCE_FLAG.some((re) => re.test(t)));
+    if (recursive && force)
+        signals.push('carries recursive and force flags together');
+    const inlineAt = tokens.findIndex((t) => INLINE_FLAG.some((re) => re.test(t)));
+    if (inlineAt >= 0 && tokens.length > inlineAt + 1) {
+        signals.push('takes code as an argument rather than a file');
+    }
+    // A destination flag: the target is the flag's value, not any token.
+    // `tar -xf a.tar -C /etc` and `docker run -v /:/host` were both passing,
+    // because no token in them looks like a path on its own.
+    for (let i = 0; i < tokens.length; i += 1) {
+        const flag = tokens[i] ?? '';
+        const m = DEST_FLAG.exec(flag);
+        if (m === null)
+            continue;
+        const inline = flag.slice(m[0].length);
+        const value = inline.length > 0 ? inline : (tokens[i + 1] ?? '');
+        const cleaned = valueOf(plainToken(value));
+        if (cleaned.length > 0 && isSensitive(cleaned)) {
+            signals.push(`writes to "${cleaned}", a location outside the workspace`);
+            break;
+        }
+    }
+    if (tokens.some((t) => DOWNLOAD_FLAG.test(t))) {
+        signals.push('takes a download or an encoded payload');
+    }
+    // Host identity, clock and volume layout. These heads read as harmless and
+    // `hostname ATTACKER`, `date -s ...` and `w32tm /config ...` all passed.
+    const statePattern = HOST_STATE.get(head);
+    if (statePattern !== undefined) {
+        const hit = tokens.slice(1).find((t) => statePattern.test(plainToken(t)));
+        if (hit !== undefined)
+            signals.push(`changes machine state with "${hit}"`);
+    }
+    // Tools whose destructive act is spelled as a subcommand rather than a
+    // verb in head position: `kubectl delete ns kube-system` passed, because
+    // the head was unfamiliar and no token looked like a path. The subcommand
+    // is what the tool is about to remove, so it is judged on its own.
+    const sub = tokens[1];
+    if (sub !== undefined && REMOVE_SUBCOMMAND.test(plainToken(sub))) {
+        signals.push(`runs "${plainToken(sub)}", which removes whatever it names`);
+    }
+    // Tools that open a privileged console and change machine-wide identity or
+    // the directory database the machine authenticates against. There is no
+    // scoped invocation of these, so the head alone is enough.
+    if (ALWAYS_SUSPICIOUS.has(head)) {
+        signals.push('edits the machine directory database or partition table directly');
+    }
+    if (SCRIPT_HOSTS.has(head)) {
+        signals.push('exists to run a script file rather than to do one job');
+    }
+    // A flag whose value is another program. The value is what runs, and the
+    // value is what nothing was looking at.
+    const execAt = tokens.findIndex((t) => EXEC_FLAG.test(t));
+    if (execAt >= 0 && tokens.length > execAt + 1) {
+        signals.push(`runs "${tokens[execAt + 1]}" as a subprocess`);
+    }
+    if (tokens.slice(1).some((t) => isHuntVerb(t))) {
+        signals.push('carries a destructive verb as an argument');
+    }
+    if (signals.length === 0)
+        return null;
+    return {
+        layer: 'capability',
+        verdict: 'ask',
+        code: 'UNKNOWN_CAPABILITY',
+        reason: `"${head}" is not a known tool, and it ${signals.join('; ')}. An unfamiliar program is judged by what it can do to the machine, not by its name.`,
+    };
+}

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;