memflow is a library that allows live memory introspection of running systems and their snapshots. Due to its modular approach, it is trivial to support almost any scenario where Direct Memory Access is available.
The very core of the library is a PhysicalMemory that provides direct memory access in an abstract environment. This object that can be defined both statically, and dynamically with the use of the plugins feature. If plugins is enabled, it is possible to dynamically load libraries that provide Direct Memory Access.
Through the use of OS abstraction layers, like memflow-win32, users can gain access to virtual memory of individual processes by creating objects that implement VirtualMemory.
Bridging the two is done by a highly throughput optimized virtual address translation function, which allows for crazy fast memory transfers at scale.
The core is architecture-independent (as long as addresses fit in 64-bits), and currently, both 32, and 64-bit versions of the x86 family are available to be used.
For non-rust libraries, it is possible to use the FFI to interface with the library.
In the repository, you can find various examples available (which use the memflow-win32 layer)
Make sure that your rustc version is at least 1.51.0 or newer.
memflow uses a plugin based approach and is capable of loading different physical memory backends (so-called connectors) at runtime. On top of the physical memory backends memflow is also capable of loading plugins for interfacing with a specific target OS at runtime.
To get started, you want to at least install one connector. On Linux based hosts you can simply execute the install.sh found in each connector repository to install the connector. When running ./install.sh --system the connector is installed system-wide. When omitting the --system argument the connector is just installed for the current user.
When using the memflow-daemon it is required to install each connector system-wide (or at least under the root user) so the daemon can access it. Some connectors also require elevated privileges, which might also require them to be accessible from the root user.
Note that all connectors should be built with the --all-features flag to be accessible as a dynamically loaded plugin.
The recommended installation locations for connectors on Linux are:
/usr/lib/memflow/libmemflow_xxx.so
$HOME/.local/lib/memflow/libmemflow_xxx.so
The recommended installation locations for connectors on Windows are:
[Username]/Documents/memflow/libmemflow_xxx.dll
Additionally, connectors can be placed in any directory of the environment PATH or the working directory of the program as well.
For Windows target support the win32 plugin has to be built:
cargo build --release --all-features --workspaceThis will create the OS plugin in target/release/libmemflow_win32.so which has to be copied to one of the plugin folders mentioned above.
For more information about how to get started with memflow please head over to the YouTube series produced by h33p:
You can either run one of the examples with cargo run --release --example. Pass nothing to get a list of examples.
Some connectors like qemu will require elevated privileges. Refer to the readme of the connector for additional information on their required access rights.
To simplify running examples, tests, and benchmarks through different connectors, we added a simple cargo runner script for Linux to this repository.
Simply set any of the following environment variables when running the cargo command to elevate privileges:
RUST_SUDOwill start the resulting binary via sudo.RUST_SETPTRACEwill enable PTRACE permissions on the resulting binary before executing it.
Alternatively, you can run the benchmarks via cargo bench (can pass regex filters). Win32 benchmarks currently work only on Linux.
All examples support the memflow connector plugins inventory system.
You will have to install at least one connector to use the examples. Refer to the getting started section for more details.
Run memflow_win32/read_keys example with a procfs connector:
RUST_SETPTRACE=1 cargo run --example read_keys -- -vv -c qemu -a [vmname]
Run memflow_win32/read_bench example with a coredump connector:
cargo run --example read_bench --release -- -vv -c coredump -a coredump_win10_64bit.raw
Note: In the examples above the qemu connector requires 'CAP_SYS_PTRACE=ep' permissions. The runner script in this repository will set the appropriate flags when the RUST_SETPTRACE environment variable is passed to it.
Extensive code documentation can be found at docs.rs.
An additional getting started guide as well as a higher level explanation of the inner workings of memflow can be found at memflow.github.io.
If you decide to build the latest documentation you can do it by issuing:
cargo doc --workspace --no-deps --open
memflow currently requires at least rustc version 1.51.0 or newer.
| target | build | tests | benches | compiles on stable |
|---|---|---|---|---|
| linux x86_64 | ✔️ | ✔️ | ✔️ | ✔️ |
| mac x86_64 | ✔️ | ✔️ | ✔️ | ✔️ |
| win x86_64 | ✔️ | ✔️ | ✔️ | ✔️ |
| linux aarch64 | ✔️ | ✔️ | ✔️ | ✔️ |
| no-std | ✔️ | ✔️ | ✔️ | ❌ |
memflow-win32 is tested on the latest Windows 11 and Windows 10 versions all the way down to Windows NT 4.0. If you found a version that does not work please submit an issue with the major/minor version as well as the build number.
All examples provided in this repository are using the plugins inventory to
dynamically load a connector at runtime. When using the library programmatically it is possible to just statically link a connector into the code.
Some connectors also require different permissions. Please refer to the individual connector repositories for more information.
These are the currently officially existing connectors:
In case you write your own connector please hit us up with a pull request so we can maintain a list of third-party connectors as well.
- CasualX for his wonderful pelite crate
- ufrisk for his prior work on the subject and many inspirations
Please check CONTRIBUTE.md