{"id":50636866,"url":"https://github.com/hexsecs/canarchy","last_synced_at":"2026-06-23T23:01:01.571Z","repository":{"id":351926218,"uuid":"1213099273","full_name":"hexsecs/canarchy","owner":"hexsecs","description":"https://hexsecs.github.io/canarchy/   CANarchy is a stream-first CAN analysis and manipulation runtime designed for automation, security research, and agent-driven workflows.","archived":false,"fork":false,"pushed_at":"2026-06-14T02:40:45.000Z","size":2305,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T04:12:34.510Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hexsecs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-17T03:28:29.000Z","updated_at":"2026-06-14T02:40:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hexsecs/canarchy","commit_stats":null,"previous_names":["hexsecs/canarchy"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/hexsecs/canarchy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexsecs%2Fcanarchy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexsecs%2Fcanarchy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexsecs%2Fcanarchy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexsecs%2Fcanarchy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexsecs","download_url":"https://codeload.github.com/hexsecs/canarchy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexsecs%2Fcanarchy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34709804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-07T04:00:18.091Z","updated_at":"2026-06-23T23:01:01.518Z","avatar_url":"https://github.com/hexsecs.png","language":"Python","funding_links":[],"categories":["Libraries and Tools"],"sub_categories":["Python"],"readme":"# README.md\n\n## CANarchy\n\nCANarchy is a stream-first CAN analysis and manipulation runtime designed for automation, security research, and agent-driven workflows.\n\nThe project is implemented in Python and uses `uv` for environment, dependency, and packaging workflows.\n\nMachine-readable output uses canonical JSON envelopes and JSONL event streams where commands produce typed events. The CLI is the interface. J1939 is a first-class citizen, not an afterthought.\n\nToday the repository delivers:\n\n* a stable CLI surface for analysts, scripts, and coding agents\n* J1939-first heavy vehicle workflows: PGN decoding, SPN extraction, TP session reassembly, DM1 fault parsing\n* structured output (`--json`, `--jsonl`, `--text`) on every command\n* live CAN transport via `python-can` with support for socketcan, virtual bus, and UDP multicast\n* UDS scan and trace, DBC decode/encode, capture/filter/replay, and an interactive shell\n\n### Try it in 60 seconds\n\nOnce a CANarchy release has been published to PyPI:\n\n```bash\npipx install canarchy\ncanarchy --version\ncanarchy doctor --text\n\n# Stream two pre-recorded frame events from the deterministic scaffold\n# backend — no hardware, no fixture files, no network. Shows the\n# canonical JSONL envelope.\nCANARCHY_TRANSPORT_BACKEND=scaffold canarchy capture can0 --jsonl\n```\n\n`canarchy doctor` runs eight offline health checks; everything green\nmeans the install is good. The scaffold capture demonstrates the\nstructured-output contract that every command emits. Replace it with\n`canarchy capture can0 --candump` once you have a real interface, or\nclone the repo to run against the in-tree J1939 fixtures.\n\nFor development or for installs from a checkout, see\n[Installation](#installation) below.\n\n### Why CANarchy?\n\nMost CAN tools force the wrong tradeoff: interactive but hard to automate, scriptable but too raw, protocol-aware but inconsistent across interfaces. CANarchy is built around the opposite constraint: every output is a stream of typed events you can parse, pipe, or forward to an agent.\n\nThe [event schema](docs/event-schema.md) is the stable contract. The CLI wraps it. J1939 heavy vehicle analysis is the initial focus for protocol-aware workflows, with a security-research lens throughout.\n\n### Current State\n\nFully implemented and tested:\n\n_Transport_\n\n* `capture`, `send`, `filter`, `stats` — transport workflows with live `python-can` and deterministic scaffold backends; `stats` reports per-ID frequency/timing, DLC distribution, and a bus-load estimate\n* `capture-info` — fast capture metadata without loading every frame\n* `generate` — cangen-style frame generation (fixed, random, incrementing modes)\n* `simulate` — deterministic, profile-driven mix of classic CAN, J1939, and DM1 traffic (no hardware needed)\n* `gateway` — bridge frames between two interfaces (unidirectional and bidirectional)\n* `replay`, `sequence replay` — deterministic replay planning from candump files, and YAML/JSON multi-message coordinated transmit\n\n_Databases (DBC / ARXML / KCD / SYM via cantools)_\n\n* `decode`, `encode` — database-backed signal decode and encode; `encode` resolves SAE PGN/SPN display names for a decode→encode round-trip\n* `dbc inspect` (incl. `--layout`, `--search`), `dbc signals` — database and signal inspection\n* `dbc convert` — convert databases between DBC / KCD / SYM\n* `dbc generate-c` — C source/header/fuzzer generation from a database\n* `dbc provider list`, `dbc search`, `dbc fetch`, `dbc cache list|prune|refresh` — provider-backed DBC discovery and cache workflows\n\n_J1939_\n\n* `j1939 monitor`, `decode`, `pgn`, `spn`, `tp`, `dm1`, `faults`, `summary`, `inventory`, `compare` — J1939 operator workflows across live, file-backed, and decoded views; faults resolve SPN names and FMI descriptions from the bundled SAE catalog\n\n_UDS_\n\n* `uds scan`, `trace`, `services` — UDS diagnostic workflows and service catalog, including initial transport-backed scan/trace heuristics\n\n_Reverse engineering_\n\n* `re signals`, `re counters`, `re entropy` — file-backed signal/counter/entropy candidate ranking, annotated with J1939 PGN/source-address context and transport-protocol aware\n* `re correlate` — correlation of candidate fields against timestamped reference series\n* `re anomalies` — inter-frame-timing and unexpected/dropped-ID anomaly detection, with optional baseline\n* `re corpus` — cross-capture coverage, cycle-time drift, and signal-stability analysis\n* `re match-dbc`, `re shortlist-dbc` — provider-backed DBC candidate ranking against captures\n\n_Datasets_\n\n* `datasets provider list`, `search`, `inspect`, `fetch`, `cache list|refresh` — public CAN dataset provider workflows\n* `datasets convert`, `stream`, `replay` — dataset conversion and bounded streaming/replay\n\n_Visualization, front ends, and extensions_\n\n* `plot` — signal time-series plots to PNG/SVG/HTML (`pip install canarchy[plot]`)\n* `web serve` — read-only browser dashboard over the JSONL envelope (HTTP + WebSocket)\n* `shell` — interactive REPL and `--command` scripting mode\n* `tui` — terminal UI front end\n* `plugins list|info|enable|disable` — Python entry-point plugin discovery and toggles\n* `skills provider list`, `search`, `fetch`, `cache list|refresh` — repository-backed CANarchy skill discovery, caching, and provenance workflows\n\n_Active-transmit fuzzing_ (gated by the [active-transmit safety design](docs/design/active-transmit-safety.md); `--dry-run` is the safe planning path)\n\n* `fuzz payload`, `fuzz replay`, `fuzz arbitration-id` — payload/replay/ID-walk fuzzing\n* `fuzz signal`, `fuzz spn` — DBC-signal and J1939-SPN-aware mutation with sentinel coverage\n\n_Session, export, and utilities_\n\n* `session save`, `load`, `show` — session management\n* `export` — structured artifact export\n* `doctor` — local environment health checks (Python, `python-can`, vendor backends, caches, MCP, config)\n* `mcp serve`, `mcp install` — Model Context Protocol server and client-config helper\n* `completion {bash,zsh,fish}` — emit a shell completion script\n* `--log-level` and `--quiet` — global stderr logging controls (place before the subcommand)\n\nDefault transport backend is `python-can`; set `CANARCHY_TRANSPORT_BACKEND=scaffold` for deterministic offline behavior.\n\n### Documentation\n\n* [Event Schema](docs/event-schema.md) — canonical event envelope for all structured output\n* [Command spec](docs/command_spec.md)\n* [CAN Tool Feature Matrix](docs/feature-matrix.md) — high-level comparison to other OSS CAN tools\n* [Architecture](docs/architecture.md)\n* [Cookbook](docs/cookbook/index.md) — short task-oriented recipes\n* [Troubleshooting](docs/troubleshooting.md) — structured error-code catalog\n* [Changelog](CHANGELOG.md)\n* [Release Workflow](docs/release.md)\n* [J1939 Heavy Vehicle Demo](docs/tutorials/j1939_heavy_vehicle.md)\n\n### Community\n\n* [Contributing](CONTRIBUTING.md) — local development, branch flow, PR gates\n* [Code of Conduct](CODE_OF_CONDUCT.md)\n* [Security Policy](SECURITY.md) — reporting security concerns and active-bus operation guidance\n\n### Installation\n\nCANarchy currently targets Python 3.12 or newer.\n\n#### From PyPI (recommended for users)\n\n```bash\npipx install canarchy        # isolated, on PATH everywhere\n# or\npip install --user canarchy  # if pipx is not available\n```\n\nAfter install, confirm the environment is healthy:\n\n```bash\ncanarchy --version\ncanarchy doctor --text\n```\n\nShell completions for bash, zsh, and fish are produced by `canarchy completion \u003cshell\u003e`; see [Getting Started](docs/getting_started.md#install-shell-completion) for the install snippet for each shell.\n\n#### From source (development)\n\nCANarchy uses `uv` for environment, dependency, and packaging workflows.\n\n1. Install Python 3.12 or newer.\n2. Install `uv`.\n3. Clone the repository.\n4. Sync the project environment and dependencies:\n\n```bash\nuv sync\n```\n\n5. Run the CLI:\n\n```bash\nuv run canarchy --help\n```\n\n6. Optionally install `canarchy` on your PATH so you don't need `uv run` every time:\n\n```bash\nuv tool install --editable .\ncanarchy --help\n```\n\nIf you want to verify the local environment end to end, run:\n\n```bash\nuv run python -m unittest discover -s tests -v\n```\n\nNotes:\n\n* `uv sync` creates the local virtual environment and installs the package from the current checkout.\n* The checked-in `uv.lock` file should be used for reproducible dependency resolution.\n* `uv tool install --editable .` puts `canarchy` on your PATH permanently; edits take effect without reinstalling.\n* Live transport support currently uses `python-can`; persist backend settings in `~/.canarchy/config.toml` (see [Getting Started](docs/getting_started.md)).\n\n### Development\n\n```bash\nuv sync\nuv tool install --editable .\ncanarchy --help\n```\n\n### Versioning Policy\n\nCANarchy uses Semantic Versioning.\n\nRules:\n\n* `MAJOR` for intentional breaking changes to the CLI contract, structured output contract, or other documented public behavior\n* `MINOR` for backward-compatible new commands, new output fields, or new capabilities\n* `PATCH` for backward-compatible fixes, documentation corrections, and implementation improvements that do not intentionally break the public contract\n\nPrereleases:\n\n* prereleases should use standard SemVer prerelease identifiers such as `0.2.0a1`, `0.2.0b1`, or `0.2.0rc1`\n* prereleases are appropriate when command behavior, output contracts, or packaging flows need release-candidate validation before a stable tag\n\nRelease tags:\n\n* Git tags should match the package version exactly, prefixed with `v`, for example `v0.1.0`\n* `canarchy --version`, package metadata, and release tags should always agree\n\nCurrent implementation:\n\n* `src/canarchy/__init__.py` is the authoritative version source\n* package metadata is derived from that version during build\n* CLI and MCP server version reporting reuse the same version value\n\n### Example Usage\n\n```bash\n# Capture and decode\ncanarchy capture can0 --candump\ncanarchy capture can0 --jsonl\ncanarchy decode --file trace.candump --dbc vehicle.dbc --jsonl\n\n# J1939 heavy vehicle analysis\ncanarchy j1939 decode --file trace.candump --text\ncanarchy j1939 spn 110 --file trace.candump --text   # Engine Coolant Temp\ncanarchy j1939 dm1 --file trace.candump --text        # Active fault codes\n\n# Pipe events into downstream tools\ncanarchy j1939 spn 110 --file trace.candump --jsonl \\\n  | jq '[.payload.value, .payload.units, .payload.timestamp]'\n\n# Active workflows\ncanarchy generate can0 --count 10 --gap 50 --id 7DF --jsonl\ncanarchy gateway can0 239.0.0.1 --count 100\ncanarchy replay --file trace.candump --rate 2.0 --json\n```\n\nUse `--candump` for a human-oriented live view. Use `--jsonl` when feeding output to scripts or agents — every line is a typed event from the [canonical schema](docs/event-schema.md).\n\nLive transport uses `python-can` by default. Set `CANARCHY_PYTHON_CAN_INTERFACE` to choose an interface type, or set `CANARCHY_TRANSPORT_BACKEND=scaffold` for deterministic offline behavior.\n\nCurrent file support:\n\n* file-backed workflows such as `filter`, `stats`, `decode`, `j1939 decode`, and `replay` read standard timestamped candump log files\n* `j1939 pgn` inspects recorded traffic with `--file \u003ccapture.candump\u003e`\n* the supported log form today is `(timestamp) interface frame#data`\n* additional supported candump forms include classic RTR `id#R`, CAN FD `id##\u003cflags\u003e\u003cdata\u003e`, and error frames using a CAN error-flagged identifier such as `20000080#0000000000000000`\n* supported capture-file suffixes today are `.candump` and `.log`; `capture-info --file -`, `stats --file -`, and `filter --file -` can read candump text from stdin\n* `filter --stdin`, `decode --stdin`, and `j1939 decode --stdin` read JSONL FrameEvents from stdin\n* malformed candump log lines are skipped during capture parsing rather than falling back to sample data; commands that require capture metadata or explicitly validate stdin emptiness return structured errors when no valid frames are available\n\n### Structured Output\n\nSuccessful commands return a stable JSON envelope:\n\n```json\n{\n  \"ok\": true,\n  \"command\": \"capture\",\n  \"data\": {},\n  \"warnings\": [],\n  \"errors\": []\n}\n```\n\nFailures return structured errors with actionable hints:\n\n```json\n{\n  \"ok\": false,\n  \"command\": \"decode\",\n  \"data\": {},\n  \"warnings\": [],\n  \"errors\": [\n    {\n      \"code\": \"DBC_LOAD_FAILED\",\n      \"message\": \"Failed to parse DBC file.\",\n      \"hint\": \"Validate the DBC syntax and line endings.\"\n    }\n  ]\n}\n```\n\n### Philosophy\n\n* CLI is the contract\n* Protocol semantics over raw frames\n* Structured outputs over formatted text\n* Reproducible workflows over ad-hoc interaction\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexsecs%2Fcanarchy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexsecs%2Fcanarchy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexsecs%2Fcanarchy/lists"}