# thecruz/kdmapper architecture

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

- Interactive diagram: https://gitdiagram.com/thecruz/kdmapper
- Repository: https://github.com/thecruz/kdmapper

## Overview

KDMapper is a Windows tool for manually mapping a driver image into kernel memory using a vulnerable Intel driver. The main workflow parses options and a driver path, optionally refreshes symbol offsets, loads the helper driver, reads the image, maps it, and unloads the helper. Documented branches include allocation modes, pre-entry parameter customization, kernel trace cleanup, and PDB-based offsets. Several implementation files were not sampled, so links for those documented capabilities are limited to their supported owning modules.

Main entry points: [`kdmapper/main.cpp`](https://github.com/thecruz/kdmapper/blob/master/kdmapper/main.cpp) (Mapper CLI), [`kdmapper/kdmapper.cpp`](https://github.com/thecruz/kdmapper/blob/master/kdmapper/kdmapper.cpp) (Mapping engine), [`kdmapper/KDSymbolsHandler.cpp`](https://github.com/thecruz/kdmapper/blob/master/kdmapper/KDSymbolsHandler.cpp) (Offset handler), [`SymbolsFromPDB/main.cpp`](https://github.com/thecruz/kdmapper/blob/master/SymbolsFromPDB/main.cpp) (PDB offset tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Mapper workflow"]
  node_mapper_cli["Mapper CLI<br/>[main.cpp]"]
  node_file_utils["File utilities<br/>[utils.cpp]"]
end

subgraph group_mapping["Image mapping"]
  node_mapper_engine["Mapping engine<br/>[kdmapper.cpp]"]
  node_pe_support["PE support"]
end

subgraph group_symbols["Symbol offsets"]
  node_offset_handler["Offset handler"]
  node_offset_file["Offsets file"]
  node_pdb_tool["PDB offset tool<br/>[main.cpp]"]
  node_symbol_handler["Symbol lookup"]
end

subgraph group_kernel["Kernel integration"]
  node_intel_driver["Intel driver control<br/>[intel_driver.cpp]"]
  node_embedded_driver["Embedded driver image"]
  node_service_control["Driver service control<br/>[service.cpp]"]
  node_kernel_memory["Kernel memory operations<br/>[intel_driver.cpp]"]
end

node_user(("Operator"))
node_image_file["Driver image"]
node_symbol_server["Microsoft symbol server"]
node_kernel_binaries["Windows binaries"]
node_kernel_state[("Kernel state")]
node_mapped_driver["Mapped driver"]

node_user -->|"runs with options"| node_mapper_cli
node_image_file -->|"supplies path"| node_mapper_cli
node_mapper_cli -.->|"loads offsets"| node_offset_handler
node_offset_handler -.->|"reads or refreshes"| node_offset_file
node_offset_handler -.->|"launches updater"| node_pdb_tool
node_pdb_tool -->|"requests symbols"| node_symbol_handler
node_symbol_handler -->|"inspects"| node_kernel_binaries
node_symbol_handler -->|"retrieves PDBs"| node_symbol_server
node_pdb_tool -->|"writes offsets"| node_offset_file
node_mapper_cli -->|"loads and unloads"| node_intel_driver
node_intel_driver -->|"uses image"| node_embedded_driver
node_intel_driver -->|"controls service"| node_service_control
node_mapper_cli -->|"reads image"| node_file_utils
node_file_utils -->|"loads bytes"| node_image_file
node_mapper_cli -->|"requests mapping"| node_mapper_engine
node_mapper_engine -->|"uses PE operations"| node_pe_support
node_mapper_engine -->|"performs kernel operations"| node_kernel_memory
node_kernel_memory -->|"reads and modifies"| node_kernel_state
node_kernel_memory -->|"places and invokes"| node_mapped_driver
node_mapper_engine -->|"customizes entry parameters"| node_mapped_driver

click node_mapper_cli "https://github.com/thecruz/kdmapper/blob/master/kdmapper/main.cpp"
click node_file_utils "https://github.com/thecruz/kdmapper/blob/master/kdmapper/utils.cpp"
click node_offset_handler "https://github.com/thecruz/kdmapper/blob/master/kdmapper/KDSymbolsHandler.cpp"
click node_pdb_tool "https://github.com/thecruz/kdmapper/blob/master/SymbolsFromPDB/main.cpp"
click node_symbol_handler "https://github.com/thecruz/kdmapper/blob/master/SymbolsFromPDB/SimplestSymbolHandler.cpp"
click node_intel_driver "https://github.com/thecruz/kdmapper/blob/master/kdmapper/intel_driver.cpp"
click node_embedded_driver "https://github.com/thecruz/kdmapper/blob/master/kdmapper/include/intel_driver_resource.hpp"
click node_service_control "https://github.com/thecruz/kdmapper/blob/master/kdmapper/service.cpp"
click node_mapper_engine "https://github.com/thecruz/kdmapper/blob/master/kdmapper/kdmapper.cpp"
click node_pe_support "https://github.com/thecruz/kdmapper/blob/master/kdmapper/portable_executable.cpp"
click node_kernel_memory "https://github.com/thecruz/kdmapper/blob/master/kdmapper/intel_driver.cpp"

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_mapper_cli,node_file_utils toneBlue
class node_mapper_engine,node_pe_support,node_kernel_state toneAmber
class node_offset_handler,node_offset_file,node_pdb_tool,node_symbol_handler,node_symbol_server toneMint
class node_intel_driver,node_embedded_driver,node_service_control,node_kernel_memory toneRose
class node_user,node_image_file,node_kernel_binaries,node_mapped_driver toneIndigo
```

## Components

### Mapper workflow

- [Mapper CLI](https://github.com/thecruz/kdmapper/blob/master/kdmapper/main.cpp): `kdmapper/main.cpp`
- [File utilities](https://github.com/thecruz/kdmapper/blob/master/kdmapper/utils.cpp): `kdmapper/utils.cpp`

### Image mapping

- [Mapping engine](https://github.com/thecruz/kdmapper/blob/master/kdmapper/kdmapper.cpp): `kdmapper/kdmapper.cpp`
- [PE support](https://github.com/thecruz/kdmapper/blob/master/kdmapper/portable_executable.cpp): `kdmapper/portable_executable.cpp`

### Symbol offsets

- [Offset handler](https://github.com/thecruz/kdmapper/blob/master/kdmapper/KDSymbolsHandler.cpp): `kdmapper/KDSymbolsHandler.cpp`
- **Offsets file**
- [PDB offset tool](https://github.com/thecruz/kdmapper/blob/master/SymbolsFromPDB/main.cpp): `SymbolsFromPDB/main.cpp`
- [Symbol lookup](https://github.com/thecruz/kdmapper/blob/master/SymbolsFromPDB/SimplestSymbolHandler.cpp): `SymbolsFromPDB/SimplestSymbolHandler.cpp`

### Kernel integration

- [Intel driver control](https://github.com/thecruz/kdmapper/blob/master/kdmapper/intel_driver.cpp): `kdmapper/intel_driver.cpp`
- [Embedded driver image](https://github.com/thecruz/kdmapper/blob/master/kdmapper/include/intel_driver_resource.hpp): `kdmapper/include/intel_driver_resource.hpp`
- [Driver service control](https://github.com/thecruz/kdmapper/blob/master/kdmapper/service.cpp): `kdmapper/service.cpp`
- [Kernel memory operations](https://github.com/thecruz/kdmapper/blob/master/kdmapper/intel_driver.cpp): `kdmapper/intel_driver.cpp`

### Other components

- **Operator**
- **Driver image**
- **Microsoft symbol server**
- **Windows binaries**
- **Kernel state**
- **Mapped driver**

## Connections

- Operator → Mapper CLI: runs with options
- Driver image → Mapper CLI: supplies path
- Mapper CLI → Offset handler: loads offsets
- Offset handler → Offsets file: reads or refreshes
- Offset handler → PDB offset tool: launches updater
- PDB offset tool → Symbol lookup: requests symbols
- Symbol lookup → Windows binaries: inspects
- Symbol lookup → Microsoft symbol server: retrieves PDBs
- PDB offset tool → Offsets file: writes offsets
- Mapper CLI → Intel driver control: loads and unloads
- Intel driver control → Embedded driver image: uses image
- Intel driver control → Driver service control: controls service
- Mapper CLI → File utilities: reads image
- File utilities → Driver image: loads bytes
- Mapper CLI → Mapping engine: requests mapping
- Mapping engine → PE support: uses PE operations
- Mapping engine → Kernel memory operations: performs kernel operations
- Kernel memory operations → Kernel state: reads and modifies
- Kernel memory operations → Mapped driver: places and invokes
- Mapping engine → Mapped driver: customizes entry parameters