ssh-mcp防篡改审计日志:完整解析哈希链与三层密钥脱敏两大核心机制

原创2026-10-25 14:59:571,866 阅读

ssh-mcp防篡改审计日志:完整解析哈希链与三层密钥脱敏两大核心机制

ssh-mcp 是一个"安全优先"的 MCP(Model Context Protocol)服务器,它把 Linux 服务器的 SSH 控制能力暴露给 AI 智能体。为了让每一次远程命令都"可查、可证、不可赖",ssh-mcp 内置了一套防篡改审计日志:用 SHA-256 哈希链让任何一条被修改、删除的记录当场穿帮,再用 字段 → 正则 → 熵值 三层密钥脱敏保证密码、Token、私钥永远不会落盘。本文带你读懂这两大机制的实现原理与快速开启方式。

一、为什么普通的审计日志不够用

AI 智能体通过 ssh-mcp 执行远程命令时,每一次调用都会生成一条审计记录(JSONL 格式,每行一条),字段定义见 AuditRecord:

字段 作用
command / binary / commandClass 命令原文、可执行名、风险分级(read-only / safe / destructive / privileged)
decision / ruleId 策略引擎的裁决(allow / deny / require-approval)与命中规则
profile / user / approver 谁、用哪个画像、由谁批准
exitCode / durationMs / error 执行结果与耗时
mcpRequestId / eventId 与 MCP 请求一一对应,方便关联排查

但审计日志要真正"可作证据",必须解决两个经典难题:

  1. 被篡改:日志就在本地,有人事后删掉一行"作案记录"怎么办?
  2. 泄密:命令里带着密码、Token 时,日志会不会变成"机密清单"?

ssh-mcp 的答案是:哈希链 + 三层脱敏。

二、哈希链:让每一行都"咬住"上一行

核心实现只有约 10 行,位于 AuditStore._record()。开启 --auditTamperEvident 后,每条记录在写入前会被追加两个字段:

  • prevHash:上一条记录的 selfHash(首条为空字符串 "")
  • selfHash:对"本行 JSON + prevHash"计算出的 SHA-256 摘要
{ "command": "ls -la /var/log", "decision": "allow",
  "prevHash": "",
  "selfHash": "3c7f9a2e…" }
{ "command": "whoami", "decision": "allow",
  "prevHash": "3c7f9a2e…",
  "selfHash": "b81d44c0…" }

链式结构带来三个关键性质:

1. 改动任意一行都会"断链"

如果有人把 rm -rf /tmp/evidence 悄悄改写回 ls -la 而保留原哈希,重新计算的 selfHash 必然对不上;若连哈希一起改,下一行的 prevHash 又会对不上。正如集成测试 chain-continuity.test.ts 验证的:编辑后的条目在逐行复核时立刻暴露。

2. 进程重启后链条不断

重启时 lastHash 需要"接力"。loadLastHash() 会读取日志尾部最多 8KB、取最后一条完整记录的 selfHash 继续链式写入,保证跨进程依然连续可验证。该逻辑有专门的回归测试(picks the chain back up in a new process),防止"静默重启导致 prevHash 归零"这种隐蔽断链。

3. 崩溃也不影响日志继续写

kill -9 可能留下半截 JSON。写入端采用追加模式(flags: 'a'),且所有写入经过同一把串行写队列排队(record()),保证顺序与原子性;恢复时若最后一行不完整,直接以新链继续,半截行本身就是崩溃证据(见 keeps logging when the last line is truncated)。

日志文件本身也做了保护

  • 文件权限强制 0600,仅属主可读写(ensureStream())
  • 按大小轮转:单文件 100MB 触发滚动,最多保留 10 个历史文件(audit.log.1 ~ audit.log.10)
  • 日志位置按平台自适应:macOS 在 ~/Library/Logs/ssh-mcp/audit.log,Windows 在 %LOCALAPPDATA%\ssh-mcp\audit.log,Linux 在 $XDG_DATA_HOME/ssh-mcp/audit.log

三、三层密钥脱敏:密码与 Token 永不落盘

脱敏发生在哈希之前——先洗掉机密,再对清洗后的内容做链式签名,实现见 src/guard/redactor.ts。

第一层:字段级脱敏(field)

redactRecord() 递归遍历记录,凡是字段名为 password、privateKey、sudoPassword、passphrase、token、secret、apiKey、authorization 等(或后缀命中 token|secret|key|password)的值,直接整体替换为 [REDACTED]。

第二层:正则级脱敏(regex)

内置 7 组高识别度模式,命中后替换为 [REDACTED:名称:长度],保留长度信息便于排查但不泄露内容:

模式名 识别对象 脱敏效果示例
aws-access-key AKIA 开头的 20 位密钥 echo [REDACTED:aws-access-key:20]
github-token ghp_ / gho_ / ghs_ 等 [REDACTED:github-token:40]
gitlab-token glpat- 前缀 Token [REDACTED:gitlab-token:26]
jwt 三段式 eyJ… Token [REDACTED:jwt:104]
pem-private-key PEM 私钥块(上限 64KB,防回溯式正则回溯开销) [REDACTED:pem-private-key:…]
bearer-auth Authorization: Bearer … [REDACTED:bearer-auth:34]
generic-api-key api_key = "…" 类赋值 [REDACTED:generic-api-key:…]

单元用例见 test/unit/guard/redactor.test.ts。

第三层:熵值扫描(entropy,可选开启)

前两层抓"长得像密钥"的东西,第三层抓"不像密钥但很随机"的东西。开启 --auditEntropyScan 后,redactText() 会对长度 ≥20 的 [A-Za-z0-9+/=_-] 字符串计算 Shannon 熵,超过阈值 4.5 bit 即视为疑似随机密钥,替换为 [REDACTED:entropy:长度];而 aaaa… 这类低熵长串会被放过,避免误伤正常输出。

隐藏的第二道保险:已知机密原文清洗

对于"已知内容"(例如配置里填的 sudo 密码),它既无 Token 形状也未必高熵,前两层都可能漏过。ssh-mcp 额外支持 literalSecrets 精确清洗:已知机密原文(≥4 字符)在输出中被逐字替换为 <a href="https://link.gitcode.com/i/ba8fd5b1f7209a63e7fc0d5594dae044" target="_blank">REDACTED:secret:长度],作为纵深防御,修复思路对应安全公告 GHSA-9m75-x2ch-j4jr(见 [RedactOptions 注释)。

四、快速开启:两个命令行参数就够

ssh-mcp 的审计增强能力默认关闭,通过两个独立开关按需开启(参数表见 README.md):

参数 默认值 作用
--auditTamperEvident false 开启哈希链防篡改日志(prevHash + selfHash)
--auditEntropyScan false 开启第三层熵值密钥扫描

启动参数在 src/index.ts 解析并注入 AuditStore,两个能力可单独或同时开启。会话释放等控制面事件(如 close-session)也会以统一的 session:close … 记录入链,见 src/audit/session-release.ts。

自查小技巧:复核链完整性的方式与写入端完全一致——逐行取出去掉 prevHash/selfHash 后的 JSON,拼接上一行的 selfHash 再算一次 SHA-256 比对即可(参考 produces a chain that verifies end to end)。

五、顺手获得的合规映射

这套"哈希链 + 三层脱敏 + 轮转 + 0600 权限"的组合,恰好覆盖了多项合规条款,映射明细见 SECURITY.md:

合规框架 条款 对应能力
SOC 2 CC7.1 系统监控 JSONL 审计日志 + 三层脱敏
PCI-DSS v4.0 10.2 审计轨迹 / 10.4 日志保护 追加写 JSONL、requestId 关联、哈希链、轮转
HIPAA §164.312(b) 审计控制 命令/用户/主机/裁决全记录,哈希链防篡改

六、核心文件速览

一句话总结:ssh-mcp 的审计日志用"上一条的哈希锁住本条"的哈希链实现改一行即断链,用字段、正则、熵值三层脱敏(外加已知机密原文清洗)保证机密不出现在任何一行日志里——再加上 0600 权限与大小轮转,让 AI 智能体的每次 SSH 操作都留下既不可抵赖、也不含机密的完整证据。

登录后查看全文
ssh-mcp