diff --git a/.agent/PROJECT_STATE.md b/.agent/PROJECT_STATE.md index 1129070..2a76020 100644 --- a/.agent/PROJECT_STATE.md +++ b/.agent/PROJECT_STATE.md @@ -4,18 +4,20 @@ Last updated: 2026-08-11 ## Current phase -Bootstrap foundation validated and stabilized with a real Rust toolchain. Architecture, collaboration workflow, community scaffolding, lockfile, deterministic fixtures, and the minimal Rust workspace are ready for initial-commit review; real Windows collection remains the next engineering phase. +The public repository foundation is complete. The initial commit is on `origin/main`, the first GitHub CI run passed, and the repository's baseline security and branch rules are active. The current phase is pre-collector hardening before implementation of the first real Windows Collector. ## Implemented components - Durable product, architecture, roadmap, threat-model, and ADR documentation. - Project-scoped Codex agents and three repeated-workflow skills. -- GitHub community templates, baseline CI design, and dependency update policy. +- Public GitHub repository `XiaojuCH/SystemDiff`, community templates, baseline CI, and dependency update policy. - A draft v1 domain/schema skeleton, deterministic diff boundary, JSON/terminal reporting boundary, rule interface, Windows collector descriptors, and CLI fixture-diff path. - Root `Cargo.lock` generated with Cargo 1.97.1; CI mirrors the local format, Clippy, test, and CLI fixture smoke commands. - The workspace passes rustfmt, Clippy with warnings denied, all-target workspace tests, and the three documented CLI fixture/status commands on stable `x86_64-pc-windows-msvc` (`rustc 1.97.1`). +- The first GitHub CI run passed on Windows and Ubuntu. The active `main` ruleset requires pull requests, resolved review threads, and the `Rust (windows-latest)` and `Rust (ubuntu-latest)` checks; it blocks deletion and non-fast-forward updates while retaining an explicit maintainer bypass. +- GitHub Secret Scanning, Push Protection, and Private Vulnerability Reporting are enabled. - Registry evidence keeps the native type code, validated typed decode status/value, a full-content SHA-256, and an optional validated 4 KiB lowercase-hex raw prefix rather than assuming every value is a UTF-16LE string. -- Final independent initial-commit review reports no remaining high- or medium-severity findings. +- The bootstrap foundation has passed real-toolchain validation and independent architecture, security, and maintainability review. ## Known limitations @@ -25,8 +27,9 @@ Bootstrap foundation validated and stabilized with a real Rust toolchain. Archit - Redaction metadata exists in the schema, but sanitization is not implemented. - The bootstrap CLI currently reads an entire JSON file before validation; header-first version routing, RFC 3339 timestamp validation, and input resource limits are not implemented. - Draft fixtures and wire types may change before v0.1; after v0.1, v1 compatibility becomes a release obligation. -- No GitHub remote, repository owner, private security contact, or conduct-reporting contact has been configured. -- No CODEOWNERS file is committed until a real repository owner/team with write access is known. +- Draft v0.1 diffs assume the same Windows installation and the same user/principal context. Cross-host and cross-user identity are out of scope; no SID hash, machine token, or identity framework exists. +- No dedicated private Code of Conduct reporting channel is published. GitHub Private Vulnerability Reporting is available only for product security reports. +- No CODEOWNERS file is committed during the solo-maintainer stage. ## Decisions affecting current work @@ -35,18 +38,20 @@ Bootstrap foundation validated and stabilized with a real Rust toolchain. Archit - Snapshot and diff JSON are separately versioned documents with deterministic serialization expectations. - Collector failures and privilege limitations are recorded per collector/scope and must not invalidate unrelated evidence. - Unknown cross-version comparisons for the same Collector ID are rejected by default; future explicitly verified compatible version pairs remain possible, but no compatibility framework exists yet. +- v0.1 comparison is limited to before/after snapshots from the same Windows installation and user/principal context. - SystemDiff remains offline-first and read-only; evidence is never executed or remediated. -- Apache-2.0 is the initial repository license choice, pending maintainer confirmation before public launch. +- Apache-2.0 is the repository license. +- Normal changes to `main` go through pull requests and the active required checks; maintainer bypass is reserved for exceptional recovery. ## Next milestone -After maintainer approval and the initial commit, specify and implement the registry Run/RunOnce Collector and real `snapshot` CLI path behind deterministic data-source abstractions, including 32/64-bit Registry view coverage, permission/partial outcomes, fixtures, and non-elevated tests. +Complete the focused pre-collector hardening work: bounded snapshot input, document-header routing, UTC RFC 3339 validation, explicit Registry view semantics, and correct structured RunOnce prefix evidence. Only then specify and implement the first real Registry Run/RunOnce Collector and `snapshot` CLI path. ## Major unresolved questions -- What GitHub organization/user will own the public repository and future CODEOWNERS entries? -- What private contact should receive security and Code of Conduct reports? +- What genuine, monitored private channel should receive Code of Conduct reports? - What minimum supported Windows versions and architectures will v0.1 promise? - Which Registry value types or decode failures warrant including the optional raw prefix rather than only typed evidence plus the full-content hash? +- What bounded/archive policy should apply to Scheduled Task raw XML before that Collector is implemented? - What minimum supported Rust version will be tested and documented? - Should the first desktop spike confirm React/Vite or compare one smaller frontend alternative before accepting ADR 0003? diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 30740d7..26c86a5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -58,11 +58,12 @@ representative at an online or offline event. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported using the private-contact procedure in `SECURITY.md`. Do not include -sensitive personal details in a public issue. Before public launch, the -maintainer must publish a real private conduct-reporting channel; no placeholder -email address is presented as monitored. +SystemDiff does not currently publish a dedicated private conduct-reporting +channel. GitHub Private Vulnerability Reporting and the process in `SECURITY.md` +are reserved for product security and must not be used for conduct or harassment +reports. Do not disclose sensitive personal information in a public Issue. A +genuine, monitored private channel remains an open governance task, and this +document will be updated when one is available. All complaints will be reviewed and investigated promptly and fairly. Community leaders are obligated to respect the privacy and security of the diff --git a/README.md b/README.md index e2f930d..b2e7cb7 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ [English](README.md) | [简体中文](README.zh-CN.md) +[![CI](https://github.com/XiaojuCH/SystemDiff/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/XiaojuCH/SystemDiff/actions/workflows/ci.yml) + **SystemDiff shows what changed on a Windows system, with plain-language explanations backed by inspectable evidence.** > [!IMPORTANT] @@ -65,6 +67,8 @@ systemdiff diff before.json after.json The `snapshot` command is intentionally not implemented in the bootstrap. v0.1 will be complete only when this pipeline works reliably. +The draft v0.1 comparison model assumes that both snapshots come from the same Windows installation and the same user/principal context. Cross-host and cross-user identity are intentionally out of scope. + ## MVP scope | Collector | v0.1 scope | Current status | @@ -115,4 +119,4 @@ SystemDiff is defensive auditing software. Credential dumping, token/cookie extr ## License -Licensed under the [Apache License 2.0](LICENSE). The maintainer should confirm this governance choice before public launch. +Licensed under the [Apache License 2.0](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index d7e51eb..738ee64 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,22 +2,22 @@ [English](README.md) | [简体中文](README.zh-CN.md) -**SystemDiff 用可检查的底层证据和清晰易懂的解释，告诉你 Windows 系统究竟发生了哪些变化。** +**SystemDiff 帮你看清 Windows 系统发生了什么变化——每一条结论都附带可查证的证据。** > [!IMPORTANT] -> SystemDiff 目前处于仓库 bootstrap 阶段，尚无面向最终用户的 release，也还没有任何真正调用操作系统 API 的 Collector。当前代码只用于证明 draft schema、确定性 Diff、报告与贡献边界；它现在还不是一个有效的系统扫描工具。 +> SystemDiff 目前处于项目搭建阶段，尚无可分发的正式版本，也没有真正调用操作系统 API 的 Collector。当前代码仅用于验证 schema 草案、确定性 Diff、报告生成和贡献流程；它现在还不是一个能用的系统扫描工具。 -## 为什么需要 SystemDiff？ +## 为什么要做 SystemDiff？ -核心流程刻意保持简单： +核心流程很简单： -1. 获取 Snapshot A。 -2. 安装、运行或修改某项内容。 -3. 获取 Snapshot B。 -4. 比较两份 Snapshot。 -5. 准确理解发生了什么变化。 +1. 创建快照（Snapshot）A。 +2. 安装、运行或改动一些东西。 +3. 创建快照 B。 +4. 对比两份 Snapshot。 +5. 看清楚到底变了什么。 -普通用户应该看到克制、易懂的说明： +普通用户看到的应该是克制、好懂的说明： ```text 需要较高关注 @@ -36,23 +36,23 @@ ExampleApp 设置 通常无害 ``` -以上只是展示目标，并不代表当前已经具备相应检测能力。高级用户未来可以检查准确的注册表路径、服务/任务配置、原始 before/after 值、Collector 与 rule ID、结构化 JSON，以及在支持后查看哈希和签名元数据。 +以上只是效果示意，不代表目前已有对应的检测能力。后续高级用户将能够查看精确的注册表路径、服务/任务配置、变更前后的原始值、Collector 和 rule ID、结构化 JSON，以及（在支持后）哈希和签名元数据。 -SystemDiff 不会把“少见”直接等同于“恶意”。解释建立在证据之上，绝不替代证据。 +SystemDiff 不会把“不常见”直接等同于“恶意”。解释始终建立在证据之上，而不是取代证据。 -## 信任基础 +## 信任模型 -- **Offline-first：** 核心扫描、Diff 和报告均在本地完成。 -- **无需账号：** 本地使用不要求注册。 -- **MVP 无 telemetry：** 默认不上传系统数据。 -- **只读：** SystemDiff 负责观察和报告，不会自动清理或修复系统。 -- **平稳处理权限：** 无法访问的范围会明确标为 partial 或 permission denied，而不是被隐藏。 -- **Evidence-first：** JSON 格式有明确版本且输出确定；未来 GUI 不会隐藏原始证据。 -- **重视隐私：** 真实 Snapshot 可能含敏感信息，未经检查或脱敏不得分享。 +- **离线优先：** 核心扫描、Diff 和报告全部在本地运行。 +- **无需账号：** 本地使用无需注册。 +- **MVP 不含遥测：** 默认不会上传系统数据。 +- **只读：** SystemDiff 只观察、只报告，不会自动清理或修复系统。 +- **明确报告权限限制：** 无法访问的部分会明确标记为 `partial` 或 `permission denied`，不会悄悄忽略。 +- **证据优先：** JSON 格式带有版本号且输出可复现；后续 GUI 不会隐藏原始数据。 +- **注意隐私：** 真实 Snapshot 可能包含敏感信息，未经审查或脱敏处理前不得分享。 -请参阅[产品原则](docs/product-principles.md)和[威胁模型](docs/threat-model.md)。 +详见[产品原则](docs/product-principles.md)和[威胁模型](docs/threat-model.md)。 -## 计划中的 v0.1 工作流 +## v0.1 计划流程 ```powershell systemdiff snapshot -o before.json @@ -63,56 +63,58 @@ systemdiff snapshot -o after.json systemdiff diff before.json after.json ``` -bootstrap 阶段刻意没有实现 `snapshot` 命令。只有这条完整链路能够可靠工作，v0.1 才算完成。 +`snapshot` 命令在搭建阶段有意没有实现。v0.1 只有在整条链路稳定工作后才算完成。 + +v0.1 的 Diff 只用于比较同一套 Windows 系统、同一用户/主体上下文中的 before/after Snapshot；跨主机或跨用户身份关联不在当前范围内。 ## MVP 范围 | Collector | v0.1 范围 | 当前状态 | | --- | --- | --- | -| 注册表启动项 | 官方文档中的 Run/RunOnce 位置及正确 Registry view | 计划中 | -| Windows 服务 | 稳定的 Win32 服务配置；不包含 driver | 计划中 | -| 计划任务 | Task Scheduler 2.0 配置及权限感知的 coverage | 计划中 | +| 注册表启动项 | 官方文档列出的 Run/RunOnce 位置，并正确处理注册表视图（Registry view） | 计划中 | +| Windows 服务 | 稳定的 Win32 服务配置；不含驱动 | 计划中 | +| 计划任务 | Task Scheduler 2.0 配置，并明确显示因权限不足造成的覆盖缺口 | 计划中 | -全盘哈希、自动 remediation、telemetry、云端分析和大型桌面 GUI 均不属于 v0.1 范围。 +全盘哈希、自动修复、遥测、云端分析和大型桌面 GUI 均不在 v0.1 范围内。 -## 开发者快速开始 +## 开发者快速上手 Windows 前置条件： -- Git； -- 安装 `rustfmt` 与 `clippy` 的 stable Rust MSVC toolchain； -- Microsoft C++ Build Tools（Desktop development with C++）； -- WebView2 仅在未来引入 Tauri 桌面端时需要。 +- Git +- 安装了 `rustfmt` 和 `clippy` 的 stable Rust MSVC toolchain +- Microsoft C++ Build Tools（“使用 C++ 的桌面开发”工作负载） +- WebView2（仅在未来引入 Tauri 桌面应用时需要） ```powershell cargo fmt --all --check cargo clippy --locked --workspace --all-targets -- -D warnings cargo test --locked --workspace --all-targets -# 使用 synthetic fixtures 运行当前已有的确定性 Diff/报告链路。 +# 使用 synthetic fixture 运行当前已有的确定性 Diff / 报告链路。 cargo run --locked -p systemdiff-cli -- diff fixtures/snapshots/before-v1.json fixtures/snapshots/after-v1.json cargo run --locked -p systemdiff-cli -- diff --json fixtures/snapshots/before-v1.json fixtures/snapshots/after-v1.json cargo run --locked -p systemdiff-cli -- collectors ``` -本 bootstrap workspace 已使用真实的 stable Rust MSVC toolchain 完成验证。实际验证状态及仍未实现的产品能力记录在 [.agent/PROJECT_STATE.md](.agent/PROJECT_STATE.md) 中。 +本 workspace 已在真实的 stable Rust MSVC toolchain 下验证通过。确切的验证状态和剩余产品限制见 [.agent/PROJECT_STATE.md](.agent/PROJECT_STATE.md)。 ## 架构 -Rust workspace 将 domain/schema、Windows 访问、确定性 Diff、rules、reports 和 CLI 组装分离。未来 Tauri 桌面端会复用同一个 Rust core。Tauri 2 + React + TypeScript 目前只是 Proposed 决策，尚未正式采纳或生成应用。 +Rust workspace 将领域模型/schema、Windows 系统访问、确定性 Diff、规则、报告生成和 CLI 组装各自分离。未来的 Tauri 桌面客户端将复用同一个 Rust core。Tauri 2 + React + TypeScript 目前仅为提议方案，尚未正式采纳或生成代码。 -建议从[架构](docs/architecture.md)、[数据格式](docs/data-format.md)、[Collector 说明](docs/collectors.md)和[路线图](docs/roadmap.md)开始阅读。 +建议从以下文档入手：[架构](docs/architecture.md)、[数据格式](docs/data-format.md)、[Collector 说明](docs/collectors.md)和[路线图](docs/roadmap.md)。 ## 参与贡献 -英文或中文贡献都很欢迎。有价值的贡献不局限于 Rust：文档、翻译、synthetic fixtures、Windows API 研究、隐私分析、问题复现和 UI 设计都很重要。 +欢迎使用中文或英文参与贡献。有价值的贡献不限于 Rust 代码：文档、翻译、synthetic fixture、Windows API 调研、隐私分析、问题复现和 UI 设计都很重要。 -请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [Collector 贡献指南](docs/contributing-collectors.md)。请勿在 public issue 中附上未经检查的真实 Snapshot 或日志。 +请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [Collector 贡献指南](docs/contributing-collectors.md)。请勿在公开 Issue 中附带未经审查的真实 Snapshot 或日志。 ## 安全与项目边界 -SystemDiff 是防御性审计软件。凭据转储、token/cookie 提取、键盘记录、创建持久化、绕过 AV/EDR、隐蔽/C2、自动化利用和未授权访问工具均不属于项目范围。详情参阅 [SECURITY.md](SECURITY.md)。 +SystemDiff 是面向防御的审计工具。凭据转储、token/cookie 提取、键盘记录、创建持久化、绕过 AV/EDR、stealth/evasion 工具、RAT/C2 功能、自动化漏洞利用和未授权访问工具均不属于本项目范围。详见 [SECURITY.md](SECURITY.md)。 ## 许可证 -本项目使用 [Apache License 2.0](LICENSE)。在公开发布前，maintainer 仍应确认这一治理选择。 +本项目基于 [Apache License 2.0](LICENSE) 授权。 diff --git a/SECURITY.md b/SECURITY.md index 4f54ff6..2b5817c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,9 @@ SystemDiff has no public release yet. The bootstrap code and draft schema do not Do not include vulnerability details, real snapshots, task XML, tokens, personal data, or sensitive logs in a public issue. -The public repository must enable GitHub Private Vulnerability Reporting before launch. Until a private channel is published, use a private channel you already have with the maintainer. If none exists, open a minimal public issue asking the maintainer to establish private contact, without disclosing technical details. +Report product security vulnerabilities through [GitHub Private Vulnerability Reporting](https://github.com/XiaojuCH/SystemDiff/security/advisories/new), which is enabled for this repository and is the preferred private reporting channel. + +Private Vulnerability Reporting is for product security vulnerabilities only. It is not a Code of Conduct, harassment, or other community-conduct reporting channel. Include, when safe: