@sema-agent/core
Version:
Stateless, task-oriented AI agent core
408 lines (407 loc) • 20.4 kB
TypeScript
/**
* The wrapper programs the tightening reader ({@link import("./shell-lexer.js").readShellCommand}) peels to
* reach the program they run — upstream's three tables (its light strip on every arm, its full strip on
* the deny/ask arms, and its `xargs` clause inlined in the matcher) as ONE closed table. Peeling is
* ADDITIVE on the reading side: the segment keeps its spelled argv as one run candidate and adds one
* candidate per peeled layer, so a deny on the wrapper itself (`Bash(sudo:*)`) and a deny on the wrapped
* program both reach.
*
* The option grammar of every row is CLOSED, and that is the whole safety argument of the peel: a
* wrapper option the row does not name — short or long — stops the peel with an `unreadable` word (the
* caller asks a person) instead of guessing its arity, because a wrong guess names the option's VALUE
* or an operand as the program — a phantom run no deny matches. Three adversarial rounds found exactly
* that shape behind every "unknown is value-less" reading; the closed sets end the family rather than
* the instance. The table is the PROJECTION of the program read model's rows
* ({@link import("./shell-wrapper-projection.js").shellWrapperProjection}) written
* out with its literal type: a launcher fact is edited in its row (one table of program facts, read by the binary gate
* and by the read station alike), and `test/shell-wrapper-table-projection.test.ts` keeps the two equal.
*
* Per row: `valueFlags` — options whose value is the NEXT word (`-u root`; the attached `-uroot` and
* `--user=root` spellings are one word and need no row); `flags` — value-less options, including those
* whose value may only be ATTACHED (`--default-signal[=SIG]`, `xargs -i[R]`: bare, they take nothing);
* `attached` — short options whose OPTIONAL value may only be attached (`xargs -i[R]`: the rest of the cluster
* is the value, the next word never is); `commandString` — options whose value is a whole COMMAND STRING (`env -S 'rm -r x'`), unreadable here;
* `positional` — an operand that must precede the command (a priority, a cpu mask, a lock file; a word
* that does not match is unreadable, never the program); `duration` — `timeout`'s duration word;
* `bareDash` — `env -` (the obsolete spelling of `-i`); `assignments` — the wrapper takes `NAME=value`
* operands before its command (`env`, `sudo`; read dequoted, `env 'FOO=1' cmd`); `viaShell` — the program EVALUATES its
* operands as shell input (a command string, a script file, an expression: `watch`, `script`, `eval`,
* `source`, `bash -c`, `trap`, `let`), so the program behind it is never readable from the words — the
* string is not split and judged (upstream splits on whitespace; this reader takes the strict word);
* `executes` — a program that is NOT a wrapper but runs a command named after one of these words ANYWHERE
* in its argv (`find … -exec rm -r {} +`): such a word, or any expansion among its arguments (it could
* expand to that word), makes the program behind it unreadable; the program's own run is still read.
*/
export declare const SHELL_WRAPPER_TABLE: {
readonly command: {
readonly valueFlags: readonly [];
readonly flags: readonly ["-p"];
readonly commandString: readonly [];
};
readonly builtin: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly noglob: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly nocorrect: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly exec: {
readonly valueFlags: readonly ["-a"];
readonly flags: readonly ["-c", "-l"];
readonly commandString: readonly [];
};
readonly env: {
readonly valueFlags: readonly ["--argv0", "--chdir", "--unset", "-C", "-P", "-a", "-u"];
readonly flags: readonly ["--debug", "--default-signal", "--help", "--ignore-environment", "--ignore-signal", "--list-signal-handling", "--version", "-i", "-v"];
readonly commandString: readonly ["--split-string", "-S"];
readonly bareDash: true;
readonly assignments: true;
};
readonly sudo: {
readonly valueFlags: readonly ["--auth-type", "--chdir", "--chroot", "--close-from", "--command-timeout", "--group", "--host", "--other-user", "--prompt", "--role", "--type", "--user", "-C", "-D", "-R", "-T", "-U", "-a", "-g", "-h", "-p", "-r", "-t", "-u"];
readonly flags: readonly ["--askpass", "--background", "--bell", "--help", "--list", "--login", "--non-interactive", "--preserve-env", "--preserve-groups", "--remove-timestamp", "--reset-timestamp", "--set-home", "--shell", "--stdin", "--validate", "--version", "-A", "-E", "-H", "-K", "-P", "-S", "-V", "-b", "-i", "-k", "-l", "-n", "-s", "-v"];
readonly commandString: readonly [];
readonly assignments: true;
};
readonly doas: {
readonly valueFlags: readonly ["-C", "-a", "-u"];
readonly flags: readonly ["-L", "-n", "-s"];
readonly commandString: readonly [];
};
readonly pkexec: {
readonly valueFlags: readonly ["--user"];
readonly flags: readonly ["--disable-internal-agent", "--help", "--keep-cwd", "--version"];
readonly commandString: readonly [];
};
readonly nohup: {
readonly valueFlags: readonly [];
readonly flags: readonly ["--help", "--version"];
readonly commandString: readonly [];
};
readonly time: {
readonly valueFlags: readonly ["--format", "--output", "-f", "-o"];
readonly flags: readonly ["--append", "--help", "--portability", "--quiet", "--verbose", "--version", "-a", "-p", "-q", "-v"];
readonly commandString: readonly [];
};
readonly nice: {
readonly valueFlags: readonly ["--adjustment", "-n"];
readonly flags: readonly ["--help", "--version"];
readonly commandString: readonly [];
};
readonly timeout: {
readonly valueFlags: readonly ["--kill-after", "--signal", "-k", "-s"];
readonly flags: readonly ["--foreground", "--help", "--preserve-status", "--verbose", "--version", "-v"];
readonly commandString: readonly [];
readonly duration: true;
};
readonly stdbuf: {
readonly valueFlags: readonly ["--error", "--input", "--output", "-e", "-i", "-o"];
readonly flags: readonly ["--help", "--version"];
readonly commandString: readonly [];
};
readonly xargs: {
readonly valueFlags: readonly ["--arg-file", "--delimiter", "--max-args", "--max-chars", "--max-procs", "--process-slot-var", "-E", "-I", "-L", "-P", "-a", "-d", "-n", "-s"];
readonly flags: readonly ["--eof", "--exit", "--help", "--interactive", "--max-lines", "--no-run-if-empty", "--null", "--open-tty", "--replace", "--show-limits", "--verbose", "--version", "-0", "-o", "-p", "-r", "-t", "-x"];
readonly attached: readonly ["-i", "-l"];
readonly commandString: readonly [];
};
readonly watch: {
readonly valueFlags: readonly ["--equexit", "--interval", "--shotsdir", "-n", "-q", "-s"];
readonly flags: readonly ["--beep", "--chgexit", "--color", "--differences", "--errexit", "--exec", "--follow", "--help", "--no-color", "--no-rerun", "--no-title", "--no-wrap", "--precise", "--version", "-C", "-b", "-c", "-e", "-f", "-g", "-h", "-p", "-r", "-t", "-v", "-w", "-x"];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly ionice: {
readonly valueFlags: readonly ["--class", "--classdata", "--pgid", "--pid", "--uid", "-P", "-c", "-n", "-p", "-u"];
readonly flags: readonly ["--help", "--ignore", "--version", "-V", "-h", "-t"];
readonly commandString: readonly [];
};
readonly setsid: {
readonly valueFlags: readonly [];
readonly flags: readonly ["--ctty", "--fork", "--help", "--version", "--wait", "-c", "-f", "-w"];
readonly commandString: readonly [];
};
readonly taskset: {
readonly valueFlags: readonly [];
readonly flags: readonly ["--all-tasks", "--cpu-list", "--help", "--pid", "--version", "-a", "-c", "-p"];
readonly commandString: readonly [];
readonly positional: RegExp;
};
readonly chrt: {
readonly valueFlags: readonly ["--pid", "--sched-deadline", "--sched-period", "--sched-runtime", "-D", "-P", "-T", "-p"];
readonly flags: readonly ["--all-tasks", "--batch", "--deadline", "--fifo", "--help", "--idle", "--max", "--other", "--reset-on-fork", "--rr", "--verbose", "--version", "-R", "-a", "-b", "-d", "-f", "-i", "-m", "-o", "-r", "-v"];
readonly commandString: readonly [];
readonly positional: RegExp;
};
readonly strace: {
readonly valueFlags: readonly ["--attach", "--columns", "--const-print-style", "--detach-on", "--env", "--expr", "--interruptible", "--output", "--string-limit", "--summary-columns", "--summary-sort-by", "--summary-syscall-overhead", "--trace", "--trace-path", "--user", "-E", "-I", "-O", "-P", "-S", "-U", "-X", "-a", "-b", "-e", "-o", "-p", "-s", "-u"];
readonly flags: readonly ["--debug", "--follow-forks", "--help", "--summary", "--summary-only", "--version", "-C", "-D", "-F", "-T", "-V", "-Z", "-c", "-d", "-f", "-h", "-i", "-k", "-q", "-r", "-t", "-v", "-w", "-x", "-y", "-z"];
readonly commandString: readonly [];
};
readonly ltrace: {
readonly valueFlags: readonly ["--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "--where", "-A", "-D", "-F", "-a", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-w", "-x"];
readonly flags: readonly ["--demangle", "--help", "--version", "-C", "-L", "-S", "-T", "-V", "-c", "-f", "-i", "-r", "-t"];
readonly commandString: readonly [];
};
readonly flock: {
readonly valueFlags: readonly ["--conflict-exit-code", "--timeout", "--wait", "-E", "-w"];
readonly flags: readonly ["--close", "--exclusive", "--help", "--nb", "--no-fork", "--nonblock", "--shared", "--unlock", "--verbose", "--version", "-F", "-n", "-o", "-s", "-u", "-x"];
readonly commandString: readonly ["--command", "-c"];
readonly positional: RegExp;
};
readonly script: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly ["--command", "-c"];
readonly viaShell: true;
};
readonly unshare: {
readonly valueFlags: readonly ["--boottime", "--map-group", "--map-user", "--monotonic", "--propagation", "--root", "--setgid", "--setgroups", "--setuid", "--wd", "-G", "-R", "-S", "-w"];
readonly flags: readonly ["--cgroup", "--fork", "--help", "--ipc", "--keep-caps", "--kill-child", "--map-current-user", "--map-root-user", "--mount", "--mount-proc", "--net", "--pid", "--time", "--user", "--uts", "--version", "-C", "-T", "-U", "-c", "-f", "-i", "-m", "-n", "-p", "-r", "-u"];
readonly commandString: readonly [];
};
readonly nsenter: {
readonly valueFlags: readonly ["--setgid", "--setuid", "--target", "-G", "-S", "-t"];
readonly flags: readonly ["--all", "--cgroup", "--help", "--ipc", "--mount", "--net", "--no-fork", "--pid", "--preserve-credentials", "--root", "--time", "--user", "--uts", "--version", "--wd", "-C", "-F", "-T", "-U", "-Z", "-a", "-i", "-m", "-n", "-p", "-u"];
readonly attached: readonly ["-r", "-w"];
readonly commandString: readonly [];
};
readonly eval: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly source: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly ".": {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly trap: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly let: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly sh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly bash: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly zsh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly dash: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly ksh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly fish: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly csh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly tcsh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly find: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly executes: readonly ["-exec", "-execdir", "-ok", "-okdir"];
};
readonly compgen: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly executes: readonly ["-C", "-F"];
};
readonly complete: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly executes: readonly ["-C", "-F"];
};
readonly busybox: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly su: {
readonly valueFlags: readonly ["--group", "--shell", "--supp-group", "--whitelist-environment", "-G", "-g", "-s", "-w"];
readonly flags: readonly ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"];
readonly commandString: readonly ["--command", "--session-command", "-c"];
readonly viaShell: true;
};
readonly runuser: {
readonly valueFlags: readonly ["--group", "--shell", "--supp-group", "--user", "--whitelist-environment", "-G", "-g", "-s", "-u", "-w"];
readonly flags: readonly ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"];
readonly commandString: readonly ["--command", "--session-command", "-c"];
readonly viaShell: true;
};
readonly chroot: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly positional: RegExp;
};
readonly setpriv: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly numactl: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly prlimit: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly "systemd-run": {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly valgrind: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly firejail: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly bwrap: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
};
readonly ash: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly mksh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly yash: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly pdksh: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly parallel: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly alias: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly viaShell: true;
};
readonly mapfile: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly executes: readonly ["-C"];
};
readonly readarray: {
readonly valueFlags: readonly [];
readonly flags: readonly [];
readonly commandString: readonly [];
readonly executes: readonly ["-C"];
};
};
export type ShellWrapperName = keyof typeof SHELL_WRAPPER_TABLE;
/** The shape of one row (see the table's contract). */
export interface ShellWrapperRow {
readonly valueFlags: readonly string[];
readonly flags: readonly string[];
readonly attached?: readonly string[];
readonly commandString: readonly string[];
readonly positional?: RegExp;
readonly duration?: true;
readonly bareDash?: true;
readonly assignments?: true;
readonly viaShell?: true;
readonly executes?: readonly string[];
}
/** Builtins whose OPERANDS name variables: an operand spelling an array element with a non-numeric
* subscript (`arr[a]`, quoted, bare, attached `-varr[a]`, or `arr[a]=1`) is evaluated as arithmetic —
* recursively, like `$((a))` — when the builtin reads or writes it (`printf -v 'arr[a]' …`, `unset arr[a]`,
* `declare arr[a]=1`, `read arr[a]`, `[[ -v arr[a] ]]`, `test -v arr[a]`), and so is the value of an
* INTEGER-attribute assignment (`declare -i x=a`). The lexer marks such a run's hidden run at every peel
* candidate (`command printf -v …`). An operand that is WHOLLY an expansion is not judged here (`unset "$X"`
* — one more indirection; the price of reading it would be a prompt on every `export FOO="$BAR"`), nor is
* an arithmetic comparison's operand (`[[ $n -gt 0 ]]` evaluates `$n` — the same price). */
export declare const VARIABLE_OPERAND_BUILTINS: ReadonlySet<string>;
/** Does this run of a variable-operand builtin evaluate an operand arithmetically? Linear in the words. */
export declare function evaluatesOperand(run: readonly {
readonly text: string;
readonly raw: string;
}[]): boolean;