@coo-quack/sensitive-canary 0.7.0 → 0.8.0

package/src/lib/command-tables.ts

@@ -0,0 +1,518 @@
+// What this hook knows about how each command treats its operands.
+//
+// The tables are the knowledge and nothing here is logic: which commands print
+// a file they are handed, which take a pattern first, which run another
+// command. A command missing from a table is a file that goes unscanned, so
+// every table has a case per entry in the suite and an equality assertion
+// beside it — a generated case cannot notice a deletion.
+
+import type { ShellToken } from "./shell.ts";
+
+// Commands that write the contents of every non-flag argument to stdout.
+// `wc` is deliberately absent: it reports counts, never the bytes themselves.
+export const FILE_READ_COMMANDS = new Set([
+  "cat",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "bat",
+  // `view` is read-only vi and `vimdiff` opens two files at once; both print
+  // the contents the way `less` does.
+  "view",
+  "vimdiff",
+  "nl",
+  "tac",
+  "rev",
+  "strings",
+  "xxd",
+  "od",
+  "hexdump",
+  "base64",
+  "cut",
+  "sort",
+  "uniq",
+  "shuf",
+  "column",
+  "paste",
+  "fold",
+  "fmt",
+  "pr",
+  "expand",
+  "unexpand",
+  "iconv",
+  "zcat",
+  "gzcat",
+  "bzcat",
+  "xzcat",
+  "zstdcat",
+  "lz4cat",
+  "lzcat",
+  "zless",
+  "zmore",
+  "bzless",
+  "xzless",
+  "diff",
+  "comm",
+  "join",
+  "look",
+]);
+
+// Commands that read a file but report only measurements of it. Their stdin is
+// not echoed either, so a redirection into one of them is not a read.
+// The rest of the digest family, and the BSD spellings, were missing. Naming a
+// file, that costs nothing — an unclassified command's operands are not
+// collected either. Over `<` it did: stdin is collected for any command not
+// known to print no contents, so `sha512sum < secrets` was scanned while
+// `sha256sum < secrets` was not. The wrong direction is only a false block, but
+// the two spellings disagreeing is not something to leave in a table.
+export const COUNT_ONLY_COMMANDS = new Set([
+  "wc",
+  "cksum",
+  "sum",
+  "md5",
+  "md5sum",
+  "shasum",
+  "sha1sum",
+  "sha224sum",
+  "sha256sum",
+  "sha384sum",
+  "sha512sum",
+  "b2sum",
+]);
+
+// Commands whose first non-flag argument is a pattern, expression or script,
+// and whose remaining non-flag arguments are files written to stdout.
+// General-purpose runtimes (`python`, `node`, `deno`, `bun`, and `perl` and
+// `ruby` when they run a program file) are absent: they execute their first
+// argument rather than print it, and the files named after it are argv, not
+// output. Their inline code (`-c`, `-e`) is still scanned via
+// INLINE_CODE_COMMANDS.
+export const PATTERN_OR_SCRIPT_FIRST_COMMANDS = new Set([
+  "sed",
+  "awk",
+  "gawk",
+  "grep",
+  "egrep",
+  "fgrep",
+  "rg",
+  "ag",
+  "jq",
+  "yq",
+  "zgrep",
+  "zegrep",
+  "zfgrep",
+  "ack",
+  "ugrep",
+]);
+
+// Flags that hand a pattern-first command its pattern or script, so no operand
+// is standing in for it. Without this, `grep --regexp=aws secrets` and
+// `sed --expression='s/a/b/' secrets` consumed the file as the pattern and never
+// scanned it. The separate-value forms name a pattern or a pattern file, neither
+// of which is printed, so their value is skipped rather than collected.
+export const PATTERN_SUPPLYING_FLAGS = new Set([
+  "-e",
+  "--regexp",
+  "--expression",
+  "-f",
+  "--file",
+  "--from-file",
+]);
+
+// Whether a flag token supplies the pattern, and whether its value is already
+// attached to it.
+//
+// Three spellings carry a value: separate (`-e aws`, `--regexp aws`), attached
+// after `=` (`--regexp=aws`), and attached directly to a short flag
+// (`-eaws`, `sed -e's/a/b/'`). Only the first two were recognised, so an attached
+// short value left `patternSkipped` unset and the file that followed was eaten as
+// the pattern — `grep -eaws secrets` and `sed -e's/a/b/' secrets` scanned nothing.
+export function patternSupplyingFlag(
+  token: string,
+): "attached" | "separate" | null {
+  const equals = token.indexOf("=");
+  const beforeEquals = equals === -1 ? token : token.slice(0, equals);
+  if (PATTERN_SUPPLYING_FLAGS.has(beforeEquals)) {
+    return equals === -1 ? "separate" : "attached";
+  }
+  // A short flag with its value written against it. Long flags are excluded:
+  // `--file-name` is not `--file` with `-name` attached.
+  if (!token.startsWith("--") && token.length > 2) {
+    if (PATTERN_SUPPLYING_FLAGS.has(token.slice(0, 2))) return "attached";
+  }
+  return null;
+}
+
+// Flags of a read command whose separate value names a file to write, not one to
+// read: `sort -o out.txt in.txt` prints nothing of `out.txt`, and scanning it
+// blocked a command that only ever writes there.
+//
+// Keyed per command rather than by flag name, because the same letter means
+// different things: `-o` is an output file for these three but an octal-format
+// flag taking no value for `od` and `hexdump`, so a shared list would swallow
+// the operand of `od -o secrets` and miss the read.
+export const WRITE_TARGET_FLAGS: Record<string, Set<string>> = {
+  sort: new Set(["-o", "--output"]),
+  shuf: new Set(["-o", "--output"]),
+  iconv: new Set(["-o", "--output"]),
+};
+
+// Interpreters whose file operands are input to a one-liner given inline:
+// `perl -pe 's/a/b/' f` and `ruby -pe '…' f` print f. Hand them a program file
+// instead and the operands are argv — `perl script.pl data.txt` prints neither —
+// so their operands count as reads only once inline code has been seen.
+export const INLINE_CODE_READS_OPERANDS = new Set(["perl", "ruby"]);
+
+// Commands that run another command. They are stripped so the wrapped command
+// is classified instead: `sudo cat secrets` is treated as `cat secrets`.
+//
+// `timeout` and `flock` take an operand of their own first (`timeout 5 cat f`,
+// `flock /tmp/lock cat f`) and sat in a set of their own for a while. Nothing
+// ever asked which set a name came from — the one place that read them ORed the
+// two — because the search does not need to know: it walks forward to the first
+// name it can classify, which steps over an operand as readily as over a flag.
+export const WRAPPER_COMMANDS = new Set([
+  "sudo",
+  "doas",
+  "command",
+  "builtin",
+  "exec",
+  "nohup",
+  "time",
+  "nice",
+  "ionice",
+  "stdbuf",
+  "xargs",
+  "env",
+  "timeout",
+  "flock",
+  // `eval cat secrets` runs its arguments as a command line, so the command to
+  // classify is the one after it, exactly as with the wrappers above.
+  "eval",
+]);
+
+// Interpreters that accept inline program text, which is scanned both as a
+// nested command line and for quoted path literals.
+export const INLINE_CODE_COMMANDS = new Set([
+  "sh",
+  "bash",
+  "zsh",
+  "dash",
+  "ksh",
+  "python",
+  "python3",
+  "perl",
+  "ruby",
+  "node",
+  "deno",
+  "bun",
+  "php",
+]);
+
+export const POSIX_SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+
+// git subcommands that can write file contents to stdout. Blob references such
+// as `git show HEAD:.env` name history, not the working tree, and stay
+// uncovered — only paths that exist on disk are scanned. `difftool` hands off
+// to an external tool and `stash` prints no file contents, so neither is here:
+// classifying them would push tokens like the `pop` in `git stash pop` as paths.
+export const GIT_READ_SUBCOMMANDS = new Set([
+  "show",
+  "diff",
+  "blame",
+  "annotate",
+  "grep",
+  "cat-file",
+]);
+
+// `-L` is not here: it prints the lines of one named file rather than a patch of
+// whatever operands follow, so it is handled where that file is extracted from
+// the range spec. Listing it here as well marked every other operand of the same
+// command as read.
+//
+// `git log <file>` prints who changed the file and when, never a line of it, so
+// it belongs with the subcommands above only when a patch is asked for. Treating
+// it as a read unconditionally blocked an everyday way of looking at history.
+//
+// The flags are the ones that produce a diff: `-U<n>` and `--unified=<n>` imply
+// `--patch`, and the merge-diff forms print one too. A flag not listed here
+// leaves the file unscanned, so the list errs towards including anything that
+// might print contents — `git -c k=v log f` matches `-c` and is scanned, which
+// is the harmless direction to be wrong in.
+function gitLogPrintsFileContents(operands: ShellToken[]): boolean {
+  return operands.some(({ value }) => {
+    if (value === "-p" || value === "-u" || value === "-c" || value === "-m") {
+      return true;
+    }
+    return (
+      value.startsWith("--patch") ||
+      value.startsWith("-U") ||
+      value.startsWith("--unified") ||
+      value.startsWith("--cc") ||
+      value.startsWith("--diff-merges")
+    );
+  });
+}
+
+// The file named inside a `git log -L` argument, which carries it after the last
+// `:` of a range spec (`-L1,10:f`, `-L:funcname:f`). Written as a path on its
+// own it would never be found, since the range is part of the token.
+export function gitLineRangeFile(value: string): string | null {
+  const colon = value.lastIndexOf(":");
+  if (colon === -1) return null;
+  const file = value.slice(colon + 1);
+  return file === "" ? null : file;
+}
+
+// Whether a git subcommand writes the contents of the files named after it.
+export function gitSubcommandPrintsFiles(
+  subcommand: string,
+  operands: ShellToken[],
+): boolean {
+  if (subcommand === "log") return gitLogPrintsFileContents(operands);
+  return GIT_READ_SUBCOMMANDS.has(subcommand);
+}
+
+// Commands whose `-i` rewrites the files it is handed instead of printing them,
+// each with the short switches it accepts without a value.
+//
+// Being on this list at all is what makes `-i` mean in-place: `grep -i` matches
+// case-insensitively and still prints. The letters are what let a bundle be read
+// one at a time in search of the `i`.
+//
+// One table rather than two. A separate set of command names said the same thing
+// as these keys, and the two could disagree — adding `awk` to the set alone made
+// `awk -i` an in-place edit, which a test had to be written to catch. Nothing can
+// disagree with itself.
+//
+// Per command, because the letters differ and sharing one set got it wrong in
+// both directions: `E`, `r` and `z` are valueless for `sed` but absent from a
+// set chosen for `perl`, so the everyday `sed -Ei` was read as a non-in-place
+// command and its file scanned; while `0` was present for `perl -0777`, which
+// made `sed -0i` — not a sed flag at all — look like an in-place edit and left
+// its file unscanned.
+//
+// A letter that is not here stops the reading, whether it takes a value or the
+// list simply does not know it. That is the fail-closed direction: the command
+// is then treated as one that prints, and its operands are scanned.
+// `e` is absent from every line on purpose: it introduces a script for all three,
+// and a sed script contains `i` as its insert command, so reading past `-e` would
+// find an `i` in the program text and call the command an in-place edit.
+export const IN_PLACE_EDITORS: Record<string, string> = {
+  sed: "anszEru",
+  perl: "aclnpsStTuUvwWX",
+  ruby: "acdlnpsSTUvwWy",
+};
+
+// True when `cmd` edits in place given `value` as one of its flags: `-i`,
+// `-i.bak`, or a bundle reaching `i` past that command's valueless switches
+// (`-pi`, `-lpi`, `-Ei`).
+//
+// A command absent from the table is not an in-place editor at all, so no flag of
+// it counts — `grep -i` and `grep --in-place` alike.
+//
+// `--in-place` is sed's alone. Accepting it from every command in the table meant
+// `perl --in-place=.bak -pe 'x' secrets` and the same for `ruby` were treated as
+// in-place edits and their files went unscanned, though neither interpreter has
+// that flag: perl and ruby spell it `-i`, and would reject the long form.
+export function isInPlaceFlag(cmd: string, value: string): boolean {
+  const valueless = IN_PLACE_EDITORS[cmd];
+  if (valueless === undefined) return false;
+
+  if (cmd === "sed" && value.replace(/=.*/, "") === "--in-place") return true;
+  if (!value.startsWith("-") || value.startsWith("--")) return false;
+
+  for (const ch of value.slice(1)) {
+    if (ch === "i") return true;
+    if (!valueless.includes(ch)) return false;
+  }
+  return false;
+}
+
+// `--` ends option parsing here as well: in `sed -- -i secrets`, `-i` is the
+// script and `secrets` is a file sed prints. Read as an in-place flag, the whole
+// command counted as writing and the file went unscanned.
+export function editsInPlace(cmd: string, operands: ShellToken[]): boolean {
+  for (const { value } of operands) {
+    if (value === "--") return false;
+    if (isInPlaceFlag(cmd, value)) return true;
+  }
+  return false;
+}
+
+// Global git flags that carry a separate value before the subcommand
+// (`git -C repo show f`, `git -c k=v show f`). Attached forms (`--git-dir=x`)
+// are single flag tokens and need no entry here.
+export const GIT_GLOBAL_FLAGS_WITH_OPERAND = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+  "--config-env",
+]);
+
+// Recursion limit for inline program text: each `-c` / `-e` script inside
+// another costs one level. Nested command substitutions are not bounded by it,
+// since the tokenizer ends a segment at a paren and reaches the inner command
+// without recursing. `depth` counts nesting, so the command line itself is 0 and
+// four levels of inline text below it are inspected.
+export const MAX_NESTING_DEPTH = 4;
+
+// References a single Bash command makes to data the hook can inspect.
+export interface CommandRefs {
+  // File paths whose contents the command may write to stdout.
+  paths: string[];
+  // Environment variables the command names explicitly.
+  envVars: string[];
+  // Whether the command dumps the whole environment (bare `env` / `printenv`).
+  dumpsEnvironment: boolean;
+  // Whether the command searches the working directory because it was given no
+  // file to search. `rg PATTERN` is the ordinary way to search a repository and
+  // names nothing, so there is no operand to collect and the whole tree it
+  // prints from went unscanned.
+  searchesWorkingDirectory: boolean;
+}
+
+// Searchers that walk the working directory when handed no path. The `grep`
+// family is not here: it reads stdin unless `-r` is given, and that flag is
+// what puts it in this class for the length of one command.
+export const RECURSIVE_BY_DEFAULT = new Set(["rg", "ag", "ack", "ugrep"]);
+
+export const GREP_FAMILY = new Set([
+  "grep",
+  "egrep",
+  "fgrep",
+  "zgrep",
+  "zegrep",
+  "zfgrep",
+]);
+
+// `-r`, `-R`, `--recursive`, and the letter inside a bundle such as `-rn`. A
+// bundle is read letter by letter because `grep -rn PATTERN` is how it is
+// usually typed.
+export function asksForRecursion(operands: ShellToken[]): boolean {
+  for (const tok of operands) {
+    if (tok.redirect) continue;
+    const v = tok.value;
+    if (v === "--recursive" || v === "--dereference-recursive") return true;
+    if (v === "--") break;
+    if (!v.startsWith("-") || v.startsWith("--") || v.length < 2) continue;
+    if (/[rR]/.test(v.slice(1))) return true;
+  }
+  return false;
+}
+
+// Fold one set of refs into another. A command line yields refs from several
+// places — its substitutions, each of its segments, the inline code it carries,
+// an `env -S` string — and combining them is the same three lines each time,
+// which is how it came to be written out three times with a closure alongside.
+export function mergeRefs(into: CommandRefs, refs: CommandRefs): void {
+  into.paths.push(...refs.paths);
+  into.envVars.push(...refs.envVars);
+  into.dumpsEnvironment = into.dumpsEnvironment || refs.dumpsEnvironment;
+  into.searchesWorkingDirectory =
+    into.searchesWorkingDirectory || refs.searchesWorkingDirectory;
+}
+
+// What this hook knows about how a command treats its operands.
+export interface CommandBehaviour {
+  // Every non-flag operand is a file written to stdout.
+  printsOperands: boolean;
+  // The first non-flag operand is a pattern or script name, the rest are files.
+  firstOperandIsPatternOrScript: boolean;
+  // -c / -e introduce inline program text.
+  takesInlineCode: boolean;
+  // Operands following inline program text are input files written to stdout.
+  inlineCodeReadsOperands: boolean;
+  // Reads a file but prints only a measurement of it, and does not echo stdin.
+  printsNoFileContents: boolean;
+  // `git <subcommand> [paths]`.
+  isGit: boolean;
+  // `dd if=<file>` names its input in an assignment-style operand.
+  isDd: boolean;
+}
+
+// Single place where a command name becomes a behaviour, so a name added to one
+// list cannot silently disagree with another.
+//
+// Not every per-command decision belongs here, and two deliberately stay out.
+// isClassifiableCommand below reads this record generically — any truthy field
+// means "operands understood" — which is what lets a new field be added without
+// updating it, and also what a field has to respect to live here:
+//
+//   - `WRITE_TARGET_FLAGS[cmd]` would arrive as a Set for the three commands
+//     that have one, and a Set is truthy whatever it holds. That would make
+//     `sort`, `shuf` and `iconv` classifiable on the strength of having an
+//     output flag, which says nothing about whether their operands are
+//     understood. (It is `undefined` for every other command, so the reach is
+//     those three, not all of them.)
+//   - `cmd === "env"` for the `-S` string would make `env` classifiable, and
+//     `env` is left out on purpose: it is a wrapper as often as a command.
+//
+// Both are therefore read from their tables at the point of use rather than
+// folded in here. Anything added to this record must be a boolean that means
+// "this hook understands what the command does with its operands".
+export function classifyCommand(cmd: string): CommandBehaviour {
+  return {
+    printsOperands: FILE_READ_COMMANDS.has(cmd),
+    firstOperandIsPatternOrScript: PATTERN_OR_SCRIPT_FIRST_COMMANDS.has(cmd),
+    takesInlineCode: INLINE_CODE_COMMANDS.has(cmd),
+    inlineCodeReadsOperands: INLINE_CODE_READS_OPERANDS.has(cmd),
+    printsNoFileContents: COUNT_ONLY_COMMANDS.has(cmd),
+    isGit: cmd === "git",
+    isDd: cmd === "dd",
+  };
+}
+
+// Commands whose operands this hook knows how to interpret. Derived from
+// classifyCommand so the two cannot silently disagree. `env` and `printenv`
+// are absent on purpose: they are wrappers as often as they are commands, and
+// inspectEnvironmentCommand handles the cases where they print the environment.
+export function isClassifiableCommand(name: string): boolean {
+  const behaviour = classifyCommand(name);
+  // Any behaviour at all means the operands are understood. Read from the object
+  // rather than listed field by field, so adding a field cannot leave this
+  // function silently disagreeing with classifyCommand.
+  return Object.values(behaviour).some(Boolean);
+}
+
+// Commands a wrapper may hand off to. Beyond the classifiable ones, `env` and
+// `printenv` count here — and only here — so wrapper operands do not hide an
+// environment dump: `sudo -u root printenv` must still find printenv.
+export function isWrapperTarget(name: string): boolean {
+  return isClassifiableCommand(name) || name === "env" || name === "printenv";
+}
+
+// Commands that write their operands out without ever opening them.
+//
+// These matter only to the wrapper search below, as the point where it has to
+// stop: everything after one of them is its own argument list. Without that
+// stop, `sudo echo cat secrets` walked past `echo` looking for a name it could
+// classify, found `cat` among echo's arguments, and blocked a command that
+// reads nothing.
+//
+// The set is deliberately short and cannot be complete — any command this hook
+// does not classify might be the one a wrapper handed off to, and the search
+// still walks past those. That is the direction to be wrong in: it collects
+// paths that are not read rather than missing a read, and `sudo -u root cat f`
+// depends on it, because `root` is not distinguishable from a command name.
+//
+// Treat this as a stopgap rather than a list to grow. Each name added buys one
+// more false positive and leaves the general case untouched, and a list that
+// accumulates one report at a time is the shape of a rule nobody wrote down. The
+// real fix is to model each wrapper's own arguments — the flags that take a
+// value, and the leading operand of `timeout` and `flock` — so the command
+// position is determinate and no allowlist is needed. That was not done here
+// because an incomplete table of those flags fails the other way, missing reads
+// instead of over-reporting them. If a third false positive of this shape turns
+// up, do that instead of adding a sixth name.
+export const ARGUMENT_ONLY_COMMANDS = new Set([
+  "echo",
+  "printf",
+  "true",
+  "false",
+  ":",
+]);