sshconfig-lint

一个引擎，适用于 SSH 配置发生变更的所有场景。

sshconfig-lint 可发现 OpenSSH 客户端配置中的语义错误：重复主机、损坏的身份文件路径、不安全选项、弱算法、通配符顺序以及错综复杂的 Include 链。在本地、Git 钩子、GitHub Actions 和编辑器中均可使用相同的规则代码。

试用私有浏览器演练场 · 通过交互式示例学习 · 阅读所有规则

浏览器检查器在您的设备上运行。配置内容不会被上传，也不会收集任何遥测数据。

快速开始

# check ~/.ssh/config
sshconfig-lint

# check one or more repository configs
sshconfig-lint .ssh/config infrastructure/ssh_config

# fail on warnings and errors
sshconfig-lint .ssh/config --strict

安装

Homebrew

brew tap Noah4ever/tap
brew install sshconfig-lint

Cargo

cargo install sshconfig-lint

Arch Linux

yay -S sshconfig-lint-bin

发布页面提供适用于 Linux、macOS 和 Windows 的已验证二进制文件。便捷安装脚本会在安装前验证发布校验和：

curl -fsSL https://raw.githubusercontent.com/Noah4ever/sshconfig-lint/main/install.sh | bash

设置 VERSION=v0.5.0 或 INSTALL_DIR=~/.local/bin 可覆盖默认值。

GitHub Actions

官方 Action 已在 GitHub Marketplace 上提供。

name: SSH config
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Noah4ever/[email protected]
        with:
          paths: |
            .ssh/config
            infrastructure/ssh_config
          strict: true

检查结果会以注解形式显示在确切的文件和行上。该 Action 会下载与其标签匹配的发布版本，并在执行前验证 SHA256SUMS。

对于启用了 GitHub Code Scanning 的仓库，可以单独上传 SARIF：

- run: sshconfig-lint .ssh/config --format sarif > sshconfig-lint.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sshconfig-lint.sarif

Pre-Commit

repos:
  - repo: https://github.com/Noah4ever/sshconfig-lint
    rev: v1.0.0
    hooks:
      - id: sshconfig-lint-strict

当警告不应阻止提交时，请使用 id: sshconfig-lint。当配置使用其他命名约定时，请在项目中覆盖 files:。

编辑器

VS Code

从 Marketplace 安装 VS Code 扩展，或运行：

code --install-extension NoahThiering.sshconfig-lint

该扩展会启动 sshconfig-lint lsp，一次性下载匹配的已验证二进制文件，之后即可离线工作。它可识别 .ssh/config、ssh_config 以及 chezmoi 的 dot_ssh/config。不会收集任何遥测数据。其源代码位于 editors/vscode。

Neovim

经过测试的 editors/neovim 示例使用 Neovim 内置的 LSP 客户端。将其小型 Lua 模块复制到您的配置中，并通过以下方式启动：

require("sshconfig_lint").setup()

它使用与 VS Code 相同的 sshconfig-lint lsp 服务器，并支持自定义二进制文件路径。

任何支持 LSP 的编辑器都可以启动：

sshconfig-lint lsp

v0.5 语言服务器会在打开、更改和保存时发布整行诊断信息。未命名缓冲区运行仅内容规则；已保存文件还会解析 Include 和文件系统路径。来自嵌套 Include 的检查结果会附加到被包含的文件上，并随根文档一起清除。

输出格式

sshconfig-lint --format text
sshconfig-lint --format json
sshconfig-lint --format github
sshconfig-lint --format sarif

JSON 检查结果包含 severity、code、rule、line、file、message、hint 和 documentation。规则代码和退出代码是稳定的自动化接口。

退出码	含义
`0`	没有错误级别的检查结果，且使用 `--strict` 时没有警告
`1`	至少有一个阻断性检查结果
`2`	至少有一个请求的配置无法读取

规则

代码	规则	严重级别
`INVALID_VALUE`	无效的指令值	error
`DUP_HOST`	重复的 Host 块	warning
`MISSING_IDENTITY`	未找到 IdentityFile	error
`WILDCARD_ORDER`	Host 通配符顺序	warning
`WEAK_ALGO`	弱算法	warning
`DUP_DIRECTIVE`	重复指令	warning
`INSECURE_OPT`	不安全选项	warning
`UNSAFE_CTRL_PATH`	不安全的 ControlPath	warning
`INCLUDE_CYCLE`	Include 循环	error
`INCLUDE_DEPTH`	Include 嵌套过深	error
`INCLUDE_READ`	Include 无法读取	error
`INCLUDE_GLOB`	无效的 Include 模式	error
`INCLUDE_NO_MATCH`	Include 未匹配任何文件	info
`NEGATED_HOST`	Host 仅包含否定模式	warning
`PROXY_CONFLICT`	ProxyCommand 与 ProxyJump 冲突	warning
`REVOKED_HOST_KEYS_UNREADABLE`	RevokedHostKeys 文件不可读	error
`MISSING_CERTIFICATE`	未找到 CertificateFile	error
`LOCAL_COMMAND_DISABLED`	LocalCommand 未启用	warning
`INVALID_TOKEN`	无效的百分号标记	error
`INVALID_SYNTAX`	无效语法	error
`UNKNOWN_DIRECTIVE`	未知指令	error
`DEPRECATED_OPTION`	已弃用选项	warning
`INVALID_MATCH`	无效的 Match 条件	error
`CONTROL_PERSIST_UNUSED`	ControlPersist 缺少 ControlMaster	warning
`UPDATE_HOSTKEYS_ASK_PERSIST`	UpdateHostKeys ask 与 ControlPersist 同时使用	warning

规则指南会展示确切的错误片段、修正后的配置、其重要性，以及如何使用 OpenSSH 验证结果。

INVALID_VALUE 会检查端口、重试和提示计数器、alive 设置、ForwardX11Timeout、RequiredRSASize、ControlPersist、布尔开关、ObscureKeystrokeTiming、OpenSSH 时间值、StreamLocalBindMask、IPQoS，以及有文档记录的值集合，例如 AddressFamily、ControlMaster、StrictHostKeyChecking、LogLevel 和 PubkeyAuthentication。OpenSSH 接受的带引号和不区分大小写的值仍然有效。该 linter 接受现代语法，不会尝试推断将使用该配置的 SSH 客户端版本。

文件系统检查会跳过包含百分号标记或环境变量的路径，因为它们的最终值取决于连接上下文。LOCAL_COMMAND_DISABLED 同样保守：当未解析的 Include 或任何可能的 PermitLocalCommand yes 可能使该命令生效时，它会被抑制。通过常规 CLI 或已保存的编辑器文档解析 Include，以获得最精确的结果。

开发

需要 Rust 1.85 或更高版本。

cargo test --all
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt -- --check

请参阅 CONTRIBUTING.md、公开的路线图、 v1 稳定性契约和安全策略。

许可证

MIT

sshconfig-lint v0.5.0

分类