aguilerasmiguel/J0Witness-release

# J0Witness           **J0Witness 是一款用于 Joomla 安装的离线完整性与取证分析工具。** 它可以在网站不处于运行状态、且无需您自备基准线的情况下，判断磁盘上的 Joomla 安装与原始官方发行版有何差异，并提供充足的证据和溯源信息，供人工判断是否发生了入侵。 ## 适用人群 J0Witness 专为那些*接手* Joomla 站点并必须出具相关报告的人员（而非主要针对扫描自己服务器的站点所有者）而构建： - **事件响应顾问**：接手一个“以防万一”被下线的站点——他们现在拥有一个压缩包和一个数据库导出文件，必须出具一份客户（或法律程序）会阅读的调查结果报告。 - **托管服务商和 MSP**：管理着大量 Joomla 安装，需要对每个站点进行可重复的离线判定，而无需实时登录每一个站点。 - **继承第三方站点的代理商**：在承担相应责任之前，必须对接手的内容进行审计。 这些角色的共同点在于：他们需要一份**经得起推敲的交付物**。这就是为什么可重现的构建、确定性的输出和 **PDF 报告**不是表面文章——它们就是核心产品。能够交付一份报告并声明*“重新运行此命令，结果将逐字节完全一致”*，这在法律程序中具有分量。而且由于分析是**离线的**，它恰好适用于实时扫描器（如 Wordfence、Sucuri 等）无法工作的场景：网站已经下线，您手中只有文件和导出数据。 ## 存在意义 J0Witness 基于以下原则构建： - **离线且自包含。** 单一静态二进制文件。默认无 PHP runtime、无数据库、无网络。将其复制到主机上即可运行。 - **被分析的文件树即为证据——绝不对其进行写入。** J0Witness 只执行读取操作。 - **绝不执行被分析的代码。** 所有 PHP/config 分析均为静态文本分析；绝不运行该文件树。 - **确定性与可重现。** 相同的（文件树、基准线、二进制文件、标志）输入会产生逐字节一致的输出，且二进制文件本身也是可重现构建的——当报告作为证据使用时，这两个属性都至关重要。 - **将误报视为严重缺陷。** 引擎宁可保持静默也不会谎报军情；每一项发现都应具备可操作性。这对于 CI 和监控来说是正确的默认设置，因为噪音会扼杀采用率。但在实际操作的事件响应中，权衡标准正好相反——漏掉一个后门所付出的代价远高于分析师排除几个文件的成本。因此，计划中的*高灵敏度 / IR 模式*（参见[路线图](docs/ROADMAP.md)）将呈现阈值以下的观察结果供人工分类处理，同时不改变保守的默认设置。 ## 功能介绍 J0Witness 组合了多个独立的分析层，每层读取已捕获的证据并提供观察结果。判定（发现）是通过对这些观察结果**执行查询衍生而来的**——绝不作为核心事实存储——因此可以从持久化的扫描中重新渲染报告，而无需再次触碰文件树。 | 层级 | 功能描述 | 规则 | |------|---------------|-------| | **L0** acquire | 确定性清单：hash、元数据、大小。只读。 | — | | **L1** fingerprint | 模糊哈希（TLSH），用于将修改过的文件与其原版配对。 | — | | **L2** core-diff | 与官方 Joomla 发行版进行对比：新增/修改/删除的核心文件。 | `J0W-CORE-*` | | **L3** ext-map | 通过清单发现第三方扩展，并将每个文件归属于其声明的扩展。 | `J0W-EXT-*`, `J0W-LAYOUT-001` | | **L4** code-scan | 静态 PHP 内容分析（绝不执行）：检测 webshell、混淆代码、执行加载器。 | `J0W-CODE-*` | | **L5** conf-scan | 检查 `.htaccess` / `.user.ini` / `web.config` 中的危险指令。 | `J0W-CONFIG-*` | | **L6** timeline | 基于声明威胁模型，以 ctime 为锚点的时间印证。 | `J0W-TIME-001` | | **L7** db-scan | 通过提供的 `mysqldump` 与站点数据库进行关联（离线，绝不执行）。 | `J0W-DB-*` | 此外： - **扫描间的差异对比**（`j0witness diff`）：比较同一站点的两次持久化扫描——即监控/事件响应中常问的问题：“*自上次已知良好的扫描以来发生了什么变化？*” - **扫描时的基准线验证**：内置目录是唯一的信任根源；存储的基准线和缓存的官方包在对比信任它们之前会重新接受验证，如果检测到篡改，扫描将强制拒绝（`BASELINE_UNTRUSTED`）。 - **基于同一规范 JSON 的四种报告展现形式**：`json` · `text` · `pdf` · `sarif`。`pdf` 是**面向客户的交付物**——IR 顾问或 MSP 交付的文档；`sarif` 用于接入 CI / 代码扫描；`json` 是机器可读的规范源，所有其他展现形式均纯粹且确定性地由其衍生而来。 - **双语报告**：`--language en|es`。 - **误报抑制**：采用声明式排除文件，其中必须填写排除理由，且每次抑制都会在报告中予以回显。 ## 下载 预构建的**静态二进制文件**（Linux `amd64` / `arm64`）已附加在每个 [GitHub Release](https://github.com/aguilerasmiguel/J0Witness-release/releases) 中， 同时附带 `SHA256SUMS.txt`。无任何依赖——验证、标记为可执行文件、运行： ``` sha256sum -c SHA256SUMS.txt chmod +x j0witness-linux-amd64 ./j0witness-linux-amd64 --help ``` 该构建是**可重现的**：从发布标签的 checkout 中执行 `make -C src build-all VERSION=` 会生成完全相同的二进制文件（一致的 SHA256）。要自行从源码构建，请参阅 **[docs/BUILD.md](docs/BUILD.md)**。 ## 快速入门 ``` # 1. 预先导入一次官方 baseline（离线：单独下载该 package）。 j0witness baseline add Joomla_5.1.4-Stable-Full_Package.zip # 或者，在具有明确授权网络的情况下： # j0witness baseline fetch 5.1.4 --allow-network # 2. 扫描。stdout = 标准 JSON 报告；stderr = 进度。 j0witness scan /var/www/mysite > report.json # 人类可读格式： j0witness scan /var/www/mysite --format text j0witness scan /var/www/mysite --format pdf > report.pdf # 3. 与 database 进行关联（离线；dump 会被解析，绝不执行）： j0witness scan /var/www/mysite --db dump.sql --format text # 4. 监控 / IR — 自上次扫描以来的变更： j0witness runs /var/www/mysite # list persisted scans j0witness diff /var/www/mysite # drift between the two most recent # 5. 重新渲染已持久化的扫描，而无需重新触碰 tree： j0witness report ~/.local/state/j0witness --format sarif ``` 构建说明：**[docs/BUILD.md](docs/BUILD.md)**。 ## 退出码（稳定契约） `0` 干净 · `1` 发现结果 >= 中危 · `2` 用法错误 · `3` 预检失败 · `4` 基准线不可用 · `5` 存在多个安装 · `6/7` 版本不支持 / 结论不明确 · `8` 基准线不受信任（存储的基准线与内置目录不匹配） · `10` 内部错误。 ## 范围与诚实的局限性 J0Witness 的范围经过刻意收窄，当您准确了解它能够和不能回答的问题时，它将发挥更大作用。 **它能够妥善回答的问题：**“*磁盘上的文件树是否与已知良好的官方发行版加上已声明的第三方扩展相匹配？如果不匹配，差异在哪里，以及有什么证据？*” **它能检测到的内容：**新增/修改/删除的核心文件；PHP 中的 webshell 和代码混淆模式（启发式、静态）；隐藏在合法安装的扩展中的未声明可执行文件；危险的服务器配置指令；结构性时间戳篡改（`mtime > ctime`）；当您提供数据库导出时的数据库状态异常；以及同一站点两次扫描之间的差异。 **它*不*做的事情——在依赖它之前请阅读此部分：** - **它不执行修复、清理、隔离或恢复。** 它只负责观察和作证。 - **未发现任何异常并不代表站点是干净的。** 它仅仅是关于磁盘的证明，并受到以下各层级能力的限制。 - **它无法察觉仅存在于文件系统之外的入侵**——纯粹的数据库内持久化（除非您提供 `mysqldump`）、内存中/运行时植入的恶意代码，或外部服务中的恶意状态。它不执行实时的进程、网络或内存检查。 - **静态 PHP 分析是启发式的。** 它经过调优以最大程度地减少误报，这意味着它可能会漏掉新型、高度混淆或仅依赖逻辑的后门。它是一个信号，不能作为恶意性或安全性的确凿证明。 - **数据库层绝不连接到实时数据库。** 它只会对您提供的离线 `mysqldump` 进行关联；如果导出数据与磁盘内容不匹配，该层将主动降级并声明不匹配，而不是盲目输出噪音。 - **它的根本判定依据是官方发行版和内置的目录。** 原厂未提供的文件（第三方扩展内部文件、上传文件、用户内容）仅会被归属和上下文化，而不会在其官方包 hash 被缓存的情况下进行深度验证。维护一个针对所有第三方扩展的详尽 hash 目录是**明确不设立的目标**——大多数针对 Joomla 的入侵都是通过存在漏洞的第三方扩展发生的，但是策划并维护覆盖整个扩展生态系统的 hash 数据库将是一项永无止境且吃力不讨好的维护工作，因此被刻意排除在范围之外（参见[路线图](docs/ROADMAP.md)）；只有当您缓存了官方扩展包时，L3 才会对其进行验证。位于您提供的基准线*上游*的供应链入侵超出了它的能力范围（基准线完整性会在扫描时根据内置目录进行验证——参见 L7 / `BASELINE_UNTRUSTED`）。 - **时间层在声明威胁模型（拥有 www-data 权限、无 root 权限的攻击者）下信任 ctime。** 拥有 root 权限、能够重写 ctime 的攻击者可以使其失效；篡改时间戳（将 `mtime` 设为远早于 `ctime`）被明确列为非目标，因为这种行为与正常解压的归档文件无法区分。 - **它只是一个证据来源，而非完整的 IR/EDR/AV 系统。** 请将其视为取证印证工具，而非最终的判定引擎。 **声明的威胁模型（主要）：**拥有 Web 服务器权限（`www-data`）且无 root 权限的攻击者。在该模型下，ctime 是可靠的时间锚点。明确这一假设是为了让读者能够判断其在何种情境下成立。 ## 状态与存储 J0Witness 将数据持久化到**内置的 SQLite 数据库**中（纯 Go 的 `modernc.org/sqlite`——无需 CGO，无需系统库；引擎被直接编译进二进制文件）。您无需进行任何启用操作：每次扫描都会自动写入其中。 数据库文件位于**工作目录**（`--workdir`，默认为 `~/.local/state/j0witness/`）中——绝不存放在代码仓库或被分析的文件树内： - `state.sqlite` —— 基准线注册表（您通过 `baseline add` / `baseline fetch` 摄入的内容）。在不同目标间共享。 - `inv-.sqlite` —— **每个扫描目标对应一个**（以目标路径的 hash 为键）。对该目标的每次扫描都会向 `runs` / `entries` / `observations` 表追加一个*运行记录*。这就是让 `report` 能够重新渲染、让 `diff` 能够**无需重新触碰文件树**进行比较的事件基础介质。 使用 `--workdir` 控制其位置；使用 `j0witness runs ` 列出目标持久化的运行记录。这些文件会随着清单规模的增加而增长，并在多次运行中不断积累——删除 `inv-*.sqlite` 会丢弃该目标的扫描历史（下次扫描时会重新创建）；它绝对不会被写入您正在分析的站点中。 ## 文档 - **[架构](docs/ARCHITECTURE.md)** ([Español](docs/ARQUITECTURA.md)) —— 分层、数据流、信任模型、图表。 - **[构建](docs/BUILD.md)** —— 编译单一静态二进制文件及可重现性保障机制。 - **[路线图](docs/ROADMAP.md)** —— 计划及未来可能开展。 - **[源码](src/)** —— 完整的 Go 源码树。 ## 许可证 本项目基于 MIT 许可证发布——请参阅 [LICENSE](LICENSE)。

标签：EVTX分析, Go, Joomla, Ruby工具, 完整性检查, 库, 应急响应, 数字取证, 日志审计, 自动化脚本