ssh-mcp防篡改审计日志:完整解析哈希链与三层密钥脱敏两大核心机制
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 请求一一对应,方便关联排查 |
但审计日志要真正"可作证据",必须解决两个经典难题:
- 被篡改:日志就在本地,有人事后删掉一行"作案记录"怎么办?
- 泄密:命令里带着密码、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) | 审计控制 | 命令/用户/主机/裁决全记录,哈希链防篡改 |
六、核心文件速览
- 审计存储与哈希链:src/audit/store.ts
- 三层脱敏实现:src/guard/redactor.ts
- 审计记录字段定义:src/types.ts
- 断链/编辑检测测试:test/unit/audit/chain-continuity.test.ts
- 轮转与脱敏测试:test/unit/audit/store.test.ts
- 安全合规说明:SECURITY.md
一句话总结:ssh-mcp 的审计日志用"上一条的哈希锁住本条"的哈希链实现改一行即断链,用字段、正则、熵值三层脱敏(外加已知机密原文清洗)保证机密不出现在任何一行日志里——再加上 0600 权限与大小轮转,让 AI 智能体的每次 SSH 操作都留下既不可抵赖、也不含机密的完整证据。