# tklengyel/drakvuf architecture

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

- Interactive diagram: https://gitdiagram.com/tklengyel/drakvuf
- Repository: https://github.com/tklengyel/drakvuf

## Overview

#### Purpose and Execution Model
DRAKVUF is an agentless, virtualization-based black-box analysis system for tracing binaries, guest OS kernels, and user processes inside Intel VT-x/EPT virtual machines. It operates externally to supported Windows and Linux guests through Xen and virtual-machine introspection (VMI), avoiding in-guest instrumentation. Primary executable entry points are `src/main.cpp`, `src/drakvuf.cpp`, and the injector CLI in `src/injector.cpp`.

#### Host/Hypervisor Boundary
The host-side runtime depends on Xen and the vendored/external VMI stack (`xen`, `libvmi`). Xen-specific control operations are isolated in `src/xen_helper/xen_helper.c` and `src/xen_helper/xen_helper.h`. This boundary is architecturally critical: DRAKVUF observes and controls guest execution, memory, registers, and event delivery through hypervisor APIs rather than guest agents.

#### Core Introspection Library
`libdrakvuf` provides the central C API over VMI, guest OS abstraction, profile parsing, and process/object access:
- `src/libdrakvuf/drakvuf.c`
- `src/libdrakvuf/vmi.c`
- `src/libdrakvuf/os.c`

Windows and Linux implementations resolve OS-specific structures, exports, process state, files, handles, and offsets. Guest symbol/type metadata is consumed through JSON profiles in `src/libdrakvuf/json-profile.c` and `src/libdrakvuf/json-util.c`; profiles form the key compatibility boundary between generic analysis logic and guest kernel layouts.

#### Event Hooking and Dispatch
`libhook` turns low-level VMI events into reusable execution hooks, including syscall, return, CR3/process-context, memory-access, CPUID, catch-all, and manually placed hooks:
- `src/libhook/libhook.hpp`
- `src/libhook/hooks/base.cpp`
- `src/libhook/hooks/syscall.cpp`

The main runtime initializes DRAKVUF/VMI, establishes hooks, then dispatches callbacks under the appropriate guest context. Plugins consume these callbacks rather than directly owning the underlying hypervisor event lifecycle.

#### Plugin Analysis Layer
The principal extensibility model is a compiled plugin registry and plugin lifecycle framework:
- `src/plugins/plugins.cpp`
- `src/plugins/plugins.h`
- `src/plugins/meson.build`

Monitoring plugins implement behavioral analysis domains—e.g., process creation (`src/plugins/procmon/procmon.cpp`), system calls (`src/plugins/syscalls/syscalls.cpp`), API activity (`src/plugins/apimon/apimon.cpp`), files (`src/plugins/filetracer/filetracer.cpp`), registry (`src/plugins/regmon/regmon.cpp`), and memory/process dumping. They depend on `libdrakvuf` for semantic guest access and `libhook` for events, keeping detection/output policy separate from VMI mechanics.

#### Output, Control, and Injection
Plugin observations are serialized through shared formatting infrastructure supporting JSON, CSV, key-value, and default formats:
- `src/plugins/output_format/ostream.cpp`
- `src/plugins/output_format/jsonfmt.h`
- `src/plugins/plugin_utils.cpp`

Active guest manipulation is separated into `libinjector`, with distinct Windows and Linux method implementations:
- `src/libinjector/injector.c`
- `src/libinjector/win/win_injector.c`
- `src/libinjector/linux/linux_injector.c`

This subsystem supports operations such as process creation, shellcode execution, and guest file reads/writes; it crosses from observation into controlled guest execution and therefore has a distinct CLI boundary at `src/injector.cpp`.

#### Auxiliary Runtimes and Delivery
A REPL/control path (`src/repl.cpp`, `src/librepl/repl.cpp`) and directory watcher (`src/dirwatch/dirwatch.c`) support operational orchestration. The project is native C/C++, built with Autotools or Meson (`configure.ac`, `meson.build`), and packaged for Debian/Xen environments via `package/build.sh`, `package/mkdeb`, and Xen-focused Dockerfiles. Automation under `.github/workflows` builds, packages, and statically analyzes the host-side system.

Main entry points: [`src/libdrakvuf/drakvuf.c`](https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/drakvuf.c) (libdrakvuf), [`src/drakvuf.cpp`](https://github.com/tklengyel/drakvuf/blob/main/src/drakvuf.cpp) (Runtime coordinator), [`src/libinjector/injector.c`](https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/injector.c) (libinjector), [`src/plugins/procmon/procmon.cpp`](https://github.com/tklengyel/drakvuf/blob/main/src/plugins/procmon/procmon.cpp) (Monitoring plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host &amp; Hypervisor"]
  node_drakvuf_cli["DRAKVUF runtime<br/>executable<br/>[main.cpp]"]
  node_runtime["Runtime coordinator<br/>[drakvuf.cpp]"]
  node_xen_libvmi{{"Xen + libvmi<br/>hypervisor VMI"}}
  node_xen_helper["Xen helper<br/>Xen control adapter<br/>[xen_helper.c]"]
end

subgraph group_core["Core Introspection"]
  node_libdrakvuf["libdrakvuf<br/>C API<br/>[drakvuf.c]"]
  node_vmi_adapter["VMI adapter<br/>VMI integration<br/>[vmi.c]"]
  node_os_abstraction["Guest OS abstraction<br/>Windows/Linux semantics<br/>[os.c]"]
  node_json_profiles["JSON profiles<br/>kernel metadata<br/>[json-profile.c]"]
  node_libhook["libhook<br/>event hook framework<br/>[libhook.hpp]"]
  node_syscall_hooks["Syscall hooks<br/>hook implementation<br/>[syscall.cpp]"]
end

subgraph group_analysis["Analysis Plugins"]
  node_plugin_registry["Plugin registry<br/>plugin lifecycle<br/>[plugins.cpp]"]
  node_monitoring_plugins["Monitoring plugins<br/>behavioral analysis<br/>[procmon.cpp]"]
  node_output_formatters["Output formatters<br/>serialization<br/>[ostream.cpp]"]
end

subgraph group_operations["Control &amp; Delivery"]
  node_injector_cli["Injector CLI<br/>executable<br/>[injector.cpp]"]
  node_libinjector["libinjector<br/>guest manipulation<br/>[injector.c]"]
  node_windows_injector["Windows injection<br/>platform method<br/>[win_injector.c]"]
  node_linux_injector["Linux injection<br/>platform method<br/>[linux_injector.c]"]
  node_repl["REPL control<br/>operational control<br/>[repl.cpp]"]
  node_packaging["Build &amp; packaging<br/>delivery automation<br/>[build.sh]"]
end

node_drakvuf_cli -->|"starts"| node_runtime
node_runtime -->|"uses"| node_libdrakvuf
node_runtime -->|"establishes hooks"| node_libhook
node_runtime -->|"runs"| node_plugin_registry
node_runtime -->|"control path"| node_repl
node_libdrakvuf -->|"integrates"| node_vmi_adapter
node_libdrakvuf -->|"provides"| node_os_abstraction
node_libdrakvuf -->|"consumes"| node_json_profiles
node_vmi_adapter -->|"VMI calls"| node_xen_libvmi
node_xen_helper -->|"Xen controls"| node_xen_libvmi
node_runtime -->|"hypervisor control"| node_xen_helper
node_libhook -->|"registers VMI events"| node_libdrakvuf
node_libhook -->|"implements"| node_syscall_hooks
node_plugin_registry -->|"manages"| node_monitoring_plugins
node_monitoring_plugins -->|"consumes callbacks"| node_libhook
node_monitoring_plugins -->|"queries guest state"| node_libdrakvuf
node_monitoring_plugins -->|"serializes observations"| node_output_formatters
node_injector_cli -->|"invokes"| node_libinjector
node_libinjector -->|"uses guest access"| node_libdrakvuf
node_libinjector -->|"selects"| node_windows_injector
node_libinjector -->|"selects"| node_linux_injector
node_libinjector -->|"controls guest externally"| node_xen_libvmi
node_packaging -.->|"delivers"| node_drakvuf_cli
node_packaging -.->|"delivers"| node_injector_cli

click node_drakvuf_cli "https://github.com/tklengyel/drakvuf/blob/main/src/main.cpp"
click node_runtime "https://github.com/tklengyel/drakvuf/blob/main/src/drakvuf.cpp"
click node_xen_helper "https://github.com/tklengyel/drakvuf/blob/main/src/xen_helper/xen_helper.c"
click node_libdrakvuf "https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/drakvuf.c"
click node_vmi_adapter "https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/vmi.c"
click node_os_abstraction "https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/os.c"
click node_json_profiles "https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/json-profile.c"
click node_libhook "https://github.com/tklengyel/drakvuf/blob/main/src/libhook/libhook.hpp"
click node_syscall_hooks "https://github.com/tklengyel/drakvuf/blob/main/src/libhook/hooks/syscall.cpp"
click node_plugin_registry "https://github.com/tklengyel/drakvuf/blob/main/src/plugins/plugins.cpp"
click node_monitoring_plugins "https://github.com/tklengyel/drakvuf/blob/main/src/plugins/procmon/procmon.cpp"
click node_output_formatters "https://github.com/tklengyel/drakvuf/blob/main/src/plugins/output_format/ostream.cpp"
click node_injector_cli "https://github.com/tklengyel/drakvuf/blob/main/src/injector.cpp"
click node_libinjector "https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/injector.c"
click node_windows_injector "https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/win/win_injector.c"
click node_linux_injector "https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/linux/linux_injector.c"
click node_repl "https://github.com/tklengyel/drakvuf/blob/main/src/repl.cpp"
click node_packaging "https://github.com/tklengyel/drakvuf/blob/main/package/build.sh"

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_drakvuf_cli,node_runtime,node_xen_libvmi,node_xen_helper toneBlue
class node_libdrakvuf,node_vmi_adapter,node_os_abstraction,node_json_profiles,node_libhook,node_syscall_hooks toneAmber
class node_plugin_registry,node_monitoring_plugins,node_output_formatters toneMint
class node_injector_cli,node_libinjector,node_windows_injector,node_linux_injector,node_repl,node_packaging toneRose
```

## Components

### Host & Hypervisor

External control and VMI boundary.

- [DRAKVUF runtime](https://github.com/tklengyel/drakvuf/blob/main/src/main.cpp): executable · Main host-side analysis entry point. · `src/main.cpp`
- [Runtime coordinator](https://github.com/tklengyel/drakvuf/blob/main/src/drakvuf.cpp): runtime · Initializes VMI, hooks, and plugin execution. · `src/drakvuf.cpp`
- **Xen + libvmi**: hypervisor VMI · External interface to guest execution and memory.
- [Xen helper](https://github.com/tklengyel/drakvuf/blob/main/src/xen_helper/xen_helper.c): Xen control adapter · `src/xen_helper/xen_helper.c`

### Core Introspection

Guest-aware VMI and hook abstractions.

- [libdrakvuf](https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/drakvuf.c): C API · Central guest introspection and semantic access layer. · `src/libdrakvuf/drakvuf.c`
- [VMI adapter](https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/vmi.c): VMI integration · `src/libdrakvuf/vmi.c`
- [Guest OS abstraction](https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/os.c): Windows/Linux semantics · Resolves guest processes, objects, exports, and layouts. · `src/libdrakvuf/os.c`
- [JSON profiles](https://github.com/tklengyel/drakvuf/blob/main/src/libdrakvuf/json-profile.c): kernel metadata · Compatibility boundary for guest symbols and types. · `src/libdrakvuf/json-profile.c`
- [libhook](https://github.com/tklengyel/drakvuf/blob/main/src/libhook/libhook.hpp): event hook framework · Converts VMI events into reusable execution hooks. · `src/libhook/libhook.hpp`
- [Syscall hooks](https://github.com/tklengyel/drakvuf/blob/main/src/libhook/hooks/syscall.cpp): hook implementation · `src/libhook/hooks/syscall.cpp`

### Analysis Plugins

Compiled behavioral monitoring modules.

- [Plugin registry](https://github.com/tklengyel/drakvuf/blob/main/src/plugins/plugins.cpp): plugin lifecycle · Loads and manages compiled analysis plugins. · `src/plugins/plugins.cpp`
- [Monitoring plugins](https://github.com/tklengyel/drakvuf/blob/main/src/plugins/procmon/procmon.cpp): behavioral analysis · Process, syscall, API, file, registry, and dump analysis. · `src/plugins/procmon/procmon.cpp`
- [Output formatters](https://github.com/tklengyel/drakvuf/blob/main/src/plugins/output_format/ostream.cpp): serialization · Shared JSON, CSV, key-value, and default output. · `src/plugins/output_format/ostream.cpp`

### Control & Delivery

Injection, orchestration, and packaging paths.

- [Injector CLI](https://github.com/tklengyel/drakvuf/blob/main/src/injector.cpp): executable · Separate command boundary for active guest manipulation. · `src/injector.cpp`
- [libinjector](https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/injector.c): guest manipulation · Creates processes, executes shellcode, and transfers guest files. · `src/libinjector/injector.c`
- [Windows injection](https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/win/win_injector.c): platform method · `src/libinjector/win/win_injector.c`
- [Linux injection](https://github.com/tklengyel/drakvuf/blob/main/src/libinjector/linux/linux_injector.c): platform method · `src/libinjector/linux/linux_injector.c`
- [REPL control](https://github.com/tklengyel/drakvuf/blob/main/src/repl.cpp): operational control · `src/repl.cpp`
- [Build & packaging](https://github.com/tklengyel/drakvuf/blob/main/package/build.sh): delivery automation · Native builds and Debian/Xen package delivery. · `package/build.sh`

## Connections

- DRAKVUF runtime → Runtime coordinator: starts
- Runtime coordinator → libdrakvuf: uses
- Runtime coordinator → libhook: establishes hooks
- Runtime coordinator → Plugin registry: runs
- Runtime coordinator → REPL control: control path
- libdrakvuf → VMI adapter: integrates
- libdrakvuf → Guest OS abstraction: provides
- libdrakvuf → JSON profiles: consumes
- VMI adapter → Xen + libvmi: VMI calls
- Xen helper → Xen + libvmi: Xen controls
- Runtime coordinator → Xen helper: hypervisor control
- libhook → libdrakvuf: registers VMI events
- libhook → Syscall hooks: implements
- Plugin registry → Monitoring plugins: manages
- Monitoring plugins → libhook: consumes callbacks
- Monitoring plugins → libdrakvuf: queries guest state
- Monitoring plugins → Output formatters: serializes observations
- Injector CLI → libinjector: invokes
- libinjector → libdrakvuf: uses guest access
- libinjector → Windows injection: selects
- libinjector → Linux injection: selects
- libinjector → Xen + libvmi: controls guest externally
- Build & packaging → DRAKVUF runtime: delivers
- Build & packaging → Injector CLI: delivers
