@loophubs/agent-guard 0.2.0 → 0.4.0

package/src/rules/credentials.ts

@@ -1,230 +1,49 @@
-// Credential rules: keep credential files, environment and shell-variable
-// dumps, stored tokens and verbose HTTP traces out of what the model reads.
-// Clients that consume a credential file themselves (dotenvx, node --env-file,
-// ssh -i) are not readers and stay allowed.
-import { basename } from "node:path";
-
-import { absPath, isSensitive, isSensitiveRoot, sshPrivate, sshScopeDenied } from "../paths";
+// Credential rules: keep credential files and private keys out of what the
+// model reads. Clients the program table models as consuming a credential file
+// themselves (dotenvx, node --env-file, ssh -i) are not readers and stay
+// allowed; the guard does not control what they do with the contents.
+import { isSensitive, isSensitiveRoot, sshPrivate } from "../paths";
 import { reasons } from "../reasons";
-import type { Command, Request, Word } from "../record";
-
-const readerPrograms = new Set(
-  (
-    "cat head tail less more bat sed awk jq yq base64 xxd od strings diff openssl plutil cp tee tar source . sort " +
-    "uniq cut nl fold rev paste comm join iconv hexdump hd zcat gzcat bzcat xzcat ag ack"
-  ).split(" "),
-);
-const {
-  file: fileReason,
-  dump: dumpReason,
-  variable: varReason,
-  token: tokenReason,
-  keychain: keychainReason,
-  trace: traceReason,
-  upload: uploadReason,
-  ssh: sshReason,
-  grepSsh: grepSshReason,
-  hiddenSearch: hiddenSearchReason,
-} = reasons;
-
-const secretName = (name: string) => /TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL/.test(name.toUpperCase());
-
-export function credentialRules(req: Request): string[] {
-  const denials: string[] = [];
-  if (req.operation === "read" && isSensitive(req.target)) denials.push(fileReason);
-  if (req.operation === "write" && sshPrivate(req.target)) denials.push(sshReason);
-  if (req.operation === "search") {
-    if (isSensitiveRoot(req.searchRoot)) denials.push(fileReason);
-    // A positive glob selects files even past ignore rules.
-    if (req.glob && !req.glob.startsWith("!") && isSensitive(`${req.searchRoot}/${basename(req.glob)}`, true)) denials.push(fileReason);
-  }
-  for (const cmd of req.commands) denials.push(...credentialCommand(cmd, req.home));
-  for (const fragment of req.uninspectable) denials.push(...credentialSignatures(fragment));
-  return denials;
-}
-
-// The core runs this last: it follows symlinks, so it touches the filesystem.
-export function credentialFilesystemRules(req: Request): string[] {
-  if ((req.operation === "read" || req.operation === "write") && sshScopeDenied(req.target, req.home, false)) return [sshReason];
-  if (req.operation === "search" && sshScopeDenied(req.searchRoot, req.home, true)) return [grepSshReason];
-  for (const cmd of req.commands) {
-    for (const redirect of cmd.redirects) {
-      if ((redirect.direction === "in" || redirect.direction === "out") && redirect.target && sshScopeDenied(absPath(redirect.target, cmd.cwd, req.home), req.home, false)) return [sshReason];
-    }
-    if (cmd.program < 0) continue;
-    const name = basename(cmd.argv[cmd.program]!.text);
-    const readsPath = ["ls", "find", "tree", "rg", "grep", "ag", "ack", "fd"].includes(name);
-    if (!readsPath && !readerPrograms.has(name)) continue;
-    const words = cmd.argv.slice(cmd.program + 1);
-    // A search with no path operand reads the working directory.
-    const searches = ["rg", "ag", "ack"].includes(name) || (name === "grep" && cmd.flags.has("recursive"));
-    if (searches && !cmd.flags.has("help") && !words.some((word) => word.role === "path") && sshScopeDenied(cmd.cwd, req.home, true)) return [grepSshReason];
-    const filter = name === "jq" ? jqFilter(words) : undefined;
-    for (const word of words) {
-      if (word === filter) continue;
-      if (!["arg", "path", "patfile", "option:patfile"].includes(word.role) || word.value.startsWith("-")) continue;
-      if (sshScopeDenied(absPath(word.value, cmd.cwd, req.home, /^['"]/.test(word.raw)), req.home, false)) return [sshReason];
-    }
-  }
-  return [];
-}
-
-function credentialCommand(cmd: Command, home: string): string[] {
-  const denials: string[] = [];
-  const sensitive = (word: string, glob = false, quoted = false) => isSensitive(absPath(word, cmd.cwd, home, quoted), glob);
-  for (const r of cmd.redirects) if (r.direction === "in" && sensitive(r.target)) denials.push(fileReason);
-  if (cmd.program < 0) {
-    if (cmd.wrappers.at(-1) === "env" && !cmd.wrappers.includes("env-S")) denials.push(dumpReason);
-    return denials;
-  }
-  const program = cmd.argv[cmd.program]!.text;
-  const name = basename(program);
-  const words = cmd.argv.slice(cmd.program + 1);
-  const args = words.map((w) => w.text);
-  // Shell variables exist only in the shell, so a path or a wrapper that
-  // execs a program never reaches these builtins.
-  if (cmd.shell && !program.includes("/")) {
-    if (name === "export" && (!args.length || args.some((a) => /^-[^-]*p/.test(a)))) denials.push(dumpReason);
-    if (name === "set" && !args.length) denials.push(dumpReason);
-    if (name === "typeset" || name === "declare") {
-      if (!args.length || (args.length === 1 && /^-[^-]*[px]/.test(args[0]!))) denials.push(dumpReason);
-      for (const a of args) if (!a.startsWith("-") && !a.includes("=") && secretName(a)) denials.push(varReason);
-    }
-  }
-  let display = readerPrograms.has(name) || ["echo", "printf", "print"].includes(name);
-  const operands = args.filter((a) => !a.startsWith("-"));
-  switch (name) {
-    case "printenv":
-      if (!operands.length) denials.push(dumpReason);
-      for (const a of operands) if (secretName(a)) denials.push(varReason);
-      break;
-    case "echo":
-    case "printf":
-    case "print":
-      if (name !== "echo" && args[0] === "-v") display = false;
-      if (display && words.some((w) => w.vars.some(secretName))) denials.push(varReason);
-      break;
-    case "rg":
-    case "grep":
-    case "ag":
-    case "ack":
-      if (cmd.flags.has("help")) break;
-      if ((name === "grep" && cmd.flags.has("recursive")) || (["rg", "ag"].includes(name) && cmd.flags.has("hidden"))) denials.push(hiddenSearchReason);
-      for (const w of words) {
-        if (w.role === "path" && absPath(w.value, cmd.cwd, home, /^['"]/.test(w.raw)) === `${home}/.ssh`) denials.push(sshReason);
-      }
-      if (cmd.flags.has("files")) break;
-      // Search operands, pattern files and positive globs are read targets;
-      // the pattern is not.
-      for (const w of words) {
-        const quoted = /^['"]/.test(w.raw);
-        if (["path", "patfile", "option:patfile"].includes(w.role) && sensitive(w.value, w.globs, quoted)) denials.push(fileReason);
-        if (w.role === "path" && isSensitiveRoot(absPath(w.value, cmd.cwd, home, quoted))) denials.push(fileReason);
-        if (["glob", "option:glob"].includes(w.role) && sensitive(basename(w.value), true)) denials.push(fileReason);
-      }
-      break;
-    case "gh":
-      if (args[0] === "auth" && args[1] === "token") denials.push(tokenReason);
-      if (args[0] === "auth" && args[1] === "status" && ghShowsToken(args.slice(2))) denials.push(tokenReason);
-      break;
-    case "glab":
-      if (args[0] === "auth" && args[1] === "status" && args.some((a) => /^(--show-token|-[^-]*t)/.test(a))) denials.push(tokenReason);
-      break;
-    case "security":
-      if (args.includes("-w") || args.includes("-g")) denials.push(keychainReason);
-      break;
-    case "curl":
-      denials.push(...curlRules(args, sensitive));
-      break;
-    default:
-      if (!readerPrograms.has(name)) return denials;
-      const filter = name === "jq" ? jqFilter(words) : undefined;
-      for (const w of words) {
-        if (w === filter) continue;
-        const target = /^-.*=/s.test(w.text) ? w.text.slice(w.text.indexOf("=") + 1) : w.text;
-        if (target && !target.startsWith("-") && sensitive(target, w.globs, /^['"]/.test(w.raw))) denials.push(fileReason);
-      }
-  }
-  // A heredoc or here-string body is standard input the command prints.
-  if (display && cmd.redirects.some((r) => r.vars.some(secretName))) denials.push(varReason);
-  return denials;
-}
-
-function jqFilter(words: Word[]): Word | undefined {
-  if (words.some((word) => word.text === "-f" || word.text === "--from-file")) return undefined;
-  return words.find((word) => !word.text.startsWith("-"));
+import type { Request, Target } from "../record";
+import { sshScopeDenied } from "../ssh";
+import { secretReasons, secretSignatures } from "./secrets";
+
+const { file: fileReason, codeFile: codeFileReason, upload: uploadReason, ssh: sshReason, grepSsh: grepSshReason, hiddenSearch: hiddenSearchReason } = reasons;
+
+function targetReason(target: Target, home: string): string | undefined {
+  const reason = target.via === "code" ? codeFileReason : target.sends ? uploadReason : fileReason;
+  if (target.effect === "write") return sshPrivate(target.path) ? sshReason : undefined;
+  if (target.effect !== "read") return undefined;
+  if (target.walk === "hidden") return hiddenSearchReason;
+  // A directory that holds a listed file is read whole.
+  return isSensitive(target.path, target.glob) || (!target.glob && isSensitiveRoot(target.path, home)) ? reason : undefined;
 }
 
-// A token-display flag counts even when a later flag cancels it.
-function ghShowsToken(args: string[]): boolean {
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i]!;
-    if (a === "--") return false;
-    if (["--hostname", "--jq", "--json", "--template", "-h"].includes(a)) i++;
-    else if (a === "--show-token" || a.startsWith("--show-token=") || /^-[at]*t/.test(a)) return true;
-  }
-  return false;
-}
-
-// curl reads ~/.curlrc and may add credentials the command line never shows,
-// so any trace is denied; @file data and uploads name files it sends.
-function curlRules(args: string[], sensitive: (word: string) => boolean): string[] {
+export function credentialRules(req: Request, targets: Target[]): string[] {
   const denials: string[] = [];
-  const long = /^--(data|data-ascii|data-binary|data-urlencode|json|form|header|upload-file|config)(=|$)/s;
-  for (let i = 0; i < args.length; i++) {
-    const word = args[i]!;
-    let key = "";
-    let value = "";
-    if (word === "--") break;
-    if (/^file:\/\//i.test(word) && sensitive(word)) denials.push(fileReason);
-    if (/^--(verbose|trace|trace-ascii)(=|$)/.test(word)) denials.push(traceReason);
-    else if (long.test(word)) {
-      key = word.slice(2).split("=")[0]!;
-      value = word.includes("=") ? word.slice(word.indexOf("=") + 1) : (args[++i] ?? "");
-    } else if (/^-[^-]/.test(word)) {
-      for (let k = 1; k < word.length; k++) {
-        if (word[k] === "v") denials.push(traceReason);
-        if (!"AbcCdDeEFHKmoPQrTtuUwxXyYz".includes(word[k]!)) continue;
-        key = word[k]!;
-        value = word.slice(k + 1) || (args[++i] ?? "");
-        break;
-      }
+  const groups = Map.groupBy(targets, (target) => target.command);
+  const judge = (command: number) => {
+    for (const target of groups.get(command) ?? []) {
+      const reason = targetReason(target, req.home);
+      if (reason) denials.push(reason);
     }
-    if (key === "d" || key.startsWith("data") || key === "json" || key === "H" || key === "header") {
-      if (!/@./s.test(value)) continue;
-      value = value.slice(value.indexOf("@") + 1);
-    } else if (key === "F" || key === "form") {
-      value = value
-        .slice(value.indexOf("=") + 1)
-        .replace(/^[@<]/, "")
-        .split(";")[0]!;
-    } else if (!["T", "upload-file", "K", "config"].includes(key)) continue;
-    if (sensitive(value)) denials.push(uploadReason);
+  };
+  judge(-1);
+  for (const [i, cmd] of req.commands.entries()) {
+    judge(i);
+    denials.push(...secretReasons(cmd));
   }
+  for (const fragment of req.uninspectable) denials.push(...secretSignatures(fragment.text));
   return denials;
 }
 
-const readers = [...readerPrograms].filter((p) => p !== ".").join("|");
-const names = "\\.env(?:\\.[A-Za-z0-9_.-]+)?|\\.npmrc|\\.zsh_history|\\.zprofile|private-keys-v1\\.d|\\S*\\.(pem|key)|auth\\.json|\\.credentials\\.json|\\.aws/credentials|\\.ssh/\\S*";
-const readerSignature = new RegExp(`(^|[^A-Za-z0-9_])(${readers})([^A-Za-z0-9_-].*)?[\\s/"'=](${names})($|[\\s/"'>|&)\`])`, "s");
-
-// Text the front end could not structure: interpreter code, case bodies, or
-// source the parser rejects. Match the commands that would expose a credential.
-function credentialSignatures(fragment: string): string[] {
-  const denials: string[] = [];
-  for (const segment of fragment.replace(/&&|\|\||\n/g, ";").split(";")) {
-    if (
-      /(^|[^A-Za-z0-9_-])printenv([^A-Za-z0-9_-]|$)/.test(segment) ||
-      /(^|[|(])\s*(env|export|set|typeset|declare)\s*($|[|>)])/.test(segment) ||
-      /(declare|typeset|export)\s+-[a-z]*[px]/.test(segment)
-    )
-      denials.push(dumpReason);
-    const reader = segment.match(readerSignature);
-    if (reader) denials.push(fileReason);
-    if (/curl\s.*\s(-[A-Za-z]*v[A-Za-z]*|--verbose|--trace(-ascii)?)(\s|=|$)/s.test(segment)) denials.push(traceReason);
-    if (/gh\s+auth\s+token/.test(segment)) denials.push(tokenReason);
-    if (/security\s.*\s-[wg](\s|$)/s.test(segment)) denials.push(keychainReason);
-    if (/(ECHO|PRINTF|PRINT)\s.*\$\{?[A-Z0-9_]*(TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL)/s.test(segment.toUpperCase())) denials.push(varReason);
+// The core runs this last: it compares inodes, so it touches the filesystem.
+export function credentialFilesystemRules(req: Request, targets: Target[]): string[] {
+  for (const target of targets) {
+    if (!["read", "write", "list"].includes(target.effect) || target.via === "items" || (target.via === "tool" && target.glob)) continue;
+    // A working directory is checked only for a search that reads what is under it.
+    if ((target.via === "cwd" || target.via === "scan") && !target.search) continue;
+    if (sshScopeDenied(target.path, req.home, target.search)) return [target.search ? grepSshReason : sshReason];
   }
-  return denials;
+  return [];
 }

package/src/rules/secrets.ts

@@ -0,0 +1,143 @@
+// Secrets that print without a path: environment and variable dumps, stored
+// tokens, verbose HTTP traces. No target exists to check, so these name the
+// command that prints them. Each is a workaround that stays until the operating
+// system's read restrictions cover the store; do not extend the list.
+import { programName } from "../argv";
+import { curlValueLetters, readers } from "../programs";
+import { reasons } from "../reasons";
+import type { Command } from "../record";
+
+const { dump: dumpReason, variable: varReason, token: tokenReason, keychain: keychainReason, trace: traceReason, secretPrint: secretReason } = reasons;
+
+const secretName = (name: string) => /TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL/.test(name.toUpperCase());
+
+export function secretReasons(cmd: Command): string[] {
+  const denials: string[] = [];
+  if (cmd.program < 0) {
+    if (cmd.wrappers.at(-1) === "env" && !cmd.wrappers.includes("env-S")) denials.push(dumpReason);
+    return denials;
+  }
+  const program = cmd.argv[cmd.program]!.text;
+  const name = programName(program);
+  const words = cmd.argv.slice(cmd.program + 1);
+  const args = words.map((w) => w.text);
+  // Shell variables exist only in the shell, so a path or a wrapper that
+  // execs a program never reaches these builtins.
+  if (cmd.shell && !program.includes("/")) {
+    if (name === "export" && (!args.length || args.some((a) => /^-[^-]*p/.test(a)))) denials.push(dumpReason);
+    if (name === "set" && !args.length) denials.push(dumpReason);
+    if (name === "typeset" || name === "declare") {
+      if (!args.length || (args.length === 1 && /^-[^-]*[px]/.test(args[0]!))) denials.push(dumpReason);
+      for (const a of args) if (!a.startsWith("-") && !a.includes("=") && secretName(a)) denials.push(varReason);
+    }
+  }
+  let display = readers.includes(name) || ["echo", "printf", "print"].includes(name);
+  const operands = args.filter((a) => !a.startsWith("-"));
+  switch (name) {
+    case "printenv":
+      if (!operands.length) denials.push(dumpReason);
+      for (const a of operands) if (secretName(a)) denials.push(varReason);
+      break;
+    case "echo":
+    case "printf":
+    case "print":
+      if (name !== "echo" && args[0] === "-v") display = false;
+      if (display && words.some((w) => w.vars.some(secretName))) denials.push(varReason);
+      break;
+    case "gh":
+      if (args[0] === "auth" && args[1] === "token") denials.push(tokenReason);
+      if (args[0] === "auth" && args[1] === "status" && ghShowsToken(args.slice(2))) denials.push(tokenReason);
+      break;
+    case "glab":
+      if (args[0] === "auth" && args[1] === "status" && args.some((a) => /^(--show-token|-[^-]*t)/.test(a))) denials.push(tokenReason);
+      break;
+    case "security":
+      if (args.some((a) => /^-[A-Za-z]*[wg]/.test(a) && !a.startsWith("--")) || ["dump-keychain", "export"].includes(args[0] ?? "")) denials.push(keychainReason);
+      break;
+    case "gcloud":
+      if (args.includes("print-access-token") || args.includes("print-identity-token")) denials.push(secretReason);
+      break;
+    case "az":
+      if (args[0] === "account" && args[1] === "get-access-token") denials.push(secretReason);
+      break;
+    case "aws":
+      if (args[0] === "configure" && args[1] === "get" && secretName(args[2] ?? "")) denials.push(secretReason);
+      break;
+    case "npm":
+      if (args[0] === "config" && args[1] === "get" && /auth|token|password/i.test(args[2] ?? "")) denials.push(secretReason);
+      break;
+    case "kubectl":
+      if (args[0] === "config" && args[1] === "view" && args.includes("--raw")) denials.push(secretReason);
+      break;
+    case "gpg":
+      if (args.some((a) => /^--export-secret-(sub)?keys$/.test(a))) denials.push(secretReason);
+      break;
+    case "curl":
+      if (curlTraces(args)) denials.push(traceReason);
+      break;
+    case "git":
+      if (gitCredentialFill(args)) denials.push(secretReason);
+      break;
+  }
+  // A heredoc or here-string body is standard input the command prints.
+  if (display && cmd.redirects.some((r) => r.vars.some(secretName))) denials.push(varReason);
+  return denials;
+}
+
+// git credential fill prints the stored credential; the subcommand follows any global options.
+function gitCredentialFill(args: string[]): boolean {
+  let i = 0;
+  while (i < args.length && args[i]!.startsWith("-")) i += ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path"].includes(args[i]!) ? 2 : 1;
+  return args[i] === "credential" && args[i + 1] === "fill";
+}
+
+// A token-display flag counts even when a later flag cancels it.
+function ghShowsToken(args: string[]): boolean {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--") return false;
+    if (["--hostname", "--jq", "--json", "--template", "-h"].includes(a)) i++;
+    else if (a === "--show-token" || a.startsWith("--show-token=") || /^-[at]*t/.test(a)) return true;
+  }
+  return false;
+}
+
+// curl reads ~/.curlrc and may add credentials the command line never shows,
+// so any trace is denied. A value letter takes the rest of its cluster, so the
+// v in -uvictor:secret is part of a user name.
+function curlTraces(args: string[]): boolean {
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i]!;
+    if (word === "--") break;
+    if (/^--(verbose|trace|trace-ascii)(=|$)/.test(word)) return true;
+    // A separate value is not an option.
+    if (/^--(data|data-ascii|data-binary|data-urlencode|json|form|header|upload-file|config)$/.test(word)) i++;
+    if (!/^-[^-]/.test(word)) continue;
+    for (let k = 1; k < word.length; k++) {
+      if (word[k] === "v") return true;
+      if (!curlValueLetters.includes(word[k]!)) continue;
+      if (k === word.length - 1) i++;
+      break;
+    }
+  }
+  return false;
+}
+
+// Text the front end could not structure: interpreter code, case bodies, or
+// source the parser rejects. Match the commands that would expose a secret.
+export function secretSignatures(fragment: string): string[] {
+  const denials: string[] = [];
+  for (const segment of fragment.replace(/&&|\|\||\n/g, ";").split(";")) {
+    if (
+      /(^|[^A-Za-z0-9_-])printenv([^A-Za-z0-9_-]|$)/.test(segment) ||
+      /(^|[|(])\s*(env|export|set|typeset|declare)\s*($|[|>)])/.test(segment) ||
+      /(declare|typeset|export)\s+-[a-z]*[px]/.test(segment)
+    )
+      denials.push(dumpReason);
+    if (/curl\s.*\s(-[A-Za-z]*v[A-Za-z]*|--verbose|--trace(-ascii)?)(\s|=|$)/s.test(segment)) denials.push(traceReason);
+    if (/gh\s+auth\s+token/.test(segment)) denials.push(tokenReason);
+    if (/security\s.*\s-[wg](\s|$)/s.test(segment)) denials.push(keychainReason);
+    if (/(ECHO|PRINTF|PRINT)\s.*\$\{?[A-Z0-9_]*(TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL)/s.test(segment.toUpperCase())) denials.push(varReason);
+  }
+  return denials;
+}

package/src/search-roles.ts

@@ -1,5 +1,10 @@
 import type { Command, ValueRole, Word } from "./record";
 
+// fd and ls skip hidden files unless asked; find never does.
+export function showsHidden(words: Word[]): boolean {
+  return words.some((word) => /^(--hidden|--unrestricted)$/.test(word.text) || /^-[A-Za-z]*[Hu][A-Za-z]*$/.test(word.text));
+}
+
 const rgShortValues = "efgtTEABCmMjrd";
 const rgLongValues = new Set(
   (

package/src/search-targets.ts

@@ -0,0 +1,33 @@
+import { basename } from "node:path";
+
+import type { Context } from "./programs";
+import type { Effect, Target } from "./record";
+
+// rg, grep, ag and ack: the roles search-roles.ts gave the words say which are roots, pattern files and globs.
+export function searchTargets(name: string, { cmd, words, make, claimed }: Context): Target[] {
+  const help = cmd.flags.has("help");
+  const files = cmd.flags.has("files");
+  const recursive = name === "grep" && cmd.flags.has("recursive");
+  const walk = recursive || (["rg", "ag"].includes(name) && cmd.flags.has("hidden")) ? "hidden" : "visible";
+  // Listing names, or printing help, reads no content; a hidden listing feeds what reads it.
+  const effect: Effect = help || (files && walk !== "hidden") ? "list" : "read";
+  const targets: Target[] = [];
+  for (const [i, word] of words.entries()) {
+    // The file these options name holds ignore rules that the search reads.
+    const owner = word.role === "optarg" ? words[i - 1] : word.role === "option:optarg" ? word : undefined;
+    if (word.role === "path") targets.push(make(word.value, word, effect, { via: "operand", walk }));
+    else if (word.role === "patfile" || word.role === "option:patfile") targets.push(make(word.value, word, effect, { via: "option", walk: "none" }));
+    else if (owner && /^--(ignore-file|exclude-from)(=|$)/.test(owner.text)) targets.push(make(word.value, word, "read", { via: "option", walk: "none" }));
+    else continue;
+    claimed.add(word);
+  }
+  const scoped = targets.some((target) => target.via === "operand");
+  if (!scoped && (name !== "grep" || recursive)) targets.push(make(cmd.cwd, undefined, help ? "list" : effect, { via: name === "grep" ? "cwd" : "scan", walk, search: !help }));
+  for (const word of words) {
+    if (word.role !== "glob" && word.role !== "option:glob") continue;
+    claimed.add(word);
+    // A positive glob selects files even past ignore rules.
+    targets.push(make(basename(word.value), word, effect, { via: "option", glob: true, walk: "none" }));
+  }
+  return targets;
+}

package/src/ssh-targets.ts

@@ -0,0 +1,46 @@
+import type { Context } from "./programs";
+import type { Effect, Target } from "./record";
+
+// `-o KEY=VALUE`, `-o "KEY VALUE"` and `-oKEY=VALUE` set a client option; these keys name a file the client reads or writes.
+const sshFileOptions: Record<string, Effect> = { identityfile: "use", certificatefile: "use", globalknownhostsfile: "use", userknownhostsfile: "write", revokedhostkeys: "use", pkcs11provider: "use" };
+
+// The option letters that take a value, from each client's synopsis in the OpenSSH 10.3p1 manual page; the first one in a cluster takes the rest of the word or the next word.
+const valueLetters: Record<string, string> = { ssh: "BDEFIJLOPQRSWbceilmopw", scp: "DFJPSXcilo", sftp: "BDFJPRSXbcilos" };
+
+// The client uses the identity and configuration files itself (sftp passes them to ssh), and ssh writes its log file.
+const letterEffects: Record<string, Effect> = { i: "use", F: "use", E: "write" };
+
+// ssh reads options before and right after the destination, scp and sftp before their first operand; later words are the remote command or operands.
+export const sshTargets =
+  (client: "ssh" | "scp" | "sftp") =>
+  ({ words, make, claimed }: Context): Target[] => {
+    const targets: Target[] = [];
+    let operands = 0;
+    for (let i = 0; i < words.length; i++) {
+      const word = words[i]!;
+      if (word.text === "--") break;
+      if (!/^-./.test(word.text)) {
+        if (++operands === (client === "ssh" ? 2 : 1)) break;
+        continue;
+      }
+      const at = [...word.text.slice(1)].findIndex((letter) => valueLetters[client]!.includes(letter));
+      if (at < 0) continue;
+      const letter = word.text[at + 1]!;
+      const glued = word.text.slice(at + 2);
+      const holder = glued ? word : words[++i];
+      if (!holder) break;
+      const value = glued || holder.text;
+      let effect: Effect | undefined = client === "sftp" && letter === "b" && value !== "-" ? "read" : letterEffects[letter];
+      let paths = [value];
+      if (letter === "o") {
+        const setting = /^(\w+)(?:\s*=\s*|\s+)(.+)$/s.exec(value);
+        effect = sshFileOptions[setting?.[1]?.toLowerCase() ?? ""];
+        // ssh strips double quotes, takes several known-hosts files separated by spaces, and expands %d and ${HOME} to the home directory.
+        paths = (setting?.[2] ?? "").match(/"[^"]*"|\S+/g)?.map((path) => path.replace(/"/g, "").replace(/^(%d|\$\{HOME\})(?=\/|$)/, "~")) ?? [];
+      }
+      if (!effect) continue;
+      claimed.add(holder);
+      for (const path of paths) targets.push(make(path, holder, effect, { via: "option", ...(letter === "o" && { quoted: false }) }));
+    }
+    return targets;
+  };

package/src/ssh.ts

@@ -0,0 +1,65 @@
+import { basename, dirname } from "node:path";
+
+import { followLinks, notALink } from "./links";
+import { isAppdata, sshPublic } from "./paths";
+import { probes } from "./probes";
+
+// A path that does not exist has no inode to compare. Any other failure means the comparison did not run, so it propagates.
+function stat(path: string) {
+  try {
+    return probes.stat(path);
+  } catch (error) {
+    if (notALink.includes((error as NodeJS.ErrnoException).code ?? "")) return undefined;
+    throw error;
+  }
+}
+
+function sameFile(a: string, b: string): boolean {
+  if (a === b) return true;
+  const x = stat(a);
+  const y = stat(b);
+  return x !== undefined && y !== undefined && x.dev === y.dev && x.ino === y.ino;
+}
+
+function kind(path: string): "dir" | "file" | "other" {
+  const st = stat(path);
+  return st?.isDirectory() ? "dir" : st?.isFile() ? "file" : "other";
+}
+
+// Whether the spelling puts a path at or under `root`, or for a search above it. Case is ignored because the default APFS volume ignores it.
+function near(path: string, root: string, search: boolean): boolean {
+  const [spelled, base] = [path.toLowerCase().replace(/\/$/, "") || "/", root.toLowerCase()];
+  return spelled === base || spelled.startsWith(`${base}/`) || (search && (spelled === "/" || base.startsWith(`${spelled}/`)));
+}
+
+// Filesystem check for a file tool target, or a search root when search is set. It compares inodes so a case alias of ~/.ssh resolves to the
+// directory it names. Only a path whose spelling, or whose readlink-followed spelling, is already at or under ~/.ssh is compared: the inode
+// probes follow links, so a target that is not established to be in ~/.ssh scope is never handed to them. When ~/.ssh scope leads into App Data
+// the comparison is skipped and the target is denied, because stat would search that tree.
+export function sshScopeDenied(target: string, home: string, search: boolean): boolean {
+  const ssh = `${home}/.ssh`;
+  const appdataOnly = (path: string) => isAppdata(path, home);
+  const roots = [...new Set([ssh, followLinks(ssh, home, appdataOnly)])];
+  const candidates = [...new Set([target, followLinks(target, home, appdataOnly)])];
+  if (!candidates.some((candidate) => roots.some((root) => near(candidate, root, search)))) return false;
+  if ([...roots, ...candidates].some((path) => isAppdata(path, home))) return true;
+  for (const candidate of candidates) {
+    for (const root of roots) {
+      if (sameFile(candidate, root)) return true;
+      if (search) {
+        for (let parent = root; parent !== "/";) {
+          parent = dirname(parent);
+          if (sameFile(candidate, parent)) return true;
+        }
+      }
+      for (let parent = candidate; parent !== "/";) {
+        parent = dirname(parent);
+        if (!sameFile(parent, root)) continue;
+        if (parent !== dirname(candidate) || !sshPublic(basename(candidate))) return true;
+        if (kind(target) === "dir") return true;
+        if (search && kind(target) !== "file") return true;
+      }
+    }
+  }
+  return false;
+}