@goodandready/dsh-approval-gate 0.1.11 → 0.1.13

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,9 @@ 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",
     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 +67,11 @@ 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",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -89,12 +103,18 @@ export const MESSAGES = Object.freeze({
     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 +128,9 @@ export const MESSAGES = Object.freeze({
     rulePathTraversal: "检测到路径穿越攻击",
     ruleBandHardDeny: "命令匹配 Band 0 关键安全黑名单",
     ruleCircuitBreakerTripped: "因连续多次安全拒绝，断路熔断器已触发",
+    ruleSilentErrorMasked: "屏蔽错误输出或强制忽略退出码",
+    ruleChmodChown: "修改权限或所有权",
+    ruleReviewerReadOnly: "审查者代理处于只读隔离模式",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -115,63 +138,11 @@ export const MESSAGES = Object.freeze({
     hintCircuitBreakerTripped: "请在尝试新的系统命令前请求操作员人工授权",
     hintDestructiveSql: "请使用版本化数据库迁移，或执行非破坏性查询",
     hintCurlPipe: "先将脚本下载到本地检查内容，再安全执行",
-  },
-  ru: {
-    blockedPrefix: "Заблокировано правилом dsh-approval-gate",
-    detectedLabel: "Обнаружено",
-    commandLabel: "Команда",
-    parseReasonLabel: "Причина разбора",
-    hintPrefix: "Подсказка",
-    detailProcessSubstitution: "подстановка процесса требует подтверждения",
-    detailUnclosedProcessSubstitution: "незакрытая подстановка процесса",
-    detailUnclosedCommandSubstitution: "незакрытая подстановка команды",
-    detailUnclosedBacktick: "незакрытая подстановка в обратных кавычках",
-    detailUnclosedParameterExpansion: "незакрытое расширение параметра",
-    detailUnclosedSingleQuote: "незакрытая одинарная кавычка",
-    detailUnclosedDoubleQuote: "незакрытая двойная кавычка",
-    detailDanglingEscape: "незавершённое экранирование",
-    detailInvalidHeredoc: "неверный разделитель here-document",
-    detailUnterminatedHeredoc: "ограничитель here-document не найден",
-    detailUnsupportedGrouping: "группировка shell не поддерживается анализатором",
-    detailUnsupported: "неподдерживаемый синтаксис shell",
-    approvalRequired: "Требуется подтверждение",
-    askUnknown: "Команда не может быть проверена полностью; проверьте её перед подтверждением",
-    askUnparseable: "Синтаксис shell не может быть проверен полностью; проверьте его перед подтверждением",
-    askUnknownFormat: "Формат вызова инструмента не может быть проверен; проверьте его перед подтверждением",
-    askUnknownWriteTarget: "Цель записи файла не может быть определена; проверьте её перед подтверждением",
-    askDynamicCommand: "Развёрнутое имя команды не может быть проверено; проверьте его перед подтверждением",
-    askDynamicArguments: "Развёрнутые аргументы чувствительной команды не могут быть проверены; проверьте их перед подтверждением",
-    askDynamicRedirect: "Развёрнутая цель перенаправления не может быть проверена; проверьте её перед подтверждением",
-    askScriptFile: "Содержимое файла скрипта недоступно для гейта; проверьте его перед подтверждением",
-    askShellStdin: "Ввод шелла недоступен для гейта в полном объёме; проверьте его перед подтверждением",
-    askInterpreterPayload: "Побочные эффекты интерпретатора не могут быть полностью проанализированы; проверьте их перед подтверждением",
-    askCredentialInArgv: "Развёрнутые учётные данные передаются как аргументы процесса; используйте безопасный API или проверьте перед подтверждением",
-    ruleUnknown: "Сработало защитное правило блокировки",
-    ruleRecursiveRm: "Рекурсивное удаление файлов",
-    ruleProcessSignal: "Завершение процесса",
-    ruleServiceControl: "Изменение состояния службы",
-    ruleGitClean: "Разрушительный git clean",
-    ruleGitResetHard: "Разрушительный git reset --hard",
-    ruleFindDelete: "find -delete",
-    ruleDestructiveSql: "Разрушительный SQL",
-    ruleSecretWrite: "Запись в защищённый файл с секретами",
-    ruleDeviceWrite: "Запись в системное устройство или защищённый файл",
-    ruleMkfsDevice: "Форматирование файловой системы",
-    ruleCurlPipe: "Передача скачанного содержимого в шелл",
-    ruleEval: "Динамическое выполнение шелла (eval)",
-    ruleNestedShell: "Превышен лимит вложенности шелла",
-    ruleInterpreterPayload: "Небезопасный исполняемый код интерпретатора",
-    ruleEnvDumpLeak: "Попытка утечки переменных окружения и секретов",
-    rulePathTraversal: "Обнаружена попытка обхода каталогов (path traversal)",
-    ruleBandHardDeny: "Команда заблокирована критическим списком безопасности Band 0",
-    ruleCircuitBreakerTripped: "Предохранитель сессии сработал из-за повторяющихся блокировок",
-    hintRecursiveRm: "Указывайте конкретные файлы вместо рекурсивного удаления",
-    hintPathTraversal: "Ограничьте операции пределами рабочего каталога проекта",
-    hintSecretWrite: "Изменяйте настройки через UI или переменные окружения, не перезаписывайте секретные файлы напрямую",
-    hintEnvDumpLeak: "Запрашивайте конкретные несекретные переменные по отдельности",
-    hintCircuitBreakerTripped: "Запросите подтверждение оператора перед повторной отправкой системных команд",
-    hintDestructiveSql: "Используйте версионированные миграции или выполняйте неразрушающие запросы",
-    hintCurlPipe: "Скачайте скрипт локально, проверьте его содержимое и выполните безопасно",
+    hintGitForcePush: "请勿使用 force 参数推送分支，或与远程仓库管理员确认",
+    hintGitRemotePush: "推送前请核对目标分支与远程仓库地址",
+    hintSilentErrorMasked: "请保留标准错误输出，并明确处理非零退出码",
+    hintChmodChown: "避免直接修改系统目录所有权或文件权限",
+    hintReviewerReadOnly: "审查者代理仅可读取项目文件，禁止执行命令或修改文件",
   },
 });
 
@@ -211,6 +182,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",
@@ -224,6 +199,9 @@ 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",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -234,6 +212,11 @@ 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",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -247,6 +230,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({
@@ -288,4 +273,4 @@ export function askMessage(hit, who, translate, logger) {
   if (snippet) parts.push(translated(translate, "commandLabel", logger) + ": " + snippet);
   if (who) parts.push(who.trim());
   return parts.join(" — ") + ".";
-}
+}

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,
+  };
+}