How tklengyel/drakvuf works
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: drakvuf.c libdrakvuf · drakvuf.cpp Runtime coordinator · injector.c libinjector · procmon.cpp Monitoring plugins
Components 19
Host & Hypervisor
External control and VMI boundary.
- DRAKVUF runtime · Main host-side analysis entry point.
src/main.cpp - Runtime coordinator · Initializes VMI, hooks, and plugin execution.
src/drakvuf.cpp - Xen + libvmi · External interface to guest execution and memory.
- Xen helper
src/xen_helper/xen_helper.c
Core Introspection
Guest-aware VMI and hook abstractions.
- libdrakvuf · Central guest introspection and semantic access layer.
src/libdrakvuf/drakvuf.c - VMI adapter
src/libdrakvuf/vmi.c - Guest OS abstraction · Resolves guest processes, objects, exports, and layouts.
src/libdrakvuf/os.c - JSON profiles · Compatibility boundary for guest symbols and types.
src/libdrakvuf/json-profile.c - libhook · Converts VMI events into reusable execution hooks.
src/libhook/libhook.hpp - Syscall hooks
src/libhook/hooks/syscall.cpp
Analysis Plugins
Compiled behavioral monitoring modules.
- Plugin registry · Loads and manages compiled analysis plugins.
src/plugins/plugins.cpp - Monitoring plugins · Process, syscall, API, file, registry, and dump analysis.
src/plugins/procmon/procmon.cpp - Output formatters · Shared JSON, CSV, key-value, and default output.
src/plugins/output_format/ostream.cpp
Control & Delivery
Injection, orchestration, and packaging paths.
- Injector CLI · Separate command boundary for active guest manipulation.
src/injector.cpp - libinjector · Creates processes, executes shellcode, and transfers guest files.
src/libinjector/injector.c - Windows injection
src/libinjector/win/win_injector.c - Linux injection
src/libinjector/linux/linux_injector.c - REPL control
src/repl.cpp - Build & packaging · Native builds and Debian/Xen package delivery.
package/build.sh
Connections 24
- 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