org-ai-assisted/dist-ai
GitHub: org-ai-assisted/dist-ai
面向 Kicksecure/Whonix 生态的 AI 辅助测试、回归复现与模糊测试工具集，在隔离 CI 中验证系统各组件的正确性与鲁棒性。
Stars: 0 | Forks: 0
# dist-ai
用于 Kicksecure 和 Whonix 生态系统的 AI 测试、复现和模糊测试工具，由 AI 协助提交。这是 AI 自己的沙盒工具：它仅在一次性、不受信任的 CI 上运行，绝不发布给用户，也绝不进入 Kicksecure 或 Whonix。
有关如何处理 AI 协助贡献，以及为什么此代码的信任度低于人工编写代码的原因，请参阅该组织页面：
[org-ai-assisted.github.io](https://org-ai-assisted.github.io) (组织：
[github.com/org-ai-assisted](https://github.com/org-ai-assisted))。
此处仅提交了工具；其大型的、可重新生成的构建产物（baseline 语料库、模糊测试输入、生成的 fixtures）是保存在操作员私有缓存（`~/private-cache`）中的运行时数据，绝不会出现在代码库或软件包中。
## 组件
| 组件 | 状态 | 位置 |
|---|---|---|
| `mediawiki-dom-snapshot` | 正在发布 | `usr/share/mediawiki-dom-snapshot/` |
| `sdwdate-gui-tests` | 正在发布 | `usr/share/sdwdate-gui-tests/` |
| `onion-grater-tests` | 正在发布 | `usr/share/onion-grater-tests/` |
| `privleap-tests` | 正在发布 | `usr/share/privleap-tests/` |
| `genmkfile-tests` | 正在发布 | `usr/share/genmkfile-tests/` |
| `dm-help-steps-tests` | 正在发布 | `usr/share/dm-help-steps-tests/` |
| `open-link-confirmation-tests` | 正在发布 | `usr/share/open-link-confirmation-tests/` |
| `sanitize-string-tests` | 正在发布 | `usr/share/sanitize-string-tests/` |
| `stcat-family-tests` | 正在发布 | `usr/share/stcat-family-tests/` |
| `stdisplay-tests` | 正在发布 | `usr/share/stdisplay-tests/` |
| `systemcheck-tests` | 正在发布 | `usr/share/systemcheck-tests/` |
| `tor-control-panel-tests` | 正在发布 | `usr/share/tor-control-panel-tests/` |
| `unicode-show-tests` | 正在发布 | `usr/share/unicode-show-tests/` |
| `grep-find-unicode-wrapper-tests` | 正在发布 | `usr/share/grep-find-unicode-wrapper-tests/` |
| `check-ref-commits-for-unicode-tests` | 正在发布 | `usr/share/check-ref-commits-for-unicode-tests/` |
| `discourse-dom-snapshot` | 计划中 | `usr/share/discourse-dom-snapshot/` |
| `sdwdate-ci-fuzz` | 计划中 | `usr/share/sdwdate-ci-fuzz/` |
每个组件都是独立的。每个组件通过 `debian/.install` 发布其各自的 Debian 二进制包。该代码库遵循 Kicksecure 打包树其余部分所使用的 FHS 布局。
## dist-ai-tests-all
除此之外，没有单一的“运行所有内容”目标。`dist-ai-tests-all`
(`usr/bin/dist-ai-tests-all`) 会一次性运行所有测试套件，汇总各套件的结果（PASS / FAIL / SKIP / TIMEOUT），并在出现任何失败时以非零状态退出。分类标志用于选择运行的内容：`--core`（默认）、`--fuzz`、`--e2e`、`--integration` 或 `--all`。
传入 `--repo-root ` 可将每个套件指向树内检出路径（它会自动为每个套件配置 `*_REPO` / `*_BIN` / `PYTHONPATH` 及位置参数），而不是使用已安装的包；如果套件的目标不存在，则以状态码 77 退出并被报告为 SKIP。`mediawiki-dom-snapshot` 是一个捕获工具，而不是通过/失败测试，因此未包含在内。
```
# 针对 in-tree checkout 的 core suite
dist-ai-tests-all --core --repo-root ~/derivative-maker
# 全部（fuzz 耗时较长；e2e 需要 tor + sudo；integration 需要 GUI stack）
dist-ai-tests-all --all --repo-root ~/derivative-maker
```
## mediawiki-dom-snapshot
通过 Playwright 驱动 headless Chromium 访问正在运行的 MediaWiki，捕获**每个页面的完整回归测试语料库**（post-JS DOM、视口截图、带有 body sha256 的完整网络清单、按哈希索引的每个 asset body），并发布三维差异对比（HTML 文本、asset 内容、截图像素 + 感知哈希），从而可以证明重构没有引起任何可观察到的变化。
用例：检测由 MediaWiki 核心或扩展升级，或站点 CSS 重构引入的 HTML/CSS/JS/图像回归。在更改前捕获 baseline，更改后再次运行并进行差异对比。pHash 距离是最强的单一信号——如果保持为 0，则说明尽管存在任何像素级别的抗锯齿抖动，但渲染在视觉上是完全相同的。
### 输出布局
对于 `pages.conf` 中的每个页面：
```
//
dom.html post-JS rendered HTML (volatile fields
scrubbed during normalise step)
screenshot.png viewport screenshot (animations disabled)
manifest.json URL -> { sha256, size, content_type, status }
assets/.
raw asset body, indexed by content hash so the
same CSS/JS/image served from multiple URLs
de-duplicates onto one file
```
### 用法
```
# 针对 live wiki 进行 capture 和 normalize
mediawiki-dom-snapshot
# 将 captured set 与 baseline 进行 diff
mediawiki-dom-snapshot diff-baseline
# 直接对两个 captured set 进行 diff
mediawiki-dom-snapshot diff
# 将 captured set 提升为新的 baseline
mediawiki-dom-snapshot baseline-promote
```
环境变量覆盖：
| 变量 | 默认值 | 含义 |
|---|---|---|
| `BASE_URL` | `https://www.kicksecure.com` | 目标 wiki 源 |
| `PAGES_FILE` | `/etc/mediawiki-dom-snapshot/pages.conf` | 每行一个标题 |
| `VIEWPORT` | `1280x800` | 浏览器视口 |
| `TIMEOUT_MS` | `30000` | 每个页面的超时时间 |
| `RAW_DIR` | `~/private-cache/mediawiki-dom-snapshot/raw` | 原始输出 |
| `FIX_DIR` | `~/private-cache/mediawiki-dom-snapshot/fixtures` | 规范化后输出 |
| `BASELINE_DIR` | `~/private-cache/mediawiki-dom-snapshot/baseline` | baseline 语料库 |
## sdwdate-gui-tests
用于 `sdwdate-gui-server` 的 headless `unittest` 套件，在 Qt `offscreen` 平台插件下驱动真实的 `SdwdateTrayIcon` 和 `SdwdateGuiClient` 类，并使用未连接的本地 socket。不需要 X server、系统托盘或实时的 qrexec 连接。
单元测试覆盖范围：
- 客户端去重不变式，防止单个 Qubes VM（例如 DisposableVM `dispNNNN`）在网关服务器清理之前重新连接时，在托盘菜单中被多次列出
( -- sudo bash ./umount_kill_test.sh`，并在测试旁边放置 `umount_kill.sh` 暂存副本。目标选择顺序：`UMOUNT_KILL_SH`，然后是暂存的兄弟副本，最后是 `~/derivative-maker/help-steps/umount_kill.sh`。
## genmkfile-tests
针对 `genmkfile` 构建助手目标分发的回归测试。
`genmkfile` 的主分发逻辑将构建机器的设置分为轻量级的“仅依赖”路径（`make_get_dependencies`）和完整的“版本信息”路径（`make_get_variables`）。只有 `deb-build-dep` / `deb-run-dep` / `deb-all-dep` 可以走轻量级路径；任何涉及由 `make_get_variables` 设置的变量的目标（upstream/debian tarball 路径、`.dsc` / `.changes` 名称、`make_package_list`）都必须走完整路径。
之前有两个 commit 错误地将 `deb-cleanup`、`reprepro-remove` 和 `reprepro-add` 分类到了轻量级组中，导致它们因例如 `make_upstream_tarball_relative_path: unbound variable`（以及 reprepro 目标对应的 `make_main_changes_file` / `make_package_list` 失败）而中止。该测试套件针对一个一次性最小化 Debian 源码包驱动真实的 `genmkfile`，并断言这三个目标中的每一个都通过 `make_get_variables` 路由，且永远不会触发“unbound variable”错误。不需要 root、不需要网络、不需要真实的 reprepro（由一个 stub 包装器代替）。已针对修复前的代码树验证为非空洞。
第二个测试（`git_describe_control_test.sh`）涵盖了 `make_use_git_describe_for_version` 路径。该标志用于没有 `debian/control` 的特殊代码库（Whonix-Installer、qubes-template-*），在这些代码库中，`make_get_variables` 会在设置 tarball / `.dsc` 路径之前短路。`live-build` 设置了相同的标志，但**确实**包含了 `debian/control` 并且被构建为 `.deb`，因此短路导致 `make_upstream_tarball_relative_path` 未设置，从而使得 `deb-cleanup` 中止。修复方案根据 `debian/control` 实际不存在的情况来对短路进行门控；测试断言带有标志和 `control` 的 fixture 会将 `deb-cleanup` 通过 `make_get_variables` 路由且不发生 unbound-variable 错误，**并且** `git-tag-show` 仍然报告 git-describe 标签（`commit_`），而不是 changelog 中的版本。同样针对修复前的代码树验证为非空洞。
该套件默认针对 `PATH` 中的 `genmkfile` 进行测试；设置 `GENMKFILE_BIN` 可测试特定的 `genmkfile`，否则它将回退到 `~/derivative-maker` 下的 derivative-maker 检出。
### 用法
```
# dispatch regression suite
genmkfile-tests
# 测试特定的 genmkfile binary
GENMKFILE_BIN=/path/to/genmkfile genmkfile-tests
```
## open-link-confirmation-tests
针对 Kicksecure [open-link-confirmation](https://github.com/Kicksecure/open-link-confirmation) 链接/文件确认对话框（即 `$BROWSER` / `x-www-browser` 处理程序）的安全和单元测试。不受信任的输入是 URL/文件参数；它通过 helper-scripts 的 `sanitize-string` 进行管道处理，并将结果作为 HTML 渲染在 PyQt5 的 `QTextBrowser` 中来显示。
`open-link-confirmation-tests` 命令检查整个显示管道，不需要 root / 不需要网络 / 不需要真实的浏览器（Qt 在 offscreen 模式下运行）：
- 针对一系列恶意测试用例（Unicode、RTL 覆盖、零宽字符、ANSI/SGR、OSC-8、控制字节、超大输入、标记）的清理契约，
- Qt 富文本差异测试，使用真实的 Qt 引擎解析已清理的输出，并断言没有引入任何可点击的锚点或图像，
- 静态审计，确保脚本只显示经过清理的参数，
- 以及针对 `source_config()` 环境变量覆盖配置优先级的 bash 单元测试。
Qt 测试组将一个已知的、目前未修复的标记注入绕过（一个 `<` 后跟空格再跟一个标签名会绕过 `sanitize-string`，但 Qt 会重构该标签）编码为严格的预期失败用例；请参阅 `usr/share/open-link-confirmation-tests/README.md`。
### 用法
```
open-link-confirmation-tests
# 测试 checkout 而非已安装的副本
OPEN_LINK_CONFIRMATION_BIN=/path/to/open-link-confirmation \
SANITIZE_STRING_BIN=/path/to/sanitize-string \
./usr/bin/open-link-confirmation-tests
```
## sanitize-string-tests
对 helper-scripts sanitize 家族（`stdisplay` -> `strip_markup` -> `sanitize-string`）的深度测试和模糊测试，这些工具主要被 msgcollector 的 PyQt5 `QTextBrowser` 对话框所使用。`sanitize-string` 的输出必须保证在终端和作为 HTML/Qt 富文本显示时都是安全的。该套件证明了这一点，没有任何绕过：
- `[T]` 终端安全（仅限 ASCII，除了换行符/制表符外没有控制字符/ESC，有长度限制），`[H]` 没有残留的 `<`，`[Q]` 针对真实 Qt 引擎的跨解析器差异测试（没有恢复的锚点/图像），`[F]` 内容保真度（良性输入包括 `&`-query URL 能正确往返，不会被静默丢弃），`[L]` 长度限制是精确的。
- 它将解析器差异导致的标记注入绕过和丢弃 `&` 的内容错误编码为严格的预期失败用例，一旦安装了修复后的 `sanitize-string`，它们就会转变为通过。附带了 `qtextbrowser_repro.py`（最小化的 headless 复现）和 `popup_repro.sh`（通过 `sanitize-string` + `generic_gui_message` 进行实时 PoC）。
### 用法
```
sanitize-string-tests
sanitize-string-tests-fuzz # heavy fuzz sweep
SANITIZE_STRING_BIN=/path/to/sanitize-string sanitize-string-tests
```
## stcat-family-tests
针对 **stcat 家族**的综合测试和模糊测试——这是 helper-scripts `stdisplay` 包中的 CLI 工具，用于将不受信任的文本安全地打印到终端：`stcat`、`stcatn`、`stecho`、`stprint`、`stsponge`、`sttee`。每一个都将输入通过 `stdisplay()` 路由，并强制输出 ASCII。该套件证明了在所有六个工具中，没有任何危险内容会到达终端：
- `[U]` 无颜色：在恶意语料库和字节级 fuzzer 的测试下，输出是纯可打印 ASCII + 换行符/制表符（没有 Unicode、控制字符、ESC、DEL）。
- `[C]` 颜色：Unicode 仍然会被剥离，只有格式正确的 SGR 颜色转义序列会保留；OSC-8 和 CSI 光标/清除序列会被中和。
- `[S]` 语义：每个工具仍然执行其功能（包括文件路径，其写入的内容会被验证为已清理）。
- `[F]` fuzz：随机字节流（Unicode、控制字符、转义符、格式错误的 UTF-8、NUL）永远不会破坏无颜色不变式。
### 用法
```
stcat-family-tests
stcat-family-tests-fuzz # heavy fuzz sweep
STDISPLAY_REPO=/path/to/helper-scripts stcat-family-tests
```
## stdisplay-tests
针对 **`stdisplay()`** 本身的综合测试和模糊测试——即 stcat 家族输入所经过的 `stdisplay` 包中的函数。`stcat-family-tests` 在两种颜色设置下驱动 CLI，而此套件则**直接在每个颜色深度**（3/4/8/24 位）下测试该函数，这是容易出错的部分（`get_sgr_pattern()` 的分级允许列表）。每个输出都会根据一个**独立的、与调色板无关的安全预言机**进行检查：剥离每一个松散的 `ESC [ ... m`（SGR 只能设置颜色），不能残留任何危险内容。
- `[P]` 钉子测试：模块自身文档字符串中的示例作为精确字符串回归测试。
- `[B]` 良性测试：可打印 ASCII + 换行符/制表符在每种深度下都能保持不变地通过（证明它不会过度过滤）。
- `[G]` 分级测试：每个 SGR 位模式（3 位 fg/bg/reset、4 位 bright、8 位 `;`/`:`、24 位）中的一个序列在其深度启用时完整保留，否则将被过滤。
- `[R]` 过滤：在包括 truecolor 在内的每种深度下，过滤掉危险的 non-SGR 转义符（清除、光标、注入输入的设备状态报告、OSC title / OSC-8、DCS/APC/PM、RIS、charset）、C1 / C0 控制字符、DEL 以及非 ASCII 字符。
- `[X]` 排除：`exclude_sgr` 仅删除其指定的代码。
- `[E]` 环境：`get_sgr_support()` 的 NO_COLOR / COLORTERM 逻辑，以及在未知或哑终端上失败关闭（`< 8`，无转义符）的 `TERM` 路径。
- `[I]` 幂等性：`stdisplay(stdisplay(x)) == stdisplay(x)`。
- `[F]` fuzz：随机 Unicode、偏向转义符的走私通道以及随机排除列表永远不会引发异常、破坏预言机或失去幂等性。
### 用法
```
stdisplay-tests
stdisplay-tests-fuzz # heavy fuzz sweep
STDISPLAY_REPO=/path/to/helper-scripts stdisplay-tests
```
## unicode-show-tests
针对 **unicode-show** 的综合测试和模糊测试——这是 helper-scripts `unicode_show` 包中用于**检测**可疑 Unicode 的扫描器。它是 `stcat` 家族的镜像：`stcat` 为终端清理不受信任的文本，而 `unicode-show` 则报告危险字符（退出 `0` 表示干净，`1` 表示发现可疑，`2` 表示错误）。该套件针对真实的 CLI 端到端证明了整个契约：
- `[D]` 检测：在恶意语料库（bidi Trojan-Source 集、零宽字符、BOM、同形异义词、组合字符、C1、行/段落分隔符、CJK、emoji、C0 / NUL / DEL）的测试下，工具退出 `1` 并指出确切的 codepoint（例如 `U+202E`）。
- `[S]` 自安全性：unicode-show 自身的 stdout 绝不会泄漏它报告的原始可疑字节——在整个语料库和 fuzzer 的测试下，输出均为纯可打印 ASCII + 换行符/制表符（它依赖于 `ascii()`；如果退化到使用 `repr()``，会在此处被捕获）。
- `[B]` 良性：干净的 ASCII 退出 `0` 且无输出（因此 `[D]` 是非空洞的）。
- `[N]` 换行符/空白字符：会标记尾随空白；默认标记缺少最后换行符的情况，通过 `UNICODE_SHOW_ALLOW_MISSING_FINAL_NEWLINE=1` 抑制；空输入判定为干净。
- `[E]` 失败关闭：无效的 UTF-8（stdin 或文件）退出 `2`，且不会向 stdout 泄漏任何字节；不存在的路径退出 `2`。
- `[P]` 路径：能检测出恶意的文件内容，并且在输出中会对恶意文件名进行清理。
- `[F]` fuzz：随机字节流和随机的有效 Unicode 绝不会导致崩溃、挂起或破坏 `[S]` 不变式。
### 用法
```
unicode-show-tests
unicode-show-tests-fuzz # heavy fuzz sweep
UNICODE_SHOW_REPO=/path/to/helper-scripts unicode-show-tests
```
## grep-find-unicode-wrapper-tests
针对 **grep-find-unicode-wrapper** 的综合测试和模糊测试——这是 helper-scripts 中围绕 `grep` 的 bash 包装器，用于扫描**文件**中的可疑内容并列出有问题的文件（类似 grep 的行为：退出 `0` 表示匹配，`1` 表示不匹配，遇到 grep 错误时大声失败）。匹配项通过 `stecho` 打印，因此 Unicode 文件名无法将任何有害内容走私到终端。如果一个文件包含任何非可打印 ASCII 或制表符/换行符的字节，则视为匹配——这是非 ASCII 字节、bidi Trojan-Source 集以及 C0-control/DEL/NUL grep 的并集。
- `[D]`/`[C]` 检测：恶意语料库会被标记，并带有专门的检查以确保纯 ASCII 控制字节（非 ASCII grep 会漏掉）仍然会被捕获。
- `[B]` 良性：干净的 ASCII 不会被标记——包括尾随空白，该工具（与 `unicode-show` 不同）不将其视为可疑。
- `[M]` 多文件：仅列出有问题的文件，并按 `-u` 排序。
- `[P]` 自安全性：恶意文件名在输出中会被清理（纯 ASCII）。
- `[E]` 错误：不存在的路径会大声失败，而不是静默的不匹配。
- `[K]` 已知限制：该工具文档中记录的损坏的 stdin 处理（只有第一个 grep 会消耗管道，因此仅含控制字符的 stdin 输入会导致假阴性）已被钉住，如果 stdin 被修复，它将转变为失败。
- `[F]` fuzz：随机字节文件会与一个独立的字节级预言机进行检查——退出代码必须完全一致，且输出必须保持为纯 ASCII。
### 用法
```
grep-find-unicode-wrapper-tests
grep-find-unicode-wrapper-tests-fuzz # heavy fuzz sweep
GREP_FIND_UNICODE_WRAPPER_REPO=/path/to/helper-scripts grep-find-unicode-wrapper-tests
```
## check-ref-commits-for-unicode-tests
针对 **check-ref-commits-for-unicode** 的综合测试和模糊测试——这是 helper-scripts 中的 git-ref 守卫，用于扫描 ref 引入的每个 commit（`git log HEAD..
标签：AI辅助开发, Kicksecure, Whonix, 测试工具, 特征检测, 逆向工具