linear-cli 安全机制深剖:API Key 保护、终端转义符过滤与凭据原子写入完整指南

原创2026-10-16 21:23:331,441 阅读

linear-cli 安全机制深剖:API Key 保护、终端转义符过滤与凭据原子写入完整指南

linear-cli 是一款让你在终端里直接管理 Linear issue、一键创建分支与 PR 的命令行工具。把 API Key 交给一个本地 CLI,总让人有点不放心。这篇文章带你钻进 linear-cli 的源码,看清它如何用系统钥匙串保管 API Key、如何过滤终端转义符防止注入、又是怎样原子写入凭据文件——一次搞懂这套"agent friendly"工具的 3 大安全防线。

🔐 第一道防线:API Key 如何被保护

凭据默认存进系统钥匙串,不落明文

linear-cli 把 API Key 交给操作系统原生的密钥管理,而不是硬塞进本地文本文件:

平台 后端 调用方式
macOS Keychain 通过系统自带 /usr/bin/security
Linux libsecret 依赖 secret-tool
Windows Credential Manager 通过 advapi32.dll

本地 credentials.toml 只存"清单",不存密钥:

# credentials.toml(钥匙串模式)
default = "acme"
workspaces = ["acme", "side-project"]

真正的密钥躺在钥匙串里,路径定义在 auth/keyring/。

密钥全程"打码",连 Debug 都看不到

内部用 ConfigSecret 类型包装密钥,它的 Debug 输出永远显示 <redacted>,避免密钥被打进日志或报错信息里:

impl fmt::Debug for ConfigSecret {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("<redacted>")
    }
}

见 config/options.rs。

交互输入密钥时终端显示为掩码

linear auth login 手动输入密钥时,终端会显示为掩码,避免明文回显;脚本场景可用 --key <key> 直接传入。实现见 commands/auth/login.rs。

传参只走 stdin,绝不进命令行

命令行参数在 ps 里对同机其他用户可见,所以写入钥匙串时,密钥只通过 stdin 传给 secret-tool,而不进参数。这一点源码注释里写得很直白:

/// The secret goes to stdin, never to the arguments, where other users
/// could see it.

见 auth/keyring/secret_tool.rs。

只读"用到的那个"工作区密钥,失败不泄露

钥匙串查询是懒加载的——命令只读取所选工作区那一条,且每个工作区最多查一次(OnceCell 缓存)。失败分类 LookupFailureCategory 刻意不携带钥匙串输出,因为那段输出里可能包含密钥本体。见 auth/keyring/mod.rs。

🛡️ 第二道防线:终端转义符过滤

标题、成员名、评论正文都是"别人写的",可能夹带转义序列——移动光标、改样式,甚至改掉终端窗口标题。linear-cli 在给自己的输出加样式之前,先清洗所有远程文本,堵住"终端注入"这条路。

核心逻辑在 platform/terminal_text.rs:

  • multiline():保留换行和制表符,其余控制字符替换为 U+FFFD(�)
  • single_line():换行、回车、制表符一律压成空格
  • \r\n 归一化为 \n,裸 \r 变 \n

一条"注入"样例被拦下后的效果:

原始:  ok ]0;pwned  [2J ...
清洗后: ok  ]0;pwned  [2J ...

转义符、CSI、响铃、退格统统变成 � 占位符,任何序列都进不了你的终端。

📦 第三道防线:凭据文件原子写入

写凭据最怕两件事:写到一半崩溃,留下半截文件;文件权限太宽,被旁人读走。platform/private_file.rs 的 write_atomic 用经典的"临时文件 + rename"手法解决:

  1. 在同目录建一个**只属主可读(0o600)**的新临时文件
  2. 写入内容并 sync_all() 落盘
  3. 原子 rename 覆盖目标
  4. 再 sync 目录,确保 rename 持久

由此带来三个好处:

  • 中途被打断绝不会留下截断文件
  • 无论旧文件权限多松,新结果都只有属主能读
  • 符号链接被替换而非跟随,防止被诱导写到别处

新目录用 0o700 创建,private_dir 还会校验目录确属当前用户、不是符号链接,见 platform/private_file.rs。

读入侧同样设防

读取凭据文件时(auth/file.rs)也有护栏:

  • 大小上限 1MB(MAX_CONFIG_BYTES),超限直接报 too large
  • Unix 下用 O_NONBLOCK 打开,防止有人放个 FIFO 把启动卡死
  • 非普通文件(目录、设备等)直接拒绝,报 not a regular file

小结

机制 关键做法 源码位置
API Key 保护 系统钥匙串 + stdin 传参 + Debug 打码 auth/keyring/
终端转义符过滤 远程文本统一清洗为 U+FFFD terminal_text.rs
凭据原子写入 临时文件 + rename + 0o600 / 0o700 private_file.rs

linear-cli 把"密钥不落明文、注入进不来、写入不半路"这三件事做成了默认行为,无需任何额外配置。想亲手验证,可运行 linear auth list 查看已配置的工作区,或阅读 docs/authentication.md 了解多工作区与密钥选择顺序。

登录后查看全文
linear-cli