@cfitsec/dsh-ast-guard 0.0.0-stage → 2.0.1

package/rules/default.yaml

@@ -0,0 +1,210 @@
+# dsh-ast-guard · 默认规则
+#
+# 重点在前两组：
+#   ① 写文件内容（Set-Content / Add-Content / Clear-Content / Out-File / Tee-Object / Export-* / .NET 直写 / 重定向）
+#   ② 条目操作（Remove / Move / Rename / Copy-Item…）
+# 它们共同的特点是：**不可逆，而且 shell 里做完全不留痕** —— 没有 diff、没有快照、进不了回退。
+# 其余（内联代码、注册表、git 范围收缩）都是同一类"代价高、事后查不到"的动作。
+#
+# 判断方式：**按效应，不按命令名**。每条规则的 `why` 会逐字出现在拒绝文案里。
+# 想改成自己的一套：复制本文件，然后在插件配置里用 `rulesFile` 指过去。
+#
+# ⚠️ 别名必须逐条写死：语法树**不解析别名**（`sc` 就只是 `sc`，认不出它是 Set-Content）。
+#    本文件的别名取自本机 PowerShell 的 `Get-Alias` 实测，换机器请自己核一遍。
+version: 1
+
+deny:
+  # ── ① 写文件内容：命令词 + 别名 + .NET 直写 + 重定向 ───────────────────────
+  - id: content-write
+    why: |
+      PowerShell 写文件内容已禁用：会破坏编码（Get-Content 默认非 UTF-8，来回一趟毁中文），
+      而且 shell 写入没有 diff、没有快照、进不了回退。
+      正确姿势：定点替换用 edit；整份新写用 write；复制/搬运用 Copy-Item（纯字节搬运，不经过解码）。
+    commands:
+      - Set-Content        # sc
+      - Add-Content        # ac
+      - Clear-Content      # clc
+      - Out-File           # 无别名
+      - Tee-Object         # tee
+      - Export-Csv         # epcsv
+      - Export-Clixml      # 无别名
+      - Start-Transcript   # 无别名
+      - sc
+      - ac
+      - clc
+      - tee
+      - epcsv
+    # .NET 直写。名字本身不专指文件（RunspaceFactory::Create 也是 Create），
+    # 所以还要求调用目标里含 File 或 Stream 才算。
+    memberTargetContains: ['File', 'Stream']
+    memberNames:
+      - WriteAllText
+      - WriteAllBytes
+      - WriteAllLines
+      - AppendAllText
+      - AppendAllLines
+      - Create
+      - CreateText
+      - OpenWrite
+      - OpenText
+      - new
+    # 文件重定向 `>` / `>>`；目标是 $null 的自动豁免（那是抑制输出，不是写文件）。
+    redirects: true
+
+  # ── ② 内联代码：解释器 + 求值开关 ─────────────────────────────────────────
+  #
+  # ⚠️ 为什么不合并成一条：**同一个开关在不同解释器上含义不同**。
+  #    `python -c` = 跑代码（该拦）；`node -c` = 语法检查（正当，必须放行）。
+  - id: inline-code-node
+    why: |
+      内联代码执行已禁用（`node -e` / `deno eval` 这类"把代码塞进参数"的写法）。
+      代码不在文件系统里：事后没人看得到它改了什么，也没有 diff 可回退。
+      正确姿势：把脚本落到文件里再跑（可审、可回滚）。
+    commands: [node, node.exe, deno, deno.exe, bun, bun.exe]
+    when:
+      flags: ['-e', '-p', '--eval', '--print']
+      argsExact: ['eval']
+
+  - id: inline-code-interp
+    why: |
+      内联代码执行已禁用（`python -c` / `powershell -Command` / `-EncodedCommand` 这类写法）。
+      正确姿势：把脚本落到文件里再跑。
+    commands: [python, python3, python.exe, python3.exe, py, powershell, powershell.exe, pwsh, pwsh.exe]
+    when:
+      # `-c` 只在这一条里（对 python / powershell 是"跑代码"；对 node 是语法检查）。
+      flags: ['-c', '-Co', '-Command', '-EncodedCommand', '-EncodedArguments', '-Enc']
+
+  # ── ②b 字符串里的写命令：`iex "Set-Content …"` 这类 ───────────────────────
+  #    语法树看得见 `iex` 这个命令节点，但**看不见字符串里的代码** —— 只能按参数子串兜一层。
+  #    这条同时演示 `argsContain` 维度（参数里**含**这串就算）。
+  - id: encoded-write
+    why: |
+      检测到用 Invoke-Expression 执行写入命令。**请直接用 edit 或 write 工具。**
+      代码在字符串里：事后没人看得到它改了什么，也没有 diff、没有快照、进不了回退。
+      （这条按参数子串判，所以只覆盖下面点名的写动词 —— 覆盖不全是有意的：
+       真正的兜底是"写内容一律走 edit / write"，不是把所有写动词列全。）
+    commands: [invoke-expression, iex]
+    when:
+      argsContain: ['set-content', 'add-content', 'out-file']
+
+  # ── ③ 凭据文件：只看工具参数里的**路径**，不碰正文 ────────────────────────
+  #    这一支不经过 shell。所以在文件正文里"提到"这些名字是正当的，不算写它们。
+  - id: credentials-readonly
+    why: |
+      这些是凭据落点：写它们等于把凭据暴露或毁掉。
+      正确姿势：凭据配在环境变量或专门的凭据存储里；要动先 Copy-Item 备份到临时位置。
+    tools: [edit, write]
+    paths: ['.npmrc', '.credentials', '.netrc', 'id_rsa', 'id_ed25519', 'id_ecdsa']
+
+  # ── ④ 受保护目录：**删除/改名** 与 路径 同时命中才拦（读与列举不受影响）────
+  - id: protected-path
+    why: |
+      这些目录被删或改名之后，行为差异要到下次运行才暴露（依赖、版本历史、钩子都在里面）。
+      读取与列举不受限制。
+    commands: [Remove-Item, ri, rm, del, erase, rd, rmdir, Clear-Content, Move-Item, mi, move, mv, Rename-Item, ren, rni]
+    paths: ['.git', 'node_modules']
+
+deliberate:
+  # ── ⑤ 删除：三思（受保护位置 / 递归 / 通配 / 强制，任一命中就停）──────────
+  - id: destructive-delete
+    cooldownSeconds: 10
+    why: |
+      删除不可逆：shell 删除没有回收站、没有 diff、进不了回退。
+      更便宜的做法：先 Copy-Item 备份；或别删只挪（Move-Item 到散放区，可逆）。
+    commands: [Remove-Item, del, erase, rd, ri, rm, rmdir, Clear-Item, cli]
+    when:
+      flags: ['-recurse', '-force']
+      wildcard: true
+      paths: ['.git', 'node_modules', '.ssh', '.aws', '.kube', '.env', 'src', 'docs']
+
+  # ── ⑥ 移动 / 改名到已存在的目标 = 覆盖 ───────────────────────────────────
+  - id: destructive-move
+    cooldownSeconds: 10
+    why: |
+      移动 / 改名到**已存在的目标**上就是覆盖 —— 和删除一样不可逆。
+      （实测：不加 -Force 时 Move-Item / Rename-Item 会报 "Cannot create a file when that file
+      already exists."，所以 **-Force 正好就是"允许覆盖"那一档**。）
+    commands: [Move-Item, mi, move, mv, Rename-Item, ren, rni]
+    when:
+      flags: ['-force']
+      wildcard: true
+      paths: ['.git', 'node_modules', '.ssh', '.aws', '.kube', '.env', 'src', 'docs']
+
+  # Copy-Item -Force 到已存在目标也是覆盖，但**默认不拦** ——
+  # 它是"先备份"那条建议用的动作；把备份也停下，等于罚自己推荐的做法。
+  # 想拦就取消注释；注意它会把"覆盖旧备份"一起停下。
+  # - id: destructive-copy-overwrite
+  #   cooldownSeconds: 10
+  #   commands: [Copy-Item, cp, copy, cpi]
+  #   when:
+  #     flags: ['-force']
+
+  # ── ⑦ 注册表增删改（读不受限）───────────────────────────────────────────
+  #
+  # ⚠️ 为什么拆成两条：`reg` 的子命令在**第一个位置参数**上；而 `*-ItemProperty` 这类 cmdlet
+  #    的第一个位置参数是**路径**，根本没有"子命令"这一维 —— 塞进同一条 `when.all`
+  #    会让 cmdlet 那一半永远不命中（2026-10-27 冒烟测试发现）。
+  - id: registry-write
+    cooldownSeconds: 10
+    why: |
+      注册表增删改的代价高：改错会影响整机行为，而且没有 diff、没有回退。
+      **读不受限**（reg query / Get-ItemProperty 都可以）。
+    commands: [reg, reg.exe]
+    when:
+      all:
+        - subcommands: [add, delete, import, restore, copy, load, unload]
+        - paths: ['HKCU', 'HKLM', 'HKCR', 'HKU', 'HKCC']
+
+  - id: registry-write-cmdlet
+    cooldownSeconds: 10
+    why: |
+      同上：这些 cmdlet 直接改注册表项 / 值。**读不受限**（Get-ItemProperty / Get-Item 都可以）。
+    commands:
+      - New-ItemProperty
+      - Set-ItemProperty
+      - Remove-ItemProperty
+      - Clear-ItemProperty
+      - Rename-ItemProperty
+      - Copy-ItemProperty
+      - Move-ItemProperty
+      - New-Item
+      - Remove-Item
+      - Rename-Item
+      - Move-Item
+      - Clear-Item
+      - ni
+      - sp
+      - rp
+      - clp
+      - rnp
+      - cpp
+      - mp
+      - del
+      - erase
+      - rd
+      - ri
+      - rm
+      - rmdir
+      - cli
+    when:
+      paths: ['HKCU', 'HKLM', 'HKCR', 'HKU', 'HKCC']
+
+  # ── ⑧ git 的范围收缩：会把工作区内容丢掉 ─────────────────────────────────
+  - id: destructive-git
+    cooldownSeconds: 10
+    why: |
+      git 的范围收缩子命令会把工作区的内容丢掉，而**未提交的部分不进 reflog** ——
+      reflog 只记 HEAD 移动过的东西，对"从未提交的文件"没有任何记录。
+      想看清楚再动（都只读）：git status --short / git diff --stat / git stash list。
+    commands: [git, git.exe]
+    when:
+      all:
+        - subcommands: [checkout, restore, reset, clean, stash, branch, push]
+        - argsExact: ['.', 'drop', 'clear']
+          wildcard: true
+          flags: ['--hard', '--force', '-f', '-fd', '-fdx', '-d', '-D', '--delete']
+    # 进冷却之前跑这些**只读**探针，把"这条命令会丢什么"现算出来放进窗口。
+    evidence:
+      - git status --porcelain
+      - git diff --shortstat HEAD
+      - git ls-files --others --exclude-standard

package/test/hook.mjs

@@ -0,0 +1,96 @@
+// 插件级集成测试：走**真的 apply()**（假 ctx），而不是直接调 evaluate()。
+//
+// 为什么需要它：smoke.mjs 只验"裁决引擎"—— 它直接调 evaluate()，绕过了插件的真正入口：
+//   apply() → ctx.on('tools/pre-execute') → check(exec)
+// 那一层会漏掉的东西：规则文件的加载与 mtime 缓存、非 shell 分支、规则读坏时的 fail-closed、
+// 拒绝文案的组装、三思窗口的生成、钩子与工具的注册。
+//
+// 仍然**不启动宿主、不注册真实钩子**（假 ctx 只把注册记下来），也**不执行任何被测命令**。
+//
+// 用法：node test/hook.mjs
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const RULES = path.join(here, '..', 'rules', 'default.yaml')
+const entry = new URL(`file://${path.join(here, '..', 'lib', 'index.js').replaceAll('\\', '/')}`)
+const mod = await import(entry)
+
+let bad = 0
+function check(label, want, got) {
+  const ok = JSON.stringify(got) === JSON.stringify(want)
+  if (!ok) bad++
+  console.log(`${ok ? '  ✅' : '  ❌'} 期望=${JSON.stringify(want).padEnd(18)} 实际=${JSON.stringify(got).padEnd(18)} ${label}`)
+}
+
+// ── 假 ctx：只记录注册，不接事件总线 ─────────────────────────────────────
+function makeCtx() {
+  const captured = { hooks: new Map(), tools: [] }
+  const ctx = {
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+    on(event, handler) { captured.hooks.set(event, handler) },
+    tools: { register(tool) { captured.tools.push(tool) } },
+  }
+  return { ctx, captured }
+}
+
+const { ctx, captured } = makeCtx()
+mod.apply(ctx, { rulesFile: RULES, timeoutMs: 15000 })
+
+const hook = captured.hooks.get('tools/pre-execute')
+check('注册了 tools/pre-execute', 'function', typeof hook)
+check('注册了 ast_confirm', true, captured.tools.some((tool) => tool.name === 'ast_confirm'))
+
+// 假 exec：形状照宿主给的那份（name / arguments / agent.session.header.cwd）
+const exec = (name, args) => ({
+  name,
+  arguments: args,
+  agent: { session: { header: { cwd: here, id: 'hook-test' } } },
+})
+const next = async () => ({ kind: 'allow' })
+const decide = async (name, args) => hook(exec(name, args), next)
+
+// ① shell + 写内容 ⇒ 拒，且文案里带规则 id（证明走到 buildDenialMessage）
+const d1 = await decide('pwsh', { command: 'Set-Content -Path x.txt -Value y' })
+check('Set-Content ⇒ kind', 'deny', d1 && d1.kind)
+check('Set-Content ⇒ 文案带 id', true, String(d1 && d1.reason).includes('content-write'))
+
+// ② shell + 只读 ⇒ 交给下游（本层返回 next() 的结果）
+const d2 = await decide('pwsh', { command: 'Get-Content x.txt -TotalCount 3' })
+check('只读 ⇒ 下游', 'allow', d2 && d2.kind)
+
+// ③ 非 shell 分支：写凭据文件 ⇒ 拒（这一支不经过解析器）
+const d3 = await decide('write', { file_path: '.npmrc', content: 'x' })
+check('write .npmrc ⇒ kind', 'deny', d3 && d3.kind)
+check('write .npmrc ⇒ 文案带 id', true, String(d3 && d3.reason).includes('credentials-readonly'))
+
+// ④ 非 shell + 正文提到凭据文件名 ⇒ 放行（只比路径参数）
+const d4 = await decide('write', { file_path: 'notes.md', content: '改 .npmrc 之前先备份' })
+check('正文提到 ⇒ 下游', 'allow', d4 && d4.kind)
+
+// ⑤ 三思：递归删除 ⇒ 拒，且文案是"冷却窗口"那一套（不是直接拒绝）
+const d5 = await decide('pwsh', { command: 'Remove-Item .\\src\\a -Recurse' })
+check('递归删除 ⇒ kind', 'deny', d5 && d5.kind)
+check('递归删除 ⇒ 冷却窗口文案', true, String(d5 && d5.reason).includes('冷却'))
+
+// ⑥ 规则文件读坏 ⇒ fail-closed（拒绝并说明怎么修），不是静默放行
+const brokenDir = mkdtempSync(path.join(tmpdir(), 'ast-guard-broken-'))
+const broken = path.join(brokenDir, 'rules.yaml')
+writeFileSync(broken, 'deny:\n  - id: [这不是合法的规则结构\n', 'utf8')
+const second = makeCtx()
+mod.apply(second.ctx, { rulesFile: broken, timeoutMs: 15000 })
+const hook2 = second.captured.hooks.get('tools/pre-execute')
+const d6 = await hook2(exec('pwsh', { command: 'Get-ChildItem .' }), next)
+check('规则读坏 ⇒ kind', 'deny', d6 && d6.kind)
+check('规则读坏 ⇒ 说明怎么修', true, String(d6 && d6.reason).includes('规则'))
+
+console.log('')
+const total = 12
+if (bad === 0) {
+  console.log(`插件级集成测试全部通过（${total} 条；走真的 apply()，假 ctx，不执行任何命令）`)
+  process.exit(0)
+}
+console.log(`${bad} 条不符`)
+process.exit(1)

package/test/import-check.mjs

@@ -0,0 +1,31 @@
+// 装载自检：只 import 插件的入口模块，**不启动**、不注册钩子。
+// 目的：在动 profile 配置之前，先确认"这个包能不能被 require 进来"——
+// 缺文件、写错路径、语法错误，都会在这一步炸，而不是等重启之后才发现守卫没装上。
+//
+// 用法：node test/import-check.mjs
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const entry = path.join(here, '..', 'lib', 'index.js')
+
+let mod
+try {
+  mod = await import(new URL(`file://${entry.replaceAll('\\', '/')}`))
+} catch (error) {
+  console.error('✗ 入口模块 import 失败：' + error.message)
+  process.exit(1)
+}
+
+const problems = []
+if (typeof mod.apply !== 'function') problems.push('没有导出 apply(ctx, config)')
+if (typeof mod.name !== 'string' || mod.name === '') problems.push('没有导出 name')
+if (!Array.isArray(mod.inject)) problems.push('没有导出 inject（数组）')
+
+if (problems.length > 0) {
+  console.error('✗ 入口导出不对：\n  - ' + problems.join('\n  - '))
+  process.exit(1)
+}
+
+console.log(`✓ 入口可装载：name=${mod.name}  inject=[${mod.inject.join(', ')}]`)
+process.exit(0)

package/test/smoke.mjs

@@ -0,0 +1,109 @@
+// 冒烟测试 —— **全程 dry-run**：只判"裁决"，不执行任何被测命令。
+//
+// 三件事：① 编译 rules/default.yaml（走真的编译链）② 喂命令文本给常驻解析器（只解析，不执行）
+// ③ 断言裁决结果。不联网、不需要 git、不写任何文件。
+//
+// 用法：node test/smoke.mjs      （或 npm test）
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const RULES = path.join(here, '..', 'rules', 'default.yaml')
+
+const { AstDaemon } = await import('../lib/daemon.js')
+const { parseRulesFile, evaluate, evaluateToolParams } = await import('../lib/rules.js')
+const { DeliberateDesk } = await import('../lib/deliberate.js')
+
+let bad = 0
+function check(label, want, got) {
+  const ok = got === want
+  if (!ok) bad++
+  console.log(`${ok ? '  ✅' : '  ❌'} 期望=${String(want ?? 'pass').padEnd(22)} 实际=${String(got ?? 'pass').padEnd(22)} ${label}`)
+}
+
+const rules = await parseRulesFile(RULES)
+console.log(`规则已编译：deny ${rules.deny.length} 条 · deliberate ${rules.deliberate.length} 条`)
+
+const daemon = new AstDaemon({
+  timeoutMs: 15000,
+  logger: { info: () => {}, warn: () => {}, error: () => {} },
+})
+await daemon.start()
+
+// ── ① 写文件内容（这套东西的重点交付物）────────────────────────────────────
+const writeCases = [
+  ['命令词 Set-Content', 'Set-Content -Path x.txt -Value y', 'content-write'],
+  ['别名 sc', 'sc -Path x.txt -Value y', 'content-write'],
+  ['别名 tee', 'Get-Date | tee x.txt', 'content-write'],
+  ['重定向 >', 'Get-ChildItem . > out.txt', 'content-write'],
+  ['.NET 直写', '[IO.File]::WriteAllText("x.txt","y")', 'content-write'],
+  ['读文件（放行）', 'Get-Content x.txt -TotalCount 3', null],
+  ['流合并 2>&1（放行）', 'node x.mjs 2>&1', null],
+]
+
+// ── ② 内联代码 ────────────────────────────────────────────────────────────
+const inlineCases = [
+  ['node -e', 'node -e "console.log(1)"', 'inline-code-node'],
+  ['node -p', 'node -p "process.version"', 'inline-code-node'],
+  ['node 跑脚本（放行）', 'node tool.mjs', null],
+  ['node -c 语法检查（放行 —— 与 python -c 含义不同）', 'node -c tool.mjs', null],
+  ['python -c', 'python -c "print(1)"', 'inline-code-interp'],
+  ['powershell -Command', 'powershell -NoProfile -Command "Get-Date"', 'inline-code-interp'],
+  // 字符串里的写命令（语法树看不见内层代码，只按参数子串兜一层）
+  ['iex 里藏写命令', 'iex "Set-Content -Path x.txt -Value y"', 'encoded-write'],
+  ['iex 只读（放行）', 'iex "Get-Date"', null],
+  ['python -m（放行）', 'python -m http.server 8000', null],
+]
+
+// ── ③ 受保护目录 ──────────────────────────────────────────────────────────
+const pathCases = [
+  ['删 node_modules', 'Remove-Item .\\node_modules\\x -Force', 'protected-path'],
+  ['删 .git 下的东西', 'Remove-Item .\\\.git\\hooks\\x', 'protected-path'],
+  ['读 node_modules（放行）', 'Get-ChildItem .\\node_modules', null],
+]
+
+// ── ④ 三思层（只断言"停在哪条规则上"，不确认、不等冷却）──────────────────
+const desk = new DeliberateDesk()
+const deliberateCases = [
+  ['递归删除', 'Remove-Item .\\src\\a -Recurse', 'destructive-delete'],
+  ['删受保护目录', 'Remove-Item .\\node_modules -Force', 'destructive-delete'],
+  ['移动覆盖', 'Move-Item .\\a.txt .\\src\\a.txt -Force', 'destructive-move'],
+  ['注册表改键（cmdlet 那条）', "New-ItemProperty -Path 'HKCU:\\Software\\X' -Name a -Value b", 'registry-write-cmdlet'],
+  ['注册表改键（reg 那条）', 'reg add HKCU\\Software\\X /v a /d b /f', 'registry-write'],
+  ['读注册表（放行）', "reg query HKCU\\Software\\X", null],
+  ['git 范围收缩', 'git checkout -- .', 'destructive-git'],
+  ['git 建分支（放行）', 'git checkout -b feature-x', null],
+]
+
+// ── ⑤ 工具参数（不经过 shell）─────────────────────────────────────────────
+const toolCases = [
+  ['写凭据文件', 'write', { file_path: '.npmrc', content: 'x' }, 'credentials-readonly'],
+  ['写别的文件、正文提到凭据文件名（放行）', 'write', { file_path: 'notes.md', content: '改 .npmrc 之前先备份' }, null],
+  ['读凭据文件（放行）', 'read', { file_path: '.npmrc' }, null],
+]
+
+for (const [label, command, want] of [...writeCases, ...inlineCases, ...pathCases]) {
+  const facts = await daemon.parse(command)
+  const hit = evaluate(rules, facts)
+  check(label, want, hit === null ? null : hit.rule.id)
+}
+for (const [label, tool, args, want] of toolCases) {
+  const hit = evaluateToolParams(rules, tool, args)
+  check(label, want, hit === null ? null : hit.rule.id)
+}
+for (const [label, command, want] of deliberateCases) {
+  const facts = await daemon.parse(command)
+  const verdict = desk.check({ sessionId: 'smoke', command, facts, rules })
+  check(label, want, verdict === null ? null : verdict.pending.rule.id)
+}
+
+daemon.stop()
+
+const total = writeCases.length + inlineCases.length + pathCases.length + toolCases.length + deliberateCases.length
+console.log('')
+if (bad === 0) {
+  console.log(`冒烟测试全部通过（${total} 条，全程 dry-run）`)
+  process.exit(0)
+}
+console.log(`${bad} 条不符`)
+process.exit(1)