RNT56/RanA

RanA 记录了 AI agent *对你的机器做了什么* — 它运行的每一个进程、写入的每一个文件、读取的每一个凭证、连接的每一台主机 — 并将其写入一个哈希链接、带有签名的账本中，你可以验证、导出、浏览该账本，并通过 agent 进行查询。它直接读取内核，因此能够看透第一方沙箱，并且对 Claude Code、Codex、Gemini CLI、goose、OpenClaw、Hermes 以及你自己构建的任何工具都能产生相同的效果。 它从不读取 prompt 或补全内容。它只记录**行为，而不是想法**。 ``` Already running OpenClaw? curl -fsSL https://raw.githubusercontent.com/RNT56/RanA/main/install/get-rana.sh | sh rana adopt openclaw Open the timeline. That's the intended one-command experience. ``` ## 为什么需要它 如今的每一个 agent 安全工具都是一堵**墙**。沙箱负责阻止。网关负责允许或拒绝网络流量。它们都在回答同一个问题：*agent 可以做这个吗？* 它们都无法回答你在事后那个早上真正面临的问题： 这堵墙是因供应商和模式而异的。Claude Code 只沙箱化 Claude Code。Codex 只沙箱化 Codex。OpenClaw 在设计上自带了一个 `elevated` 绕过机制。没有任何工具会跨 agent 进行监控，也没有任何工具记录这些墙本身放行了什么。只有预防而没有记录意味着每次事件审查都得从零开始 — 而个人 agent 往往会悄无声息地失败： - **Cline，2026年2月**（500万以上用户）— 一条 prompt 注入链窃取了 npm 发布 token 并发布了恶意软件包。 - **OpenClaw CIK 评估**（arXiv 2604.04759）— 部署最广泛的个人 agent 在运行时拥有对 Gmail、Stripe 和文件系统的完全本地访问权限。 RanA 的答案是内核真相：一个 eBPF 收集器记录下可归因于某个 agent 会话的每一次 `exec`、具有写入意图的文件操作、网络流以及凭证文件读取 → 一个不可选的脱敏阶段在写入任何内容之前剥离敏感信息 → 最终结果落入一个哈希链接、Merkle 分段、经过 Ed25519 签名的账本中，你可以对其进行 `verify`（验证）、`export`（导出）、浏览和查询。 ## RanA 是什么，不是什么 | ✓   RanA 是 | ✗   RanA 不是 | |---|---| | 一个跨 agent 的飞行记录仪 | 一个沙箱或防火墙 (v1) | | 基于内核真相 (eBPF)，而非 agent 自我报告 | 一个 MCP 网络代理或 TLS 拦截器 | | 一个由你拥有的、防篡改的签名账本 | 一个云服务 — 没有遥测，没有账号，绝对没有 | | **行为**的记录：执行、文件、网络 | **想法**的记录 — 绝不包含 prompt、补全或按键 | | 可与沙箱组合（记录由 `srt` 包装的 agent） | 它们的替代品 | **只看行为不看想法**的界限既是一种隐私立场，也是一种范围边界：RanA 记录的是 agent 对你的机器做了什么，而不是它说了什么。它之所以*可以安全运行*，正是因为它不会泄露你的对话、prompt 或机密。 ## 快速开始 安装 — 一个静态二进制文件加上一个特权收集器；在 macOS 上，由一个 Linux 客户机镜像执行记录： ``` # Linux (kernel 5.15+, cgroup v2) 或 macOS 13+ (Apple Silicon) curl -fsSL https://raw.githubusercontent.com/RNT56/RanA/main/install/get-rana.sh | sh # 检查您机器的 capability tier（现在可用 — kernel recon） rana doctor ``` ▸  **记录任意 agent 的一次运行** ``` rana run --profile claude-code -- claude rana timeline # localhost UI, token-gated ``` ▸  **接管一个长期运行的 agent**（主要路径） ``` rana adopt openclaw # slots the gateway and all its children into one session rana timeline # watch conversation → consequences, live ``` ▸  **证明记录未被篡改** ``` rana verify # recomputes the whole chain; seconds even at millions of events rana export --session out/ # portable proof pack a third party can verify with no RanA installed ``` ▸  **让 agent 基于记录进行推理** — [`rana-mcp`](./docs/MCP.md) ``` rana-mcp --data ~/.local/share/rana # a read-only MCP server over your ledger ``` 将任意 MCP client 指向它并询问*“哪个记录的会话存在严重警报，并且其链条是否完好？”* — agent 会从已签名、**免秘密**的行为记录中给出答案，永远不会看到 prompt 或凭证。 ## 支持的 agent RanA 在**内核**层进行捕获（每个会话一个 cgroup-v2 叶子节点），因此它能以完全相同的方式记录*任何* agent 的进程树 — `generic` 配置文件无需任何配置即可捕获任何内容。在此基础之上，RanA 提供了经过调优的**配置文件**（识别、摘要范围、凭证监视列表），并且，如果某个框架公开了生命周期钩子，还会提供可选的**标记发射器**，通过 `runId` 将行为与某次运行关联起来（仅限标识符 — 绝不包含 prompt 文本，P7）。 | Agent | 配置文件 | 标记发射器 | |---|---|---| | OpenClaw | ✓ | ✓ (JS gateway 插件) | | Claude Code | ✓ | ✓ (settings.json 钩子) | | Codex (OpenAI CLI) | ✓ | ✓ (config 钩子) | | Gemini CLI (Google) | ✓ | ✓ (SessionStart/End 钩子) | | goose (Block) | ✓ | ✓ (command 钩子) | | Hermes (Nous Research) | ✓ | ✓ (Python 插件) | | OpenCode | ✓ | ✓ (TS 插件) | | Cline | ✓ | ✓ (task 钩子) | | Aider | ✓ | — (不存在生命周期钩子) | | Cursor · 通用 CI · 任何自定义 agent | ✓ / generic | — | 添加一个新 agent 只需一个配置文件（约 10 分钟）加上一个可选的发射器 — 捕获功能本身已经可以直接工作。请参阅 [`docs/PROFILES.md`](./docs/PROFILES.md) 以及 [`plugins/`](./plugins) 中的发射器。 ## 两个值得一看的演示 1. **抓包数据窃取。** 一个有毒的网页试图诱导你的 agent 读取 `~/.ssh/id_ed25519` 并将其 POST 发送出去。在读取凭证的那一刻，RanA 会将其与随后连接到的前所未见的主机关联起来 — 形成“数据窃取前兆”三要素 — 时间线会显示读取操作、新域名以及执行此操作的确切进程链。 2. **可逆的破坏** *(受限模式，1.0 版本之后)*。一个 agent 在写时复制 (copy-on-write) overlay 中执行 `rm -rf`。你打开 `rana diff`，看到它更改的所有内容（不仅是 git 跟踪的文件），提交好的部分，丢弃其余部分。你的机器完全未受影响。 ## 工作原理 **每个会话一个 cgroup v2 叶子节点**是归属判定原语：agent 的整个进程树 — 一个网关生成子 agent，子 agent 再生成工具进程 — 都会被内核继承机制捕获，这就是跨 agent 能够直接运行的原因。 ``` agent process tree ── cgroup: rana.slice/rana-.scope │ ┌──────┴──────────────────────────────────────────────────┐ │ [kernel] eBPF exec · file · connect · sensitive-read │ └──────┬──────────────────────────────────────────────────┘ │ ring buffer ┌──────┴──────────────────────────────────────────────────┐ │ ranad (root) decode → REDACT secrets → rate-govern │ └──────┬──────────────────────────────────────────────────┘ │ unix socket, peer-authenticated ┌──────┴──────────────────────────────────────────────────┐ │ rana session service (your user) │ │ ▸ SQLite ledger + hash chain + Ed25519 checkpoints │ │ ▸ content-digest worker (profile scopes only) │ │ ▸ localhost timeline UI · rana-mcp read API │ └─────────────────────────────────────────────────────────┘ ``` 收集器在构造上是惰性的：没有任何钩子可以阻止、延迟或修改 syscall。如果 `ranad` 崩溃终止，你的 agent 仍会继续运行 — 丢失的窗口会变成一个可见的 `gap` 事件，绝不会是一个悄无声息的黑洞。详见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)。 ## 信任，简述 - **持久化后的完整性** → 任何编辑、删除、重排序或大规模的会话移除都会被 `rana verify` 检测到。 - **免秘密** → 绝不捕获环境变量值；其他所有字符串在哈希处理前都会被脱敏。详见 [`docs/REDACTION.md`](./docs/REDACTION.md)。 - **惰性** → 观察模式无法更改或破坏你的 agent。 - **可移植的证明** → 链规范和独立（以及 WASM/浏览器）验证器已在 [`docs/TRUST.md`](./docs/TRUST.md) 中记录；导出后的数据可以在未安装 RanA 的情况下验证。 客观存在的局限性详见 [`LIMITS.md`](./LIMITS.md)。请务必阅读。 ## 平台支持 | | Linux | macOS | Windows | |---|---|---|---| | **v1** | 原生 eBPF (内核 5.15+, cgroup v2) | 嵌入式 Linux microVM (Apple Virtualization, 以 Apple Silicon 为主) | 非目标 | 原生 macOS 进程记录需要 Apple 案例审批的 Endpoint Security 权限 — 这对开源分发是封闭的。microVM 是唯一的记录路径，并且在其内部运行的是相同的捕获堆栈；该客户机内置了一个 Node.js runtime 层，因此真正的 agent 实际上是在那里运行的，你的配置和工作区会从宿主机映射进去。两个客观限制是：*原生*运行的 macOS agent 根本不会被记录，并且客户机内的 agent 无法驱动原生的 macOS 应用（如 AppleScript、iMessage）。详情见 [`docs/MACOS.md`](./docs/MACOS.md)，原生路径设计见 [`docs/MACOS-NATIVE.md`](./docs/MACOS-NATIVE.md)。 ## 工程姿态 - **每个宿主角色一个静态二进制文件。** 不依赖 Python、Node 或 Docker runtime。纯 Go 编写的 SQLite 和纯 Go 编写的 eBPF 加载器；唯一的 CGO 是用于 macOS 宿主二进制文件。 - **可复现构建**、cosign 签名的发布制品，以及从第一个版本就开始提供 SBOM。没有信息回传，没有后台更新检查。对每个信任边界解析器进行持续的模糊测试，并在 CI 中运行调用图漏洞扫描。 - **严格的 TDD，由门禁强制执行。** 账本可承受每秒 1 万+事件且零丢失 · 脱敏机制在永久的预置秘密语料库上保持 99%+ 的召回率，并设有零原始秘密泄露门禁 · `verify` 可检测出 100% 的链变异。这些都是回归测试门禁，而不是一次性的检查。 ## 文档 - 核心规范 — [`ARCHITECTURE`](./docs/ARCHITECTURE.md) · [`THREAT-MODEL`](./docs/THREAT-MODEL.md) · [`TRUST`](./docs/TRUST.md) · [`REDACTION`](./docs/REDACTION.md) - [`docs/OPENCLAW.md`](./docs/OPENCLAW.md) — 接管流程和因果关系解释 - [`docs/MCP.md`](./docs/MCP.md) — `rana-mcp`：从 agent 查询账本（只读、仅限行为、免秘密） - 平台与流程 — [`MACOS`](./docs/MACOS.md) · [`PROFILES`](./docs/PROFILES.md) · [`SECURITY`](./docs/SECURITY.md) · [`CONTRIBUTING`](./CONTRIBUTING.md) - 设计说明 — [`MULTIUSER`](./docs/MULTIUSER.md) (系统级 ranad) · [`MACOS-NATIVE`](./docs/MACOS-NATIVE.md) (原生 ES 路径) - 贡献者须知 — [`docs/CONTRACTS.md`](./docs/CONTRACTS.md)：构建和测试每一层所依据的包级接口契约 ## 许可证 Apache-2.0。需要 DCO 签名；无 CLA。安全披露：见 [`docs/SECURITY.md`](./docs/SECURITY.md)。

<sub>rana is Latin for frog. It sits on the lilypad. It sees everything. It does not interfere.

Nothing was blocked that shouldn't have been · Nothing happened that wasn't recorded · Nothing left that wasn't seen · And every byte of proof belongs to you.</sub>

标签：AI代理监控, Docker镜像, EVTX分析, Go, Ruby工具, 审计日志, 数字取证, 日志审计, 自动化脚本, 防篡改账本