@coo-quack/sensitive-canary 0.7.0 → 0.8.0

package/dist/lib/command-tables.js

@@ -0,0 +1,462 @@
+// 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.
+// 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) {
+    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 = {
+    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) {
+    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) {
+    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, operands) {
+    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 = {
+    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, value) {
+    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, operands) {
+    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;
+// 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) {
+    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, refs) {
+    into.paths.push(...refs.paths);
+    into.envVars.push(...refs.envVars);
+    into.dumpsEnvironment = into.dumpsEnvironment || refs.dumpsEnvironment;
+    into.searchesWorkingDirectory =
+        into.searchesWorkingDirectory || refs.searchesWorkingDirectory;
+}
+// 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) {
+    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) {
+    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) {
+    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",
+    ":",
+]);