@goodandready/dsh-approval-gate 0.1.12 → 0.1.14

package/lib/loopback.js

@@ -0,0 +1,85 @@
+// lib/loopback.js
+// Safe loopback bypass helper for 127.0.0.1 and localhost dev servers.
+// Resolves: #40
+
+/**
+ * Checks whether a hostname or IP string represents a local loopback interface.
+ *
+ * @param {string} host
+ * @returns {boolean}
+ */
+export function isLoopbackHost(host) {
+  if (typeof host !== "string" || !host.trim()) return false;
+  const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h === "127.0.0.1" || h === "0.0.0.0" || h === "::1" || h === "0:0:0:0:0:0:0:1") return true;
+
+  // 127.0.0.0/8 IPv4 loopback range
+  if (/^127(?:\.(?:25[0-5]|2[0-4]\d|[01]?\d\d?)){3}$/.test(h)) return true;
+
+  // IPv6 loopback variants (::ffff:127.x.x.x)
+  if (/^::ffff:127(?:\.(?:25[0-5]|2[0-4]\d|[01]?\d\d?)){3}$/i.test(h)) return true;
+
+  return false;
+}
+
+/**
+ * Checks whether a URL points to a loopback address.
+ *
+ * @param {string} targetUrl
+ * @returns {boolean}
+ */
+export function isLoopbackUrl(targetUrl) {
+  if (typeof targetUrl !== "string" || !targetUrl.trim()) return false;
+  try {
+    const parsed = new URL(targetUrl.includes("://") ? targetUrl : `http://${targetUrl}`);
+    return isLoopbackHost(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks whether an HTTP/network tool execution or command targets a loopback endpoint.
+ *
+ * @param {string[]} argv - Tokens of curl/wget or similar command
+ * @returns {{ isLoopback: boolean, host?: string, port?: string }}
+ */
+export function isLoopbackCommand(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return { isLoopback: false };
+  const cmd = argv[0].replace(/\\/g, "/").split("/").pop();
+
+  if (cmd !== "curl" && cmd !== "wget" && cmd !== "nc" && cmd !== "socat") {
+    return { isLoopback: false };
+  }
+
+  const urls = [];
+  for (let i = 1; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a.startsWith("-")) {
+      // Skip flags and their values if common
+      if ((a === "-u" || a === "-H" || a === "-d" || a === "--data" || a === "-o" || a === "-O") && i + 1 < argv.length) {
+        i += 1;
+      }
+      continue;
+    }
+    if (a.includes("localhost") || a.includes("127.0.0.1") || a.includes("::1") || a.includes("0.0.0.0") || a.startsWith("http://") || a.startsWith("https://")) {
+      urls.push(a);
+    }
+  }
+
+  if (urls.length === 0) return { isLoopback: false };
+
+  const allLoopback = urls.every((u) => isLoopbackUrl(u));
+  if (allLoopback) {
+    try {
+      const parsed = new URL(urls[0].includes("://") ? urls[0] : `http://${urls[0]}`);
+      return { isLoopback: true, host: parsed.hostname, port: parsed.port };
+    } catch {
+      return { isLoopback: true };
+    }
+  }
+
+  return { isLoopback: false };
+}

package/lib/messages.js

@@ -32,12 +32,18 @@ export const MESSAGES = Object.freeze({
     askShellStdin: "Shell input is not fully available to the guard; review it before allowing",
     askInterpreterPayload: "Interpreter side effects are not fully analyzed; review it before allowing",
     askCredentialInArgv: "Expanded authorization values become process arguments; use a credential-safe API helper or review before allowing",
+    askGitRemotePush: "Publishing commits to a remote repository via git push requires confirmation",
+    askSilentErrorMasked: "The command suppresses errors or masks non-zero exit codes; review before allowing",
     ruleUnknown: "A blocking safety rule matched",
     ruleRecursiveRm: "Recursive file deletion",
     ruleProcessSignal: "Process termination",
     ruleServiceControl: "Service state change",
     ruleGitClean: "Destructive git clean",
     ruleGitResetHard: "Destructive git reset --hard",
+    ruleGitForcePush: "Forceful git push",
+    ruleGitBranchForceDelete: "Forceful git branch deletion",
+    ruleGitCheckoutForce: "Forceful checkout discarding local modifications",
+    ruleGitRestoreWorktree: "Restoring working tree files discarding modifications",
     ruleFindDelete: "find -delete",
     ruleDestructiveSql: "Destructive SQL",
     ruleSecretWrite: "Write to a protected secret file",
@@ -51,6 +57,10 @@ export const MESSAGES = Object.freeze({
     rulePathTraversal: "Directory traversal attack detected",
     ruleBandHardDeny: "Command matched Band 0 critical security blocklist",
     ruleCircuitBreakerTripped: "Circuit breaker tripped due to repeated security denials",
+    ruleSilentErrorMasked: "Suppression of command failure or error stream",
+    ruleChmodChown: "Permission or ownership mutation",
+    ruleReviewerReadOnly: "Reviewer agent is strictly isolated in read-only mode",
+    ruleRetryExhaustion: "Exhausted repeated attempts to bypass safety gate",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -58,6 +68,12 @@ export const MESSAGES = Object.freeze({
     hintCircuitBreakerTripped: "Request manual operator approval before attempting new system commands",
     hintDestructiveSql: "Use migrations or execute non-destructive database operations",
     hintCurlPipe: "Download the script, inspect its content, and execute locally",
+    hintGitForcePush: "Push branch without force or check with remote administrator",
+    hintGitRemotePush: "Confirm remote target branch and repository before pushing",
+    hintSilentErrorMasked: "Allow standard error output to be captured and handle non-zero exit codes explicitly",
+    hintChmodChown: "Avoid modifying file permissions or system directory ownership directly",
+    hintReviewerReadOnly: "Reviewer agents may only read repository files, not run commands or modify files",
+    hintRetryExhaustion: "Repeated denials detected; manual operator intervention required",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -85,16 +101,22 @@ export const MESSAGES = Object.freeze({
     askDynamicCommand: "无法验证展开后的命令名；请在允许前进行审查",
     askDynamicArguments: "敏感命令的展开参数无法验证；请在允许前进行审查",
     askDynamicRedirect: "展开后的重定向目标无法验证；请在允许前进行审查",
-    askScriptFile: "卫兵无法获取脚本文件内容；请在允许前进行审查",
+    askScriptFile: "脚本文件内容不可见；请在允许前进行审查",
     askShellStdin: "卫兵无法完整获取 Shell 输入；请在允许前进行审查",
     askInterpreterPayload: "解释器副作用未完全分析；请在允许前进行审查",
     askCredentialInArgv: "展开后的授权凭据作为进程参数传递；请使用凭据安全的 API 辅助工具，或在允许前进行审查",
+    askGitRemotePush: "通过 git push 向远程仓库发布代码需要确认",
+    askSilentErrorMasked: "命令屏蔽了错误输出或强制将退出码设为 0；请在允许前审查",
     ruleUnknown: "命中阻止性安全规则",
     ruleRecursiveRm: "递归删除文件",
     ruleProcessSignal: "终止进程",
     ruleServiceControl: "更改服务状态",
     ruleGitClean: "破坏性 git clean",
     ruleGitResetHard: "破坏性 git reset --hard",
+    ruleGitForcePush: "强制 git push",
+    ruleGitBranchForceDelete: "强制删除 git 分支",
+    ruleGitCheckoutForce: "强制 checkout 丢弃本地修改",
+    ruleGitRestoreWorktree: "还原工作区文件并丢弃修改",
     ruleFindDelete: "find -delete",
     ruleDestructiveSql: "破坏性 SQL",
     ruleSecretWrite: "写入受保护的敏感文件",
@@ -108,6 +130,10 @@ export const MESSAGES = Object.freeze({
     rulePathTraversal: "检测到路径穿越攻击",
     ruleBandHardDeny: "命令匹配 Band 0 关键安全黑名单",
     ruleCircuitBreakerTripped: "因连续多次安全拒绝，断路熔断器已触发",
+    ruleSilentErrorMasked: "屏蔽错误输出或强制忽略退出码",
+    ruleChmodChown: "修改权限或所有权",
+    ruleReviewerReadOnly: "审查者代理处于只读隔离模式",
+    ruleRetryExhaustion: "多次尝试绕过安全网关已达上限",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -115,6 +141,12 @@ export const MESSAGES = Object.freeze({
     hintCircuitBreakerTripped: "请在尝试新的系统命令前请求操作员人工授权",
     hintDestructiveSql: "请使用版本化数据库迁移，或执行非破坏性查询",
     hintCurlPipe: "先将脚本下载到本地检查内容，再安全执行",
+    hintGitForcePush: "请勿使用 force 参数推送分支，或与远程仓库管理员确认",
+    hintGitRemotePush: "推送前请核对目标分支与远程仓库地址",
+    hintSilentErrorMasked: "请保留标准错误输出，并明确处理非零退出码",
+    hintChmodChown: "避免直接修改系统目录所有权或文件权限",
+    hintReviewerReadOnly: "审查者代理仅可读取项目文件，禁止执行命令或修改文件",
+    hintRetryExhaustion: "检测到重复拒绝；需要操作员手动介入",
   },
 });
 
@@ -154,6 +186,10 @@ const RULE_KEYS = Object.freeze({
   "service-control": "ruleServiceControl",
   "git-clean": "ruleGitClean",
   "git-reset-hard": "ruleGitResetHard",
+  "git-force-push": "ruleGitForcePush",
+  "git-branch-force-delete": "ruleGitBranchForceDelete",
+  "git-checkout-force": "ruleGitCheckoutForce",
+  "git-restore-worktree": "ruleGitRestoreWorktree",
   "find-delete": "ruleFindDelete",
   "destructive-sql": "ruleDestructiveSql",
   "secret-write": "ruleSecretWrite",
@@ -167,6 +203,10 @@ const RULE_KEYS = Object.freeze({
   "path-traversal": "rulePathTraversal",
   "band-hard-deny": "ruleBandHardDeny",
   "circuit-breaker-tripped": "ruleCircuitBreakerTripped",
+  "silent-error-masked": "ruleSilentErrorMasked",
+  "chmod-chown": "ruleChmodChown",
+  "reviewer-read-only": "ruleReviewerReadOnly",
+  "retry-exhaustion": "ruleRetryExhaustion",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -177,6 +217,12 @@ const HINT_KEYS = Object.freeze({
   "circuit-breaker-tripped": "hintCircuitBreakerTripped",
   "destructive-sql": "hintDestructiveSql",
   "curl-pipe": "hintCurlPipe",
+  "git-force-push": "hintGitForcePush",
+  "git-remote-push": "hintGitRemotePush",
+  "silent-error-masked": "hintSilentErrorMasked",
+  "chmod-chown": "hintChmodChown",
+  "reviewer-read-only": "hintReviewerReadOnly",
+  "retry-exhaustion": "hintRetryExhaustion",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -190,6 +236,8 @@ const ASK_KEYS = Object.freeze({
   "shell-stdin": "askShellStdin",
   "interpreter-payload": "askInterpreterPayload",
   "credential-in-argv": "askCredentialInArgv",
+  "git-remote-push": "askGitRemotePush",
+  "silent-error-masked": "askSilentErrorMasked",
 });
 
 const DETAIL_KEYS = Object.freeze({

package/lib/parsers/git.js

@@ -0,0 +1,321 @@
+// lib/parsers/git.js
+// Specialized Git AST and semantics parser with classification of read, local mutation,
+// remote operations, and destructive commands.
+// Resolves: #125, #103
+
+export const GIT_CATEGORY_READ = "read";
+export const GIT_CATEGORY_MUTATE_LOCAL = "mutate_local";
+export const GIT_CATEGORY_REMOTE = "remote";
+export const GIT_CATEGORY_DESTRUCTIVE = "destructive";
+
+const GLOBAL_FLAGS_WITH_VALUE = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+  "--super-prefix",
+  "--config-env",
+]);
+
+const READ_ONLY_VERBS = new Set([
+  "status",
+  "log",
+  "diff",
+  "show",
+  "rev-parse",
+  "describe",
+  "cat-file",
+  "ls-files",
+  "ls-tree",
+  "shortlog",
+  "blame",
+  "check-ignore",
+  "check-ref-format",
+  "var",
+  "version",
+  "help",
+  "symbolic-ref",
+  "name-rev",
+  "merge-base",
+  "count-objects",
+  "diff-index",
+  "diff-tree",
+  "for-each-ref",
+  "rev-list",
+]);
+
+const LOCAL_MUTATE_VERBS = new Set([
+  "add",
+  "commit",
+  "checkout",
+  "switch",
+  "branch",
+  "tag",
+  "stash",
+  "merge",
+  "rebase",
+  "cherry-pick",
+  "revert",
+  "mv",
+  "rm",
+  "init",
+  "apply",
+  "am",
+]);
+
+const REMOTE_VERBS = new Set([
+  "push",
+  "pull",
+  "fetch",
+  "clone",
+  "remote",
+  "submodule",
+]);
+
+/**
+ * Extracts global git options and isolates the git subcommand verb and its arguments.
+ *
+ * @param {string[]} argv - Array of tokens starting with 'git' or the first flag/verb.
+ * @returns {{ verb: string, args: string[], globalOptions: Record<string, string>, rawArgv: string[] }}
+ */
+export function parseGitArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return { verb: "", args: [], globalOptions: {}, rawArgv: [] };
+  }
+
+  const rawArgv = [...argv];
+  let idx = rawArgv[0] === "git" ? 1 : 0;
+  const globalOptions = {};
+
+  while (idx < rawArgv.length && rawArgv[idx].startsWith("-")) {
+    const flag = rawArgv[idx];
+    if (flag === "--") {
+      idx += 1;
+      break;
+    }
+    if (GLOBAL_FLAGS_WITH_VALUE.has(flag)) {
+      globalOptions[flag] = rawArgv[idx + 1] || "";
+      idx += 2;
+    } else if (flag.startsWith("--") && flag.includes("=")) {
+      const eqIdx = flag.indexOf("=");
+      globalOptions[flag.slice(0, eqIdx)] = flag.slice(eqIdx + 1);
+      idx += 1;
+    } else if (flag.length > 2 && flag[1] !== "-" && flag.startsWith("-C")) {
+      globalOptions["-C"] = flag.slice(2);
+      idx += 1;
+    } else {
+      globalOptions[flag] = "true";
+      idx += 1;
+    }
+  }
+
+  const verb = rawArgv[idx] || "";
+  const args = rawArgv.slice(idx + 1);
+
+  return { verb, args, globalOptions, rawArgv };
+}
+
+/**
+ * Checks whether an argument contains a specific short flag (e.g. 'f' in '-fdx').
+ *
+ * @param {string[]} args
+ * @param {string} flagChar
+ * @returns {boolean}
+ */
+function hasShortFlag(args, flagChar) {
+  for (const a of args) {
+    if (a === "--") break;
+    if (a.length > 1 && a[0] === "-" && a[1] !== "-" && a.includes(flagChar)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Analyzes and classifies a git subcommand and its arguments.
+ *
+ * @param {string} verb
+ * @param {string[]} args
+ * @returns {{
+ *   verb: string,
+ *   category: "read" | "mutate_local" | "remote" | "destructive",
+ *   isDestructive: boolean,
+ *   isRemote: boolean,
+ *   isForce: boolean,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function classifyGitOperation(verb, args = []) {
+  if (!verb) {
+    return {
+      verb: "",
+      category: GIT_CATEGORY_READ,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  const subArgs = Array.isArray(args) ? args : [];
+
+  // 1. Destructive operations check
+  if (verb === "reset" && subArgs.includes("--hard")) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-reset-hard",
+      detail: "Destructive git reset --hard discards all uncommitted modifications",
+    };
+  }
+
+  if (verb === "clean" && (subArgs.includes("-f") || subArgs.includes("--force") || hasShortFlag(subArgs, "f"))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-clean",
+      detail: "Destructive git clean removes untracked files irreversibly",
+    };
+  }
+
+  if (verb === "branch" && (subArgs.includes("-D") || (subArgs.includes("-d") && (subArgs.includes("-f") || subArgs.includes("--force"))))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-branch-force-delete",
+      detail: "Forceful git branch deletion (-D) risks losing unmerged commits",
+    };
+  }
+
+  // 2. Remote operations (#103: git push vs local git operations)
+  if (verb === "push") {
+    const isForce = subArgs.some((a) => (
+      a === "--force" ||
+      a === "-f" ||
+      a.startsWith("--force-with-lease") ||
+      a === "--delete" ||
+      (a[0] === "+" && a.length > 1)
+    )) || hasShortFlag(subArgs, "f");
+
+    if (isForce) {
+      return {
+        verb,
+        category: GIT_CATEGORY_DESTRUCTIVE,
+        isDestructive: true,
+        isRemote: true,
+        isForce: true,
+        reason: "git-force-push",
+        detail: "Forceful git push overwrites remote repository commit history",
+      };
+    }
+
+    return {
+      verb,
+      category: GIT_CATEGORY_REMOTE,
+      isDestructive: false,
+      isRemote: true,
+      isForce: false,
+      reason: "git-remote-push",
+      detail: "Publishing commits to a remote repository via git push requires confirmation",
+    };
+  }
+
+  if (verb === "checkout" && (subArgs.includes("-f") || subArgs.includes("--force") || (subArgs.includes("--") && subArgs.includes(".")))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-checkout-force",
+      detail: "Forceful checkout discards local working tree changes",
+    };
+  }
+
+  if (verb === "restore" && subArgs.includes("--worktree") && (subArgs.includes(".") || subArgs.includes("--staged"))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-restore-worktree",
+      detail: "Restoring working tree files discards local changes",
+    };
+  }
+
+  if (REMOTE_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_REMOTE,
+      isDestructive: false,
+      isRemote: true,
+      isForce: false,
+    };
+  }
+
+  if (LOCAL_MUTATE_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_MUTATE_LOCAL,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  if (READ_ONLY_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_READ,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  return {
+    verb,
+    category: GIT_CATEGORY_MUTATE_LOCAL,
+    isDestructive: false,
+    isRemote: false,
+    isForce: false,
+  };
+}
+
+/**
+ * Full inspection of a git command invocation.
+ *
+ * @param {string[]} argv - Tokenized arguments
+ * @returns {{
+ *   verb: string,
+ *   args: string[],
+ *   category: "read" | "mutate_local" | "remote" | "destructive",
+ *   isDestructive: boolean,
+ *   isRemote: boolean,
+ *   isForce: boolean,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function inspectGitCommand(argv) {
+  const parsed = parseGitArgv(argv);
+  const classification = classifyGitOperation(parsed.verb, parsed.args);
+  return {
+    ...classification,
+    args: parsed.args,
+    globalOptions: parsed.globalOptions,
+  };
+}