CANarchy

一款流优先的 CAN bus 工具包，专为分析师、安全研究人员和 AI agent 设计。
每个命令都会输出类型化的、机器可读的事件，你可以对其进行 pipe、script 操作，或直接交给 agent —— 并将 J1939 重型车辆支持作为一等公民。

## 什么是 CANarchy？ CANarchy 是一个 CLI 优先的 runtime，用于捕获、解码和操作 CAN 和 CAN-FD 流量。大多数 CAN 工具都迫使你做出权衡：要么是交互式的但难以自动化，要么是可编写脚本的但过于原始，或者是支持协议的但跨接口不一致。CANarchy 的构建理念则截然相反 —— **每个输出都是类型化事件的流**（`--json`、`--jsonl`、`--text`），你可以对其进行解析、pipe 或通过 MCP 转发给 LLM agent。 它适合以下人群： - **安全研究人员**：逆向分析未知 bus、fuzzing ECU 或对比捕获的数据以查找异常。 - **重型车辆 / J1939 工程师**：需要进行 PGN/SPN 解码、TP 重组和 DM1 故障解析，而不想退回到处理原始 ID。 - **构建自动化或 AI agent**：需要一个稳定的、机器可读的 CAN 接口，而不是去抓取人类格式的文本。 ## 安装 ``` pipx install canarchy # isolated, on PATH everywhere # 或： pip install --user canarchy ``` 需要 Python 3.12+。实时 transport 使用 [`python-can`](https://python-can.readthedocs.io/)（socketcan、虚拟 bus、UDP 多播等）。 ## 60 秒试用 —— 无需硬件 ``` canarchy --version canarchy doctor --text # 8 offline health checks; all green = good install # 从 deterministic scaffold backend 流式传输 typed events —— # 无需硬件，无需 fixtures，无需网络。这是 JSONL 合约： CANARCHY_TRANSPORT_BACKEND=scaffold canarchy capture can0 --jsonl ``` 等你有了真实接口，再将其指向该接口： ``` canarchy capture can0 --candump # human-friendly live view canarchy capture can0 --jsonl | jq . # typed events, one per line ``` 喜欢可视化探索？启动**全屏 TUI**（如上图所示）并实时观察 bus： ``` canarchy tui # /capture to stream; /filter, /sort, /help ``` ## 为什么选择 CANarchy？ [event schema](docs/event-schema.md) 是稳定的契约；CLI 只是对其进行了封装。正是这一设计决策让 CANarchy 在大多数开源 CAN 工具中脱颖而出： - **结构化输出是核心契约，而非事后补充。** 每个命令 —— 捕获、解码、fuzz、逆向工程 —— 都会输出相同的标准化 JSON 信封。一次解析，处处复用。 - **Pipe 优先。** `--jsonl` 按行流式传输类型化事件，因此 `| jq`、`| grep` 或下游脚本可以无缝工作。 - **J1939 是一等公民。** PGN 解码、SPN 提取、TP 会话重组和 DM1 故障解析会从内置的 SAE 目录中解析名称，而不仅仅是原始仲裁 ID。 - **Agent 就绪。** 内置的 [MCP](https://modelcontextprotocol.io/) server 将工具包暴露给 Claude 及其他 MCP 客户端，以便 agent 可以直接驱动 CAN 分析。 | | CANarchy | 典型的 CAN CLI 工具 | |---|:---:|:---:| | 作为核心契约的结构化输出 | ✅ | ✗ / 部分 | | 支持 pipe 的类型化事件流 | ✅ | 部分 | | Provider 支持的 DBC 发现与缓存 | ✅ | ✗ | | J1939 优先的操作工作流 | ✅ | 部分 | | MCP / agent 集成 | ✅ | ✗ | 请参阅完整的 [CAN 工具功能矩阵](docs/feature-matrix.md)，了解与 can-utils、SavvyCAN、Caring Caribou、TruckDevil 等工具的客观的并排比较。 ## 你可以用它做什么？ ``` # 针对 DBC 解码 capture canarchy decode --file trace.candump --dbc vehicle.dbc --jsonl # J1939 heavy-vehicle 分析 canarchy j1939 decode --file trace.candump --text canarchy j1939 spn 110 --file trace.candump --text # Engine Coolant Temp canarchy j1939 dm1 --file trace.candump --text # active fault codes # 逆向工程未知 bus：对可能的 signals、counters、anomalies 进行排序 canarchy re signals --file trace.candump --jsonl canarchy re anomalies --file trace.candump --baseline known_good.candump --jsonl # 按 arbitration ID 对比两次 capture（速率/时序/熵差值） canarchy compare before.candump after.candump --json # 活动工作流（受 active-transmit safety model 约束；--dry-run 可安全地进行计划） canarchy generate can0 --count 10 --gap 50 --id 7DF --jsonl canarchy replay --file trace.candump --rate 2.0 --json # 将 events 直接 pipe 到下游工具 canarchy j1939 spn 110 --file trace.candump --jsonl \ | jq '[.payload.value, .payload.units, .payload.timestamp]' ``` ## 通过 AI agent 驱动 (MCP) CANarchy 内置了 [Model Context Protocol](https://modelcontextprotocol.io/) server，因此 LLM agent 可以通过 CLI 使用的相同结构化契约来捕获、解码和分析 CAN 流量。 ``` canarchy mcp install --client claude-desktop # or: --client claude-code canarchy mcp serve # or run the stdio server directly ``` 主动传输工具需要明确的确认，因此 agent 不会意外地将帧发送到活动的 bus 上。请参阅[主动传输安全设计](docs/design/active-transmit-safety.md)。 ## 全屏 TUI `canarchy tui` 会打开一个交互式的全屏仪表板，实时流式传输 bus 数据： - **实时面板：** 实时流量、解码信号、J1939（摘要边栏 + 最新表）、UDS 事务，以及仅追加的告警日志。 - **后台捕获：** `/capture ` 开始流式传输；`/stop`（或 `x`）停止。 - **交互式：** `/filter `、`/sort `、方向键行导航、`space` 暂停数据流、`[`/`]` 调整 backlog 大小、`ctrl+f` 最大化面板。 - 在提示符下输入任何真实的 CANarchy 命令 —— 它将通过共享解析器运行并整合到面板中。

完整命令目录（点击展开）

已完全实现并经过测试： **Transport** - `capture`, `send`, `filter`, `stats` —— 包含实时 `python-can` 和确定性 scaffold backend 的 transport 工作流；`stats` 报告每个 ID 的频率/时序、DLC 分布以及 bus 负载估算 - `compare` —— 按仲裁 ID 对比两个或多个普通 CAN 捕获：帧数/速率增量、周期时间漂移、相对 baseline 的 payload 熵增量，每个 ID 均带有标记（rate-drop、rate-spike、entropy-collapse、timing-drift、new/dropped） - `capture-info` —— 无需加载每一帧即可快速获取捕获元数据 - `generate` —— cangen 风格的帧生成（固定、随机、递增） - `simulate` —— 确定性的、基于 profile 的经典 CAN、J1939 和 DM1 流量混合（无需硬件） - `gateway` —— 在两个接口之间桥接帧（单向和双向） - `replay`, `sequence replay` —— 基于 candump 文件的确定性回放规划，以及 YAML/JSON 多消息协调传输 **数据库 (DBC / ARXML / KCD / SYM，通过 cantools)** - `decode`, `encode` —— 基于数据库的信号解码/编码；`encode` 解析 SAE PGN/SPN 显示名称以用于往返操作 - `dbc inspect`（包括 `--layout`, `--search`），`dbc signals` —— 数据库和信号检查 - `dbc convert` —— 在 DBC / KCD / SYM 之间转换数据库 - `dbc generate-c` —— 从数据库生成 C 源码/头文件/fuzzer - `dbc provider list`, `dbc search`, `dbc fetch`, `dbc cache list|prune|refresh` —— 基于 provider 的 DBC 发现和缓存工作流 **J1939** - `j1939 monitor`, `decode`, `pgn`, `spn`, `tp`, `dm1`, `faults`, `summary`, `inventory`, `compare`, `map` —— 涵盖实时、文件支持和解码视图的操作工作流；faults 从内置的 SAE 目录中解析 SPN 名称和 FMI 描述 **UDS** - `uds scan`, `trace`, `services`, `subservices`, `ecu-reset`, `tester-present`, `security-seed`, `dump-dids`, `read-memory`, `auto` —— 诊断发现和主动工作流 **逆向工程** - `re signals`, `re counters`, `re entropy` —— 基于文件的候选排名，附有 J1939 PGN/源地址上下文注释，支持感知 transport protocol - `re correlate` —— 将候选字段与带时间戳的参考序列进行关联 - `re anomalies` —— 帧间时序和意外/丢失 ID 的异常检测；针对 baseline，它还会标记每个 ID 的速率下降/激增（抑制/注入）和 payload 熵崩溃（平稳/冻结值攻击） - `re corpus` —— 跨捕获覆盖率、周期时间漂移和信号稳定性分析 - `re match-dbc`, `re shortlist-dbc` —— 基于 provider 的、针对捕获数据的 DBC 候选排名 **数据集** - `datasets provider list`, `search`, `inspect`, `fetch`, `download`, `cache list|refresh` —— 公共 CAN 数据集 provider 工作流 - `datasets convert`, `stream`, `replay` —— 数据集转换和有界流式传输/回放 **其他 transport 上的诊断** - `doip discovery`, `services`, `ecu-reset`, `tester-present`, `security-seed`, `dump-dids` —— DoIP UDP 发现和主动诊断工作流 - `xcp scan`, `info`, `dump` —— XCP slave 发现、能力审查和有界内存转储 **可视化、前端和扩展** - `plot` —— 将信号时间序列图输出为 PNG/SVG/HTML (`pip install canarchy[plot]`) - `web serve` —— 基于 JSONL 信封的只读浏览器仪表板 (HTTP + WebSocket) - `shell` —— 交互式 REPL 和 `--command` 脚本模式 - `tui` —— 带有后台实时捕获的全屏终端仪表板 - `plugins list|info|enable|disable` —— Python entry-point 插件发现和开关 - `skills provider list`, `search`, `fetch`, `cache list|refresh` —— 仓库支持的 CANarchy 技能发现、缓存和出处追踪 **主动传输 fuzzing**（受[主动传输安全设计](docs/design/active-transmit-safety.md)控制；`--dry-run` 是安全的规划路径） - `fuzz payload`, `fuzz replay`, `fuzz arbitration-id`, `fuzz identify` —— payload/重放/ID 遍历 fuzzing，并将 fuzz 日志二分定位至问题帧 - `fuzz signal`, `fuzz spn` —— 感知 DBC 信号和 J1939-SPN 的变异，带有 sentinel 覆盖率 - `fuzz guided` —— 带有持久化 seed 语料库的、基于响应反馈的覆盖率引导 fuzzing **会话、导出和实用工具** - `session save`, `load`, `show` —— 会话管理 - `export` —— 结构化产物导出 - `doctor` —— 本地环境健康检查 (Python, `python-can`, vendor backend, 缓存, MCP, 配置) - `mcp serve`, `mcp install` —— Model Context Protocol server 和客户端配置助手 - `completion {bash,zsh,fish}` —— 输出 shell 补全脚本 - `--log-level`, `--quiet` —— 全局 stderr 日志记录控制（放在子命令之前） 默认的 transport backend 是 `python-can`；设置 `CANARCHY_TRANSPORT_BACKEND=scaffold` 可获得确定性的离线行为。

## 结构化契约 每个成功的命令都会返回一个稳定的信封： ``` { "ok": true, "command": "capture", "data": {}, "warnings": [], "errors": [] } ``` 失败将返回带有可操作提示的结构化错误（以及文档化的[错误代码目录](docs/troubleshooting.md)）： ``` { "ok": false, "command": "decode", "data": {}, "warnings": [], "errors": [ { "code": "DBC_LOAD_FAILED", "message": "Failed to parse DBC file.", "hint": "Validate the DBC syntax and line endings." } ] } ``` 使用 `--candump` 获取面向人类的实时视图；在为脚本或 agent 提供数据时使用 `--jsonl` —— 每一行都是来自[标准化 schema](docs/event-schema.md) 的类型化事件。设置 `CANARCHY_PYTHON_CAN_INTERFACE` 以选择接口类型，或设置 `CANARCHY_TRANSPORT_BACKEND=scaffold` 以获得确定性的离线行为。 ## 文档 - [入门指南](docs/getting_started.md) · [实用手册](docs/cookbook/index.md) —— 面向任务的方案 - [Event Schema](docs/event-schema.md) —— 所有结构化输出的标准化信封 - [命令规范](docs/command_spec.md) · [架构](docs/architecture.md) - [CAN 工具功能矩阵](docs/feature-matrix.md) —— 与其他开源 CAN 工具的比较 - [J1939 重型车辆演示](docs/tutorials/j1939_heavy_vehicle.md) · [故障排除](docs/troubleshooting.md) - 完整文档站点：**[hexsecs.github.io/canarchy](https://hexsecs.github.io/canarchy/)** ## 从源码安装（开发） CANarchy 使用 [`uv`](https://docs.astral.sh/uv/) 进行环境、依赖项和打包工作流管理。 ``` git clone https://github.com/hexsecs/canarchy && cd canarchy uv sync # create the venv and install from the checkout uv run canarchy --help uv tool install --editable . # optional: put `canarchy` on your PATH; edits take effect live ``` 端到端运行测试套件： ``` uv run python -m unittest discover -s tests -v ``` bash、zsh 和 fish 的 Shell 补全由 `canarchy completion ` 提供 —— 请参阅[入门指南](docs/getting_started.md#install-shell-completion)。 ## 理念 - CLI 即契约。 - 协议语义优于原始帧。 - 结构化输出优于格式化文本。 - 可复现的工作流优于临时交互。 _{版本控制遵循 [SemVer](https://semver.org/)；请参阅 [changelog](CHANGELOG.md) 和[发布工作流](docs/release.md)。`src/canarchy/__init__.py` 是权威的版本来源。}

标签：CAN总线, J1939协议, 云资产清单, 汽车安全, 网络安全, 调试插件, 逆向工具, 逆向工程, 隐私保护