CVE-2026-31431 批量检查与修复工具

English

本项目用于在企业内网中对 Linux 资产进行 CVE-2026-31431 的批量巡检与修复编排。

• 支持批量 SSH 登录设备
• 支持检查漏洞相关风险线索
• 支持临时缓解（禁用 algif_aead）
• 支持按发行版执行内核升级
• 支持输出 JSON / CSV / Markdown 报告

1. 环境要求

• Python: >=3.13
• 包管理: uv
• 网络: 能从执行机 SSH 到目标设备

2. 快速开始

2.1 安装依赖

uv sync

项目已在 pyproject.toml 配置清华源：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

2.2 准备资产配置文件

复制示例文件并按实际环境修改：

cp fleet.env.example fleet.env

2.3 运行

uv run python main.py fleet.env

3. 项目结构

.
├── main.py
├── pyproject.toml
├── uv.lock
├── fleet.env.example
├── reports/
└── src/
    ├── main.py
    ├── models.py
    ├── config.py
    ├── executor.py
    ├── collector.py
    ├── analyzer.py
    ├── adapters.py
    ├── remediator.py
    ├── orchestrator.py
    └── reporter.py

4. 配置文件详解（fleet.env）

配置文件是 KEY=VALUE 形式。空行和 # 注释会被忽略。

4.1 全局配置项

MODE

• 含义：运行模式。
• 可选值：
  • audit：仅检测，不执行修复。
  • fix：检测后按策略执行缓解与修复。
• 默认值：audit

AUTO_REBOOT

• 含义：修复成功后是否自动重启目标设备。
• 可选值：0 或 1
• 默认值：0
• 说明：仅在 MODE=fix 且修复流程成功时生效。

SSH_TIMEOUT

• 含义：SSH 连接与认证超时时间（秒）。
• 类型：整数
• 默认值：12

MAX_WORKERS

• 含义：并发处理设备数量（线程池大小）。
• 类型：整数
• 默认值：8
• 建议：根据跳板机和目标环境容量调整。

REPORT_DIR

• 含义：报告输出目录。
• 类型：相对路径或绝对路径
• 默认值：./reports

PROGRESS_HEARTBEAT_SECONDS

• 含义：实时进度心跳日志输出间隔。
• 类型：整数（秒）
• 默认值：5

DEVICE_MAX_DURATION_SECONDS

• 含义：单设备总执行时长阈值，用于超时/卡住告警。
• 类型：整数（秒）
• 默认值：1800

PROGRESS_LOG_TO_FILE

• 含义：是否将进度日志落盘到 REPORT_DIR。
• 可选值：0 或 1
• 默认值：1

FLEET_COUNT

• 含义：设备槽位数量（脚本会按 1..FLEET_COUNT 读取）。
• 类型：整数
• 说明：槽位内如果 DEVICE_n_HOST 为空会自动跳过该设备。

4.2 设备配置项（按编号）

每台设备通过 DEVICE_{n}_ 前缀定义，例如 DEVICE_1_*、DEVICE_2_*。

DEVICE_n_NAME

• 含义：设备显示名（用于报告）。
• 可留空：是，留空时自动命名为 device_n。

DEVICE_n_HOST

• 含义：目标主机地址（IP 或域名）。
• 必填：是（为空则该设备被跳过）。

DEVICE_n_PORT

• 含义：SSH 端口。
• 默认值：22

DEVICE_n_USER

• 含义：SSH 用户名。
• 默认值：root

DEVICE_n_PASSWORD

• 含义：SSH 密码认证。
• 说明：与 DEVICE_n_KEY 二选一或同时提供。
• 注意：脚本只使用 fleet.env 显式配置的密码或私钥，不会使用系统默认 SSH key/agent。

DEVICE_n_KEY

• 含义：SSH 私钥路径（本地路径）。
• 示例：./keys/node-1_ed25519
• 注意：若未配置 DEVICE_n_PASSWORD 且未配置 DEVICE_n_KEY，连接会直接失败并提示配置错误。

DEVICE_n_SUDO_PASSWORD

• 含义：sudo 密码（仅非 root 用户需要）。
• 说明：当需要执行修复命令时使用。

4.3 完整示例

# =========================
# Global
# =========================
MODE=audit
AUTO_REBOOT=0
SSH_TIMEOUT=12
MAX_WORKERS=8
REPORT_DIR=./reports
PROGRESS_HEARTBEAT_SECONDS=5
DEVICE_MAX_DURATION_SECONDS=1800
PROGRESS_LOG_TO_FILE=1
FLEET_COUNT=3

# =========================
# Device 1
# =========================
DEVICE_1_NAME=pve-node-1
DEVICE_1_HOST=192.168.1.10
DEVICE_1_PORT=22
DEVICE_1_USER=root
DEVICE_1_PASSWORD=
DEVICE_1_KEY=./keys/pve-node-1_ed25519
DEVICE_1_SUDO_PASSWORD=

# =========================
# Device 2
# =========================
DEVICE_2_NAME=web-1
DEVICE_2_HOST=192.168.1.20
DEVICE_2_PORT=22
DEVICE_2_USER=admin
DEVICE_2_PASSWORD=your_ssh_password
DEVICE_2_KEY=
DEVICE_2_SUDO_PASSWORD=your_sudo_password

# =========================
# Device 3
# =========================
DEVICE_3_NAME=
DEVICE_3_HOST=192.168.1.30
DEVICE_3_PORT=22
DEVICE_3_USER=ops
DEVICE_3_PASSWORD=
DEVICE_3_KEY=./keys/db-1_ed25519
DEVICE_3_SUDO_PASSWORD=

5. 运行模式与流程

5.1 审计模式（推荐先执行）

MODE=audit
uv run python main.py fleet.env

行为：

• 连接目标设备
• 采集系统信息与模块状态
• 采集补丁线索
• 输出状态与报告

5.2 修复模式

MODE=fix
AUTO_REBOOT=0
uv run python main.py fleet.env

行为：

• 先执行临时缓解：
  • 写入 /etc/modprobe.d/disable-cve-2026-31431-algif-aead.conf
  • 尝试卸载 algif_aead
• 再执行发行版对应的内核升级
• 根据 AUTO_REBOOT 决定是否自动重启

6. 状态定义

SAFE

• 存在补丁线索，且 algif_aead 未加载。

MITIGATED

• 已检测到缓解线索，但补丁线索不明确。

NEEDS_PATCH

• algif_aead 可用或已加载，且缺少明确补丁线索。

UNKNOWN

• 信息不足，无法明确判定。

FAILED

• SSH 登录失败或执行过程中发生异常。

7. 报告说明

每次执行会在 REPORT_DIR 输出 3 份报告：

• cve_2026_31431_时间戳.json
• cve_2026_31431_时间戳.csv
• cve_2026_31431_时间戳.md
• progress_时间戳.log（实时进度与心跳日志）

核心字段：

• name, host
• status
• kernel, os
• algif_loaded, algif_available
• patch_hint
• fixed, rebooted
• error

8. 安全建议

• 不要将 fleet.env、私钥文件提交到 Git。
• 建议配置最小权限运维账号，避免长期使用 root 密码。
• 修复前建议做好快照或备份。
• 生产环境建议分批执行：先 audit，后 fix，再复检。

9. 常见问题

ModuleNotFoundError: No module named 'paramiko'

• 执行 uv sync 安装依赖。

FAILED 数量较多

• 检查网络连通性、SSH 凭据、sudo 权限及目标主机 known_hosts 配置。

BadHostKeyException（主机指纹冲突）

• 含义：目标主机当前指纹与本机 known_hosts 记录不一致。
• 注意：这不是在使用系统认证 key 回退；认证仍只使用 fleet.env 显式配置的密码/私钥。
• 处理步骤（请先带外确认主机身份）：
  • ssh-keygen -R 目标IP
  • ssh-keyscan -H 目标IP >> $env:USERPROFILE\.ssh\known_hosts

Server ... not found in known_hosts

• 含义：当前启用了严格指纹校验，但本机 known_hosts 尚无该主机记录。
• 处理：先写入该主机指纹，再重新执行脚本。

修复后未生效

• 内核补丁通常需要重启进入新内核，请检查 AUTO_REBOOT 或手动维护窗口重启。