Aeptus/aegiuw

# Aegiuw Aegiuw 通过对每个出站 HTTPS 连接做出单一决策来保护用户免受网络钓鱼和中间人攻击：**这个域名受信任吗？** - **受信任** → 连接直接桥接到网卡。原生浏览器正常连接，延迟开销 `<15ms` (NFR-4.1)。 - **未知 / 可疑** → 连接被拦截，页面在一次性、无界面的云端浏览器中渲染。只有渲染后的输出被流式传输回本地只读查看器。凭证在物理上绝对无法到达攻击者手中，因为在沙箱内部已经切断了在密码字段中的输入操作 (FR-3.2)。 这是成熟的**远程浏览器隔离 (RBI)**模式，其有两个显著特征：基于本地 SNI 的流量*分流*，以及在凭证收集表单上的*键盘断连*。 ## 状态 🚧 **早期框架。** 仓库结构、构建系统和组件边界已就绪。核心逻辑已通过清晰的 `TODO` 进行打桩，并与 PRD 需求 ID（例如 `FR-2.1`）相关联。完整产品规范请参见 [`docs/PRD.md`](docs/PRD.md)。 ## 架构 分为三层，刻意解耦： | 层级 | 组件 | 技术栈 | 位于 | |-------|-----------|-------|----------| | 1. 本地代理 | `aegiuw-daemon` | 原生 Rust (Win/macOS/Linux) | `crates/aegiuw-daemon` | | — 风险逻辑 | `aegiuw-core` | 纯 Rust (lib, WASM-friendly) | `crates/aegiuw-core` | | 2. 边缘路由器 | `aegiuw-router` | 运行于 Cloudflare Workers 的 TypeScript | `workers/aegiuw-router` | | 3. 沙箱 | `aegiuw-cage` | Cloudflare Browser Rendering | (由路由器驱动) | ``` native browser ──► aegiuw-daemon ──┬─(trusted)──► NIC ──► internet (port 443 via TUN) │ └─(unknown)──► aegiuw-router (Worker) └──► ephemeral sandbox └─► read-only stream ──► local viewer ``` ## 仓库布局 ``` . ├── crates/ │ ├── aegiuw-core/ # pure risk heuristics: Levenshtein, context, SNI parsing, verdicts │ └── aegiuw-daemon/ # privileged background agent (TUN, fork logic) — depends on aegiuw-core ├── workers/ │ └── aegiuw-router/ # Cloudflare Worker: stateless traffic controller + sandbox orchestration └── docs/ └── PRD.md # product requirements (source of the FR-/CR-/NFR- IDs referenced in code) ``` ## 快速入门 ### 本地代理 ``` cargo build # build the workspace cargo test # run aegiuw-core unit tests cargo run -p aegiuw-daemon ``` ### 边缘路由器 ``` cd workers/aegiuw-router npm install npm run typecheck # tsc --noEmit npm run dev # local Worker via wrangler # 要部署，您必须首先创建 bound resources 并将其 ID 粘贴 # 到 wrangler.jsonc 中（请参阅该文件中的注释）： # npx wrangler kv namespace create LOCAL_SAFE_CACHE # npx wrangler r2 bucket create aegiuw-quarantine-vault npm run deploy # wrangler deploy (FR-1.1: single-command edge deploy) ``` ### 模糊测试 SNI 解析器 ``` rustup toolchain install nightly # one-time cargo install cargo-fuzz # one-time cd crates/aegiuw-core/fuzz cargo +nightly fuzz run extract_sni -- -max_total_time=10 -timeout=1 ``` 三个目标涵盖了 `extract_sni`、`reassemble_handshake` 和 `parse_handshake_message`。完整的说明以及“发生崩溃时的应对措施”操作手册位于 [`crates/aegiuw-core/fuzz/README.md`](crates/aegiuw-core/fuzz/README.md) 中。 ### 质量门禁 ``` npm run hooks:install # one-time: points core.hooksPath at hooks/ npm run quality:staged # what pre-commit runs npm run quality:prepush # what pre-push runs (scoped to push range) npm run quality:local # everything, repo-wide npm run test:quality # unit tests for the runner/registry ``` 经过深思熟虑，我们没有使用 GitHub Actions CI（基于组织政策 + 仓库规模较小）。这些门禁会在本地和 hooks 中运行。完整架构：[`docs/quality-gates.md`](docs/quality-gates.md)。 ## 已知注意事项 (如实声明) 这些是 PRD 文字描述中掩盖的现实世界限制；它们影响的是具体的实现方式，而非可行性。 - **加密 ClientHello (ECH)：** 当连接使用 ECH（对服务器名称进行加密）时，SNI 提取 (FR-1) 会静默失败。此类连接将回退到隔离路径或单独的策略——它们无法通过 SNI 进行分类。 - **“`<1ms`” 验证：** 亚毫秒级的数值 (CR-1.1) 仅仅是指在隔离环境中的 `crypto.subtle.verify` 耗时。守护进程的实际物理延迟包含了到边缘的网络往返时间（数十毫秒）。 - **沙箱流式传输：** Cloudflare Browser Rendering 暴露的是 Puppeteer/CDP + screencast，而不是一个交钥匙的 “KasmVNC 向量管线”。FR-3.1 的流是基于 CDP 之上的通过 WebSocket 传输的 screencast。 - **住宅代理伪装 (CR-2.2)：** 仅限商业用途，并且在发布前需要进行法律 / 服务条款审查——通过住宅代理路由流量以规避机器人检测通常会违反提供商的条款。 ## 许可协议 **核心引擎**（`crates/`, `workers/aegiuw-router/`）采用 [GNU Affero General Public License v3.0 or later](LICENSE) 进行授权。这是一个强 Copyleft 许可证：任何修改 Aegiuw 并通过网络提供服务的人，都必须向该网络的用户提供修改后的源代码 (AGPL §13)。 **Aegiuw-Enterprise** 商业层（计费、热池、托管威胁情报、SIEM 流式传输）根据单独的商业条款分发，**不受** AGPL 的约束。请参见 [`NOTICE`](NOTICE)。

标签：可视化界面, 暗色界面, 程序员工具, 通知系统, 高对比度