用于 Ubuntu 系统取证分诊的 Python CLI/TUI —— 检测并修复持久化机制,具备工件收集、时间线关联和 Wazuh 集成功能。
针对运行中的 Ubuntu 系统的取证分诊——在大约一分钟内完成自动化工件收集、持久化检测和引导式修复。
当你怀疑一台 Linux 系统已被入侵时,最初的 30-40 分钟通常都花在按顺序运行同样的十条命令上:检查运行中的进程、查找异常的 cron 任务、grep 查找 LD_PRELOAD、扫描 authorized_keys 中的新条目、审计 sudoers。每一步都是手动的、需要切换上下文,并且在压力下容易出错。漏掉一个来源——比如只检查了 /etc/sudoers 而没检查 /etc/sudoers.d/,或者只检查了 /etc/cron.d/ 而没检查用户 crontab——你就会得到一幅不完整的图景。
现有的方案无法干净地解决这个问题。lynis 是一个加固审计工具,而不是分诊工具——它在干净的系统中报告配置弱点,在已被入侵的系统中则产生大量噪音。chkrootkit 和 rkhunter 检查已知的 rootkit 特征,但对新型持久化技术视而不见,例如被滥用的 systemd 定时器或看似合法的 cron 条目。通用 SIEM 查询需要日志基础设施,而你所查看的系统上可能并不存在这些基础设施。像 Volatility 这样的取证套件针对的是内存镜像,而不是运行中主机上的实时 shell。
这个空白正是一款工具需要填补的:它能在当前实时系统上运行,覆盖最常见的持久化途径,将跨日志源的活动关联成时间线,并准确告诉你该查看什么——无需外部代理、数据库或互联网连接。
ubuntils 按四个连续阶段运行:
/proc、cron 表、systemd 单元、SSH 密钥、sudoers 文件、环境定义、软件包完整性(dpkg --verify)、PAM/NSS 配置以及已加载的内核模块中收集取证工件。大多数收集器在一两秒内完成;dpkg --verify 会重新检查每个已安装的软件包文件,因此耗时占主导——在 Ubuntu 26.04 arm64 桌面虚拟机上,一次完整扫描耗时 29–68 秒。--rules 加载的任何自定义规则——在大约一秒内生成按等级排序、带置信度评分的发现列表。--json)。ubuntils 本身不进行任何网络调用,并且所有功能——包括自定义规则和关联——都针对本地收集的工件运行。发现结果离开主机的唯一途径是 Wazuh 集成:如果安装了 Wazuh 代理,一次实时 scan 会将其发现写入本地文件,然后由该代理将其发送到其管理器。传入 --no-wazuh 可在一次运行中关闭该功能。
ubuntils scan 在以下所有内容中保持不变——它仍然是 100% 实时、单主机运行,且所有现有标志的行为完全一致。新增的两个命令 collect 和 analyze 将相同的检测/时间线流水线拆分为适合离线使用的“先采集后分析”工作流,适用于你无法(或不想)直接在受调查主机上运行检测的情况——请参阅下方的离线分析:collect 与 analyze,包括其检测覆盖范围的注意事项。
Ubuntu 22.04+ 以及任何带有 PEP 668 的系统(推荐):
Ubuntu 22.04+ 会阻止系统范围的 pip install。请使用 pipx——它会透明地处理环境,让你无需操心:
sudo apt install pipx -y
pipx ensurepath # then open a new shell
git clone https://github.com/asmitdesai/ubuntils.git
cd ubuntils
pipx install -e .
ubuntils scan # not `ubuntils scan` — see below
以普通用户身份运行:scan 和 collect 会在 sudo 下重新调用自身。自己输入 ubuntils … 会失败并提示 command not found,因为 sudo 的 secure_path 不包含 pipx 放置命令的 ~/.local/bin。如果你需要从 root shell 启动它,请通过路径调用已安装的二进制文件(~youruser/.local/bin/ubuntils scan),或者改为安装到虚拟环境中:
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/ubuntils scan
较旧系统 / 手动安装:
git clone https://github.com/asmitdesai/ubuntils.git
cd ubuntils
pip install -r requirements.txt -e .
ubuntils scan
ubuntils 需要 root 权限才能完整访问所有工件。如果你以非 root 用户运行 ubuntils scan,它会自动使用相同的 Python 解释器(通过绝对路径)以 sudo 重新调用自身,因此会使用正确的环境,而无需将你的 PATH 转发到 root 进程中。每个外部命令(ss、dpkg、systemctl……)都在固定的、由 root 拥有的搜索路径上解析,绝不会使用你的 PATH。不以 root 运行将跳过 /etc/shadow、部分 /proc 条目以及受保护的 cron 文件,并会为每一项记录警告。
仅检测 — 交互式 TUI:
ubuntils scan
使用 JSON 输出检测并将结果保存到文件:
ubuntils scan --json > /tmp/triage-$(hostname)-$(date +%Y%m%d).json
使用 CLI 修复预览进行检测(试运行 — 未应用任何更改):
ubuntils scan --remediate
应用 CLI 修复后的检测:
ubuntils scan --remediate --confirm
打印版本:
ubuntils version
收集防篡改证据包以供后续或离线分析:
ubuntils collect --output /path/to/bundle.tar.gz
分析之前收集的捆绑包(无需 root 权限):
ubuntils analyze /path/to/bundle.tar.gz --json
分析已挂载的取证镜像或提取的文件系统树,而非捆绑包:
ubuntils analyze --root /mnt/forensic-image --json
参见离线分析:收集与分析了解捆绑包格式,以及——重要的是——与实时 scan 相比,离线分析无法检测到的内容。
ubuntils scan [OPTIONS]
--json Output JSON to stdout instead of launching the TUI
--output FILE Write the JSON report to FILE (implies --json)
--remediate Run the remediation engine after detection
--confirm Required with --remediate to actually apply changes (else dry-run)
--min-confidence N Only auto-remediate findings with confidence >= N (default 40)
--no-wazuh Never forward findings to a local Wazuh agent
--config FILE YAML allowlist of findings to suppress (see below)
--baseline FILE YAML baseline of environment-specific known-good fingerprints to suppress (see below)
--since TIME Limit the timeline to events since TIME (e.g. '24h', '7d', '2026-05-20')
--rules FILE YAML file of custom detection rules to add (see below)
--verbose Verbose structlog output
ubuntils collect [OPTIONS]
--output FILE Bundle path to write (default ./ubuntils-bundle-<timestamp>.tar.gz)
--verbose Verbose structlog output
ubuntils analyze (BUNDLE | --root PATH) [OPTIONS]
--root PATH Analyze a mounted image / artifact tree instead of a bundle
--json Output JSON instead of launching the TUI
--output FILE Write the JSON report to FILE (implies --json)
--config FILE YAML allowlist of findings to suppress (same format as scan)
--baseline FILE YAML baseline of environment-specific known-good fingerprints to suppress (same format as scan)
--rules FILE YAML file of custom detection rules to add (same format as scan)
--since TIME Limit the timeline to events since TIME (e.g. '24h', '7d', '2026-05-20')
--verbose Verbose structlog output
ubuntils version
Print version string and exit
--config)新配置或由 CI 管理的主机会产生预期内的噪声——部署密钥、配置 crontab、内置 shell 初始化。与其让响应人员学会在脑中过滤这些内容,不如通过 YAML 允许列表显式抑制:
# allowlist.yaml
allowlist:
rules:
- SHELL_RC_MODIFICATION # suppress this rule entirely
paths:
- /home/ci/.ssh/authorized_keys # suppress any finding on this exact path
ubuntils scan --json --config allowlist.yaml
抑制始终是显式的——通过规则 ID 和/或精确的产物路径。不存在一刀切的“忽略一切”开关。示例位于 examples/allowlist.yaml。
--baseline)--config 会在任何人对该代码库运行 ubuntils 时,在所有位置抑制某条规则或路径。--baseline 范围更窄且特定于环境:它表示“在此环境中,这个确切的产物——这个 SSH 密钥、这个 RC 文件——是已知良好的”,而不会对你使用同一工具扫描的所有其他主机静默该规则或路径。它与 --config 保持为独立文件,原因与 --rules 独立相同:抑制与规则级允许列表是不同的关注点,不应放在同一个文件中。
# baseline.yaml
baseline:
- rule_id: SSH_UNAUTHORIZED_KEY
fingerprint: ci@ci-runner # substring match against the finding's raw_value
- rule_id: SHELL_RC_MODIFICATION
fingerprint: /home/deploy/.bashrc # exact match against the finding's artifact_path
ubuntils scan --json --baseline baseline.yaml
基线条目通过 rule_id 加上一个 fingerprint 进行匹配,该 fingerprint 会作为发现项 raw_value 的子串进行测试,或与其 artifact_path 进行精确匹配。匹配会将该发现项从报告中完全移除——不过抑制从不会静默进行:基线移除的发现项数量始终可见于 scan_metadata.suppressed_by_baseline。允许列表(--config)抑制仍然会在基线抑制之上生效。在 scan 和 analyze 上行为完全一致。示例位于 examples/baseline.yaml。
--rules)--config 抑制发现项;--rules 添加发现项。它们被刻意放在不同的文件中,因为它们是相反的关注点。
规则文件仅进行模式匹配——没有表达式、没有条件语句,也不执行代码,因此加载规则文件永远不会运行攻击者提供的逻辑。每条规则指定一个工件 source、一个 match 模式和一个 pattern: