配置参考

本页说明当前代码的读取规则、默认值和边界；完整样例见 config.json.example。操作步骤见 运维手册，命令副作用见 命令参考。

配置如何生效

• 使用 JSON，不支持注释、尾逗号或环境变量插值。时长写字符串，例如 "30s"、"10m"、"24h"，不能写 "1d"。
• 先加载程序默认值，再覆盖文件中的字段。遗漏的顶层字段保留默认值；显式提供 rules 数组会替换默认规则，数组元素不会逐项继承默认 SSH 模板。
• 例如自定义规则遗漏 count_by_user 时值为 false；遗漏 reset_patterns 时没有成功登录重置规则。不要把局部规则片段当作完整规则。
• 文件缺失、未知字段、非法正则、非法端口、重复规则名会报错；重启前先运行 config-check。
• config-check 只校验，不扫描、不修改防火墙、不发通知。
• 守护进程启动时加载配置，不热更新。修改后重启对应服务；所有相关命令和服务应使用同一个 -config 路径。
• 安装器调用本平台二进制的 init-config；已有文件保持不变。

顶层字段

同一状态路径有进程锁，拒绝两个守护进程或 test 同时写入。隔离回放使用独立状态和通知队列路径。

SSH 规则字段

max_attempts、find_time、ban_time 小于等于零会恢复归一化默认值，不表示“永不封禁”。地区规则的空名称或非正阈值会被删除。

自定义 action 是可执行程序名，参数只有 IP，不是 shell 命令或后端枚举。托管规则用 auto。顶层 ssh_ports 默认 [22]，多个 SSH 端口显式设为 [22,2222]；此字段不会修改 sshd 的监听端口。

地区匹配忽略大小写，支持国家/省/城市部分名称；多个地区命中时确定性选择最高阈值，降低误封。数据库仅 IPv4；IPv6 检测不依赖 GeoIP。公司出口优先用白名单。

仅统计密码失败

修改已有 SSH 规则的 patterns，保留该规则其他字段，特别是 reset_patterns、阈值和 count_by_user：

{
  "patterns": ["Failed password for(?: invalid user)? (?P<user>\\S+) from <HOST>"]
}

这只是规则片段，不是完整配置。不会按每分钟建立多少次连接封禁；MaxAuthTries 是 sshd 单次连接内的认证限制。公司共用出口仍需 ignore_ips，详见 共享出口操作。

SSH 基线

以下字段位于 hardening.ssh。只由 secure-ssh 预览/写入；运行守护进程不会自动改写 sshd。

keepalive 是独立命令，不读取上述 JSON，也没有 -config 参数。它的预览包含密码/root 登录设置和保活参数；与 secure-ssh 的写入位置不同。使用前先比较输出，使用后检查 sshd 实际生效值。

日志、地区与恶意程序扫描

这是轻量 Linux 主机杀毒/入侵排查辅助，不是完整商业杀毒或 EDR。手动报告格式为 {名字}.yyyy-MM-dd_HH-mm-ss.txt；当前数量淘汰按修改时间实现“保留最新”的 LRU 类策略，不按读取次数刷新。自动巡检写应用日志，不能代替手动报告归档。

通知字段

所有字段位于 notifications。配置示例和具体渠道格式见 README 通知说明。

通知使用有界持久队列，各渠道独立、10 秒超时；检查 Telegram/飞书业务错误，只重试失败渠道。见 投递语义与配置。

生产快捷命令会改什么

语言/时区及独立 SMTP 凭据字段需要 v0.2.3+。非法语言或时区名校验失败；缺省维持 zh-CN / Local。新文件可用 init-config -language en -timezone UTC 创建，或参考英文 Linux 配置。支持 SMTP PLAIN/TLS，不支持 OAuth2；见服务商边界。

enable-production 只修改 dry_run=false，保留其他偏好；之后需要重启服务。

升级不静默改写已有规则。用 safe-ssh 预览、safe-ssh -write 迁移原默认规则。

源码依据：配置结构与默认值、扫描逻辑、命令入口。

新增防误伤与投递字段

• ssh_ports：目标 TCP 端口，默认 [22]（Linux/Windows），与真实 SSH 监听端口保持一致；PF 由管理员配置。
• 规则 success_grace：默认模板 "10m"；自定义规则省略时为 "0s"。成功登录对同规则该来源 IP 的所有用户名提供宽限；即使为零，同一读取批次仍优先处理成功。不会解除已存在封禁。
• notifications.queue_path：默认 state_path + ".notifications.json"；需私有可写路径，不能与状态文件相同。
• notifications.telegram：enabled、bot_token 或 bot_token_env、chat_id，可选 message_thread_id、disable_notification。bot_token_env 和邮箱 password_env 读取指定环境变量，不做通用 JSON 变量替换。