memflow: a plugin framework for reading the memory of running machines

Two object kinds, and the chain between them

memflow is described as a library that enables introspection of various machines, hardware, virtual machines, memory dumps, in a generic fashion. The whole design turns on two kinds of object.

A Connector provides raw access to the physical memory of a machine. An OS layer builds a higher level abstraction over a running operating system, providing access to running processes, input events and the like. The two are joined by chaining: a connector is paired with an OS layer to produce a view of a process.

The chaining is the point, and the diagram in the README makes it concrete. A QEMU virtual machine containing a Win32 OS containing lsass.exe is one chain. A native OS containing a QEMU VM containing a Win32 OS containing a Hyper-V guest containing a Linux OS containing an SSHD process is another, deeper chain. On the right of the same figure, leechcore is a connector and Win32 OS is the layer above it.

The diagram comes with an honesty note: for illustrative purposes only, Hyper-V Connector and Linux OS are not yet available. So the deep chains are the design goal and the diagram shows the shape, and the connectors and layers that exist today cover less of it.

What this buys you is the abstraction boundary. The code that walks a process's memory does not know whether the bytes came from a hypervisor, from a PCIe device, or from a file on disk. It asks an OS layer for a process, and the OS layer asks a connector for memory. A tool written against that interface can be pointed at a QEMU guest today and at a memory dump tomorrow, and the difference is the plugin you load, not the analysis code.

The audience is therefore security researchers, malware analysts, forensics tooling authors and anyone who has wanted to inspect a running system without writing a hypervisor-specific memory reader for each one.

Connectors and OS layers are plugins loaded at runtime

memflow uses a plugin based approach and is capable of loading different physical memory backends, the so-called connectors, at runtime. On top of the physical memory backends it is also capable of loading plugins for interfacing with a specific target OS at runtime.

As a library user, the README says you do not have to worry about the delicacies of chaining, everything is provided, batteries included, and points to an example on how simple it is to build a chain. The example is memflow/examples/process_list.rs.

The runtime loading is the mechanism that makes the composition practical. Connectors are shared objects loaded on demand rather than compiled in, which means the same binary can talk to a QEMU guest or to a coredump file without being rebuilt, and a connector can be updated without rebuilding the consumer. The plugins inventory system, which the README says all examples support, is the part that lets you select a connector and an OS layer from a configuration rather than in code.

The connector selection syntax is a small string format, and it is worth knowing because it is what you will type. The general format is [connector]:[target_name]:[additional_arguments], where the additional arguments are a comma-separated key-value list like a=b,c=d. The key of the default argument can be omitted, so b,c=d is valid where a was the default key, and the individual connector documentation covers the available arguments. A concrete invocation from the README:

RUST_SETPTRACE=1 cargo run --example keyboard -- -vv -c qemu:[vmname] -o win32

Here -c selects the qemu connector with an optional VM name, and -o selects the win32 OS layer. The vmname can be omitted entirely, and the README gives the shorter form:

RUST_SETPTRACE=1 cargo run --example keyboard -- -vv -c qemu -o win32

The connector format is uniform across connectors, which is what makes the chaining composable. The same -c and -o shape selects a coredump connector:

cargo run --example read_bench --release -- -vv -c coredump:coredump_win10_64bit.raw: -o win32

The core crate itself is Rust, and the workspace in Cargo.toml has three members, memflow, memflow-ffi and memflow-bench, with memflow-derive also present as a directory. The FFI crate is the important one for the portability claim: Connector and OS layer functions are linked together using the C ABI, so users can write code that interfaces with them in other languages such as C, C++ and Zig, and the plugins can themselves be implemented in foreign languages.

Batchable memory access and the address translation pipeline

The performance claim in the README is specific and architectural rather than a benchmark table. All of this flexibility is provided with a very robust and efficient backend, where the memory interface is batchable and divisible, which gets taken advantage of by a throughput optimized virtual address translation pipeline that is able to walk the entire process virtual address space in under a second.

The design idea is worth unpacking because it is what makes a plugin-based introspection system viable rather than a toy. Reading guest physical memory over PCIe or a hypervisor interface is expensive per call, and a naive implementation that reads a page at a time spends its time in round trips. Making the memory interface batchable means a single call can request a set of pages, and divisible means a request can be split, which is what lets the pipeline overlap fetching with translating.

The virtual address translation pipeline is the second half. A process's virtual addresses have to be resolved to physical addresses before the connector can fetch them, and that resolution has to happen for every page of the process. Doing that as a streamed pipeline rather than a two-phase approach, fetch the whole table then translate, is what gets the walk under a second. The README also says connectors and OS layers can be composed with the vast library of generic caching mechanisms, utility functions and data structures.

Caching is the other half of the story. An OS layer that translates virtual to physical addresses will translate the same addresses repeatedly, and the physical-to-virtual direction has the same property, so a cache at the right level removes most of the repeated work. This is why the library is composed out of plugins at all: the caching, the translation and the raw access are separable concerns, and a consumer picks the combination it needs.

The benchmark tooling is in the repository as memflow-bench/, and the README notes that benchmarks can be run via cargo bench with regex filters, and that the Win32 benchmarks currently work only on Linux.

Installing connectors, and the privilege question behind them

Getting started requires rustc 1.82.0 or newer, and at least one connector installed. The recommended way is the memflowup utility, with the note to use its dev channel.

The manual route is to place the shared object somewhere the loader looks. On Linux the recommended locations are:

/usr/lib/memflow/libmemflow_xxx.so
$HOME/.local/lib/memflow/libmemflow_xxx.so

On Windows the recommended location is:

[Username]/Documents/memflow/libmemflow_xxx.dll

Additionally, connectors can be placed in any directory on the environment PATH or in the working directory of the program. That last point matters for testing, since it means a connector can be dropped next to a binary without touching system directories.

The privilege question is the real constraint here. Some connectors like qemu will require elevated privileges, and the README says to refer to the readme of the connector for additional information on their required access rights. It is specific in the examples: the qemu connector requires 'CAP_SYS_PTRACE=ep' permissions, and the runner script in the repository will set the appropriate flags when the RUST_SETPTRACE environment variable is passed to it.

The runner script exists because that is a recurring annoyance. To simplify running examples, tests, and benchmarks through different connectors, a simple cargo runner script for Linux was added to the repository, and setting any of the following environment variables when running the cargo command elevates privileges. RUST_SUDO will start the resulting binary via sudo. RUST_SETPTRACE will enable PTRACE permissions on the resulting binary before executing it.

So there are two ways to get the permissions a connector needs, and they differ in what they grant. RUST_SETPTRACE is the narrower one, enabling PTRACE on the binary, and the README prefers it in the examples. RUST_SUDO runs the whole binary as root, which is broader than the connector needs and which you would not want as a habit.

This is the security-relevant part of the whole project, and it deserves a plain statement. A connector that reads physical memory is a component with deep access to the machine, and the process running it will be privileged. A connector is a shared object loaded into your process, so the trust question extends to whoever publishes it.

The gaps: docs, the version line, and what is not there yet

There are three honest limitations, and they are of different kinds.

The first is documentation. The README says extensive code documentation can be found at docs.rs, and then adds, in parentheses, that it currently is relatively out of date. It also mentions an additional getting started guide and a higher level explanation of the inner workings, and the sentence trails off there. So the documentation exists but is acknowledged as stale, which is a meaningful caveat for a library whose interface is large.

The second is the version line. The repository is not archived and the last push was on 2026-04-24, so work is continuing. But the release list tells a different story about what has shipped: 0.2.3 on 2024-07-31, 0.2.1 and 0.2.0 both on 2024-05-06. The 0.2.x line is what the crates.io badge points at, and the newest tagged release of the core library is roughly twenty months older than the last commit on the branch. Note also that the crate documentation link points at a 0.2.0-beta path, so the published docs and the current version do not line up exactly.

There is a CHANGES.md and a RELEASE.md at the repository root, which is where the version history lives rather than in release notes on the page.

The third is the availability of the components the design promises. The diagram itself flags that the Hyper-V Connector and Linux OS are not yet available. The connectors named in the examples are qemu and coredump, and the OS layer named is win32. The README's own example set stays with the Windows layer, and the benchmarks for the Win32 layer run on Linux.

There is also a no_std test crate, nostd-test/, which is excluded from the workspace in Cargo.toml. Its presence says the library is intended to work without the standard library, which is a meaningful constraint for anyone embedding memflow in a constrained environment, though the repository does not document the feature set in the visible README.

And a smaller one: the README closes by claiming that memflow is the best of the available solutions for machine introspection, on efficiency and flexibility as well as robustness. That is a self-assessment from the project's own documentation, not a measurement, and it is the kind of claim you should discount when reading a project's README about itself.

memflow against reading memory the direct way

The alternative is not one thing but two, and the differences in approach matter.

The first alternative is a hypervisor-specific or device-specific memory reader. If your target is always a QEMU guest on KVM, a small library that talks to the KVM API directly does the job with far fewer layers, no plugin loading and no C ABI. That is a genuinely better fit for a tool that will only ever see one kind of target. The cost of memflow's generality is that you load a plugin, pass data through an abstraction boundary and pay for the flexibility whether or not you use it.

The second alternative is offline analysis of a memory image. A coredump connector and a forensics tool that reads a raw file are two paths to the same bytes, and the offline path has real advantages: no privileges on a live machine, no risk of perturbing the system under investigation, and the image can be examined repeatedly. The memflow coredump connector is exactly this, and it sits in the same plugin model, so the same analysis code can be pointed at a live guest or a file.

What memflow does that neither alternative does is present one interface across both, and across a stack of virtualization. The diagram's deep chain, a Linux process inside a Hyper-V guest inside a QEMU VM inside a native OS, is the case where a purpose-built reader would have to be rewritten for each level, and where a hypervisor-native tool for the outer layer plus a guest agent for the inner layer is a different and more fragile architecture.

The fourth option is not to read process memory at all. Much of what a tool wants to know about a running system is available through its normal interfaces, and a userland agent inside the guest can report on processes, files and input events without any of the privilege that physical memory access requires. memflow's own OS layer provides access to running processes and input events, which is the same information an agent would give you. The difference in approach is where the code runs: memflow's model puts the reader outside the guest, at the hypervisor or device boundary, which is what makes it work when the guest is hostile or unreachable.

So the deciding question is whether your target is one fixed environment or several. One fixed environment and a focused tool is simpler with a direct reader. Several environments, or a tool that has to work on a dump and on a live system, is what the connector and OS layer split buys you, and that is the case the project is built for.

Editorial conclusion

Adopt memflow if you are writing a tool that has to read the memory of a running machine, a virtual machine or a dump, and you want the connector and OS abstraction separated so the same analysis code works across hypervisors. Do not adopt it if you need live, monitored memory access on a production host, since the connectors documented here reach physical memory through hypervisor interfaces and DMA, and a dump or a paused guest is a different and safer operating assumption. Verify first that the connector you need exists and that its privilege requirements match your environment, since the qemu connector wants CAP_SYS_PTRACE=ep, and that the OS layer you pair with it supports the guest you are targeting.

Frequently asked questions

Official sources

1. License: MIT
2. memflow/memflow on GitHub
3. Project website
4. README
5. Releases