You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
147 lines
6.9 KiB
Markdown
147 lines
6.9 KiB
Markdown
4 years ago
|
# memflow
|
||
|
|
[](https://crates.io/crates/memflow)
|
||
|
|
|
||
|
|
[](https://codecov.io/gh/memflow/memflow)
|
||
|
|
[](LICENSE)
|
||
|
|
[](https://discord.gg/afsEtMR)
|
||
|
|
|
||
|
|
## physical memory introspection framework
|
||
|
|
|
||
|
|
memflow is a library that allows live memory introspection of running systems and their snapshots. Due to its modular approach it trivial to support almost any scenario where Direct Memory Access is available.
|
||
|
|
|
||
|
|
The very core of the library is a [PhysicalMemory](https://docs.rs/memflow/latest/memflow/mem/phys_mem/trait.PhysicalMemory.html) that provides direct memory access in an abstract environment. This object can be defined both statically, and dynamically with the use of the `inventory` feature. If `inventory` is enabled, it is possible to dynamically load libraries that provide Direct Memory Access.
|
||
|
|
|
||
|
|
Through the use of OS abstraction layers, like [memflow-win32](https://github.com/memflow/memflow/tree/master/memflow-win32), users can gain access to virtual memory of individual processes by creating objects that implement [VirtualMemory](https://docs.rs/memflow/latest/memflow/mem/virt_mem/trait.VirtualMemory.html).
|
||
|
|
|
||
|
|
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](https://github.com/memflow/memflow/tree/master/memflow-ffi) to interface with the library.
|
||
|
|
|
||
|
|
In the repository, you can find various examples available (which use the memflow-win32 layer)
|
||
|
|
|
||
|
|
## Building from source
|
||
|
|
|
||
|
|
To build all projects in the memflow workspace:
|
||
|
|
|
||
|
|
`cargo build --release --workspace`
|
||
|
|
|
||
|
|
To build all examples:
|
||
|
|
|
||
|
|
`cargo build --release --workspace --examples`
|
||
|
|
|
||
|
|
Run all tests:
|
||
|
|
|
||
|
|
`cargo test --workspace`
|
||
|
|
|
||
|
|
Execute the benchmarks:
|
||
|
|
|
||
|
|
`cargo bench`
|
||
|
|
|
||
|
|
## Documentation
|
||
|
|
|
||
|
|
Extensive code documentation can be found at [docs.rs](https://docs.rs/memflow/0.1/).
|
||
|
|
|
||
|
|
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](https://memflow.github.io).
|
||
|
|
|
||
|
|
If you decide to build the latest documentation you can do it by issuing:
|
||
|
|
|
||
|
|
`cargo doc --workspace --no-deps --open`
|
||
|
|
|
||
|
|
## Basic usage
|
||
|
|
|
||
|
|
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_procfs` will require elevated privileges. See the Connectors section of this Readme for more information.
|
||
|
|
|
||
|
|
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_SUDO` will start the resulting binary via sudo.
|
||
|
|
- `RUST_SETPTRACE` will 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.
|
||
|
|
|
||
|
|
## Running Examples
|
||
|
|
|
||
|
|
All examples support the memflow connector inventory system.
|
||
|
|
You will have to install at least one `connector` to use the examples.
|
||
|
|
|
||
|
|
To install a connector just use the [memflowup](https://github.com/memflow/memflowup) utility,
|
||
|
|
or, head over to the corresponding repository and install them via the `install.sh` script.
|
||
|
|
|
||
|
|
You will find a folder called `memflow` in any of the following locations:
|
||
|
|
```
|
||
|
|
/opt
|
||
|
|
/lib
|
||
|
|
/usr/lib/
|
||
|
|
/usr/local/lib
|
||
|
|
/lib32
|
||
|
|
/lib64
|
||
|
|
/usr/lib32
|
||
|
|
/usr/lib64
|
||
|
|
/usr/local/lib32
|
||
|
|
/usr/local/lib64
|
||
|
|
```
|
||
|
|
|
||
|
|
On Windows, you can put the connector DLL in a folder named `memflow`
|
||
|
|
that is either in your current PATH or put it in `C:\Users\{Username}\.local\lib\memflow`.
|
||
|
|
Additionally connectors can be placed in the working directory of the process as well.
|
||
|
|
|
||
|
|
Now you can just run the examples by providing the appropriate connector name:
|
||
|
|
|
||
|
|
Run memflow\_win32/read\_keys example with a procfs connector:
|
||
|
|
|
||
|
|
`RUST_SETPTRACE=1 cargo run --example read_keys -- -vv -c qemu_procfs -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_procfs` 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.
|
||
|
|
|
||
|
|
## Compilation support
|
||
|
|
|
||
|
|
| target | build | tests | benches | compiles on stable |
|
||
|
|
|---------------|--------------------|--------------------|--------------------|--------------------|
|
||
|
|
| linux x86_64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
||
|
|
| mac x86_64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
||
|
|
| win x86_64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
||
|
|
| linux aarch64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
||
|
|
| no-std | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
|
||
|
|
|
||
|
|
## Target support
|
||
|
|
|
||
|
|
memflow-win32 is tested on the latest 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.
|
||
|
|
|
||
|
|
## Connectors
|
||
|
|
|
||
|
|
All examples provided in this repository are using the 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:
|
||
|
|
- [qemu_procfs](https://github.com/memflow/memflow-qemu-procfs)
|
||
|
|
- [kvm](https://github.com/memflow/memflow-kvm)
|
||
|
|
- [pcileech](https://github.com/memflow/memflow-pcileech)
|
||
|
|
- [coredump](https://github.com/memflow/memflow-coredump)
|
||
|
|
|
||
|
|
In case you write your own connector please hit us up with a merge request so we can maintain a list of third-party connectors as well.
|
||
|
|
|
||
|
|
## Road map / Future Development
|
||
|
|
|
||
|
|
- Provide a rust native connector for PCILeech based hardware
|
||
|
|
- Provide a UEFI Demo
|
||
|
|
- Linux target support
|
||
|
|
|
||
|
|
## Acknowledgements
|
||
|
|
- [CasualX](https://github.com/casualx/) for his wonderful pelite crate
|
||
|
|
- [ufrisk](https://github.com/ufrisk/) for his prior work on the subject and many inspirations
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
Please check [CONTRIBUTE.md](CONTRIBUTE.md)
|