# dawidkantowicz/virtual-can-hacking-lab architecture

> Architecture diagram of the GitHub repository dawidkantowicz/virtual-can-hacking-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dawidkantowicz/virtual-can-hacking-lab
- Repository: https://github.com/dawidkantowicz/virtual-can-hacking-lab

## Overview

Virtual CAN Hacking Lab is an educational, software-only automotive security lab. The learner follows setup and CAN fundamentals, then practices sniffing, mapping, and replaying traffic against ICSim before exploring UDS diagnostics with UDSim. The only sampled runtime code listens on vcan0 and prints received frames. The README also describes a planned UDS decoder; its implementation is not present in the tree. Documentation details beyond the README are not inferred.

Main entry points: [`docs/01-setup.md`](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/01-setup.md) (Environment setup), [`docs/03-icsim.md`](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/03-icsim.md) (ICSim practice), [`scripts/read_can.py`](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/scripts/read_can.py) (CAN frame reader), [`docs/02-can-basics.md`](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/02-can-basics.md) (CAN fundamentals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning guides"]
  node_readme["Lab overview<br/>[README.md]"]
  node_setup["Environment setup<br/>[01-setup.md]"]
  node_canbasics["CAN fundamentals<br/>[02-can-basics.md]"]
  node_icsimguide["ICSim practice<br/>[03-icsim.md]"]
  node_udsguide["UDS diagnostics<br/>[04-uds.md]"]
  node_decoderguide["Decoder notes"]
end

subgraph group_lab["Virtual lab"]
  node_vcan["SocketCAN vcan0"]
  node_canutils["can-utils"]
  node_icsim["ICSim target"]
  node_udsim["UDSim ECU"]
  node_frames["CAN frames"]
end

subgraph group_tooling["Lab tooling"]
  node_readcan["CAN frame reader<br/>[read_can.py]"]
end

node_learner(("Learner"))

node_learner -->|"reads overview"| node_readme
node_learner -->|"follows setup"| node_setup
node_learner -->|"learns CAN"| node_canbasics
node_learner -->|"practices attacks"| node_icsimguide
node_learner -->|"explores diagnostics"| node_udsguide
node_learner -.->|"reviews roadmap"| node_decoderguide
node_setup -->|"configures"| node_vcan
node_setup -->|"sets up tools"| node_canutils
node_icsimguide -->|"guides practice"| node_icsim
node_icsimguide -->|"uses tools"| node_canutils
node_icsim -->|"communicates over"| node_vcan
node_udsguide -->|"guides exploration"| node_udsim
node_readcan -->|"listens on"| node_vcan
node_vcan -->|"provides frames"| node_readcan
node_readcan -->|"prints"| node_frames
node_canbasics -->|"demonstrates tools"| node_canutils

click node_readme "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/README.md"
click node_setup "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/01-setup.md"
click node_canbasics "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/02-can-basics.md"
click node_icsimguide "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/03-icsim.md"
click node_udsguide "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/04-uds.md"
click node_decoderguide "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/05-uds-decoder"
click node_readcan "https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/scripts/read_can.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_setup,node_canbasics,node_icsimguide,node_udsguide,node_decoderguide toneBlue
class node_vcan,node_canutils,node_icsim,node_udsim,node_frames toneAmber
class node_readcan toneMint
class node_learner toneIndigo
```

## Components

### Learning guides

- [Lab overview](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/README.md): `README.md`
- [Environment setup](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/01-setup.md): `docs/01-setup.md`
- [CAN fundamentals](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/02-can-basics.md): `docs/02-can-basics.md`
- [ICSim practice](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/03-icsim.md): `docs/03-icsim.md`
- [UDS diagnostics](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/04-uds.md): `docs/04-uds.md`
- [Decoder notes](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/docs/05-uds-decoder): `docs/05-uds-decoder`

### Virtual lab

- **SocketCAN vcan0**
- **can-utils**
- **ICSim target**
- **UDSim ECU**
- **CAN frames**

### Lab tooling

- [CAN frame reader](https://github.com/dawidkantowicz/virtual-can-hacking-lab/blob/main/scripts/read_can.py): `scripts/read_can.py`

### Other components

- **Learner**

## Connections

- Learner → Lab overview: reads overview
- Learner → Environment setup: follows setup
- Learner → CAN fundamentals: learns CAN
- Learner → ICSim practice: practices attacks
- Learner → UDS diagnostics: explores diagnostics
- Learner → Decoder notes: reviews roadmap
- Environment setup → SocketCAN vcan0: configures
- Environment setup → can-utils: sets up tools
- ICSim practice → ICSim target: guides practice
- ICSim practice → can-utils: uses tools
- ICSim target → SocketCAN vcan0: communicates over
- UDS diagnostics → UDSim ECU: guides exploration
- CAN frame reader → SocketCAN vcan0: listens on
- SocketCAN vcan0 → CAN frame reader: provides frames
- CAN frame reader → CAN frames: prints
- CAN fundamentals → can-utils: demonstrates tools