vehsec — Vehicle Security Toolkit

CAN · UDS · Seed-Key · V2X · ICSim · DoIP · DBC — wrapped as a CLI, a TUI, and an MCP server so you (or an AI coding agent) can drive it. No car required.

中文 README / Chinese version · Attack playbook · Launch copy

Why

Vehicle / in-vehicle-network (IVN) security is one of the hottest areas in security research — and one of the most fragmented. The classic tools (CANalyzat0r, UDSim, CANToolz, ICSim, caringcaribou) are aging, Shell-heavy, and thinly documented, so a beginner cannot get started without a real car.

vehsec folds those capabilities into one modern, documented, composable package: one command, one TUI, or one sentence to an AI agent gets you a UDS handshake, a CAN replay, a Seed-Key solve, a V2X signature analysis, or an instrument-cluster tamper demo. Everything runs on a virtual CAN bus (python-can virtual, or vcan0 + ICSim on Linux) with Docker labs — nothing to brick.

Related MCP server: CTF MCP Server

Architecture

One core library, three surfaces (CLI / TUI / MCP), one transport. The same implementation is exposed to humans and to AI agents — that is the main difference from the older tooling.

Quick start

git clone https://github.com/xuange-hu/vehsec && cd vehsec
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[all]"

vehsec --help             # CLI
vehsec tui                # interactive TUI
vehsec mcp                # MCP server (stdio) for AI agents
python examples/demo.py   # 5-step scripted demo, no hardware

Let an AI agent drive it

Copy examples/mcp-config.json into your agent's MCP config (~/.workbuddy/mcp.json, Cursor ~/.cursor/mcp.json, or Claude Desktop's claude_desktop_config.json) and trust the server. Then just ask:

"Run a UDS security access on the virtual ECU and show me the seed and key."

Twenty-four tools are exposed: can_send, can_fuzz, can_analyze, uds_security_access, uds_read_did, uds_read_dtcs, uds_clear_dtcs, uds_decode_dtc, uds_raw, seedkey_solve, v2x_analyze, icsim_set_speed, icsim_tamper_demo, doip_simulate, doip_probe, dbc_decode, dbc_info, j1939_decode, j1939_encode, j1939_decode_name, j1939_decode_dm1, isotp_segment, isotp_decode, isotp_reassemble.

Capabilities

• UDS diagnostics — session control, security access (27), DID read/write, routine control, ECU reset, DTC read/clear (19/14), communication control (28), and a raw request escape hatch, over ISO-TP (udsoncan + can-isotp). Ships with an attached virtual ECU, so all of it runs with nothing plugged in.

• CAN replay & fuzz — replay candump logs, or mutate frames against a set of IDs.

• CAN ID discovery — per-ID counts, unique payloads, and which bytes change, to locate the control signal in an unknown vehicle.

• Seed-Key solver — pluggable algorithm registry for the UDS 27 handshake.

• V2X / ECDSA — detect nonce reuse and recover the signer's private key.

• ICSim control — script speed / doors / turn signals on the virtual cluster.

• DoIP (ISO 13400) — in-process virtual DoIP entity: vehicle discovery, routing activation, and UDS-over-Ethernet (read the VIN) with no hardware.

• DBC parsing — pure stdlib: Intel/Motorola endianness, signed values, factor/offset scaling, value tables, multiplexed signals.

• J1939 (trucks/buses) — 29-bit id ↔ PGN/priority/source (PDU1 & PDU2), NAME decode, DM1 diagnostics (SPN/FMI/CM/OC), EEC1 engine speed.

• ISO-TP (ISO 15765-2) — the UDS transport layer, from scratch: SF/FF/CF/FC framing, segmentation and reassembly with sequence validation.

• DTC (diagnostic trouble codes) — read faults (19 sub 01/02/0A), clear them (14), and decode the 3-byte code into its SAE J2012 identifier (C10000 → U0100) with status flags and a short description.

Labs — 4 runnable Docker exercises

python labs/v2x-ecdsa-nonce/solve.py --gen 20   # nonce reuse is the default:
                                                # the first run recovers the key
python labs/v2x-ecdsa-nonce/solve.py --gen 20 --no-reuse   # contrast: nothing found

UDS in 30 seconds — no hardware

Every UDS command talks to an attached virtual ECU on a python-can virtual bus, so the UDS stack (ISO-TP segmentation, flow control, Seed-Key) is exercised for real — just without metal.

$ vehsec uds read --did 0xF190
{'did': '0xF190',
 'value': '5756575a5a5a314a5a5857303030303031',
 'ascii': 'WVWZZZ1JZXW000001'}

$ vehsec uds security --level 1 --vendor training_rotate
{'level': 1, 'seed': '01020304', 'key': '585e5c52', 'unlocked': True}

$ vehsec uds write --did 0xF190 --data 0102030405
{'did': '0xF190', 'written': 5}

Diagnostic trouble codes in 30 seconds

$ vehsec uds dtc                       # read faults (service 0x19 sub-function 02)
        Diagnostic Trouble Codes (3)
┌───────┬────────┬─────────┬──────────────────────────┬──────────────────────┐
│ code  │ raw    │ status  │ flags                    │ description          │
├───────┼────────┼─────────┼──────────────────────────┼──────────────────────┤
│ P0100 │ 010000 │ 0x2C    │ pendingDTC,confirmedDTC… │ Mass or Volume Air … │
│ P0420 │ 042000 │ 0x0C    │ pendingDTC,confirmedDTC  │ Catalyst System Eff… │
│ U0100 │ C10000 │ 0x08    │ confirmedDTC             │ Lost Communication … │
└───────┴────────┴─────────┴──────────────────────────┴──────────────────────┘

$ vehsec uds dtc --status 0x08         # confirmed faults only
$ vehsec uds dtc --count               # just the number stored
$ vehsec uds dtc --clear               # service 0x14
$ vehsec uds raw --data 1901FF         # any request, response returned verbatim
590109000003

Three records are 15 bytes, so this response is carried by a first frame plus consecutive frames — the ISO-TP path is the real one, not a stub.

The VIN response is 20 bytes, so it is carried by a first frame plus two consecutive frames — you can watch that happen frame by frame with vehsec isotp segment. Point it at metal or UDSim instead with VEHSEC_CAN_IFACE=socketcan VEHSEC_CAN_CHANNEL=vcan0 plus auto_ecu=False.

DoIP & DBC in 30 seconds

vehsec doip simulate                       # spin up a fake DoIP ECU, read its VIN
vehsec dbc info    --file examples/sample.dbc
vehsec dbc decode  --file examples/sample.dbc --id 0x100 --data 9F01393000010000
#   Speed 41.5 km/h · Odometer 1234.5 km · SpeedValid 1
vehsec dbc encode  --file examples/sample.dbc --id 0x100 --set Speed=41.5
vehsec dbc watch   --file examples/sample.dbc --log capture.log   # decode a whole capture

Docs

Tests

pip install -e ".[all]" && pip install pytest
pytest -q      # 172 passed: core, CLI, MCP registration, all 4 labs, demo script

CI runs ruff + pytest on Python 3.11 / 3.12 / 3.13.

Legal & ethics

For authorized security research, teaching, and testing on equipment you own only. Do not point this at vehicles or networks you are not authorized to test; comply with your jurisdiction's laws. The authors accept no responsibility for misuse.

License

MIT © xuange-hu