{"id":13593679,"url":"https://github.com/memflow/memflow","last_synced_at":"2025-04-09T05:32:05.331Z","repository":{"id":40428688,"uuid":"259714075","full_name":"memflow/memflow","owner":"memflow","description":"physical memory introspection framework","archived":false,"fork":false,"pushed_at":"2025-03-28T10:04:08.000Z","size":13299,"stargazers_count":835,"open_issues_count":42,"forks_count":71,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-28T11:22:53.265Z","etag":null,"topics":["analysis","crate","introspection","linux","machine","memory","physical","rust","virtual"],"latest_commit_sha":null,"homepage":"https://memflow.github.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/memflow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-28T18:04:57.000Z","updated_at":"2025-03-28T10:04:12.000Z","dependencies_parsed_at":"2024-04-08T22:32:50.445Z","dependency_job_id":"1d132c19-4ed3-4b80-af90-68b2c94fac41","html_url":"https://github.com/memflow/memflow","commit_stats":{"total_commits":1175,"total_committers":10,"mean_commits":117.5,"dds":"0.33021276595744686","last_synced_commit":"ec4d19b5600597d0f9e463c3ad085af288f77f5c"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memflow%2Fmemflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memflow%2Fmemflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memflow%2Fmemflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memflow%2Fmemflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/memflow","download_url":"https://codeload.github.com/memflow/memflow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247986842,"owners_count":21028889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","crate","introspection","linux","machine","memory","physical","rust","virtual"],"created_at":"2024-08-01T16:01:23.097Z","updated_at":"2025-04-09T05:32:00.316Z","avatar_url":"https://github.com/memflow.png","language":"Rust","readme":"# memflow\n[![Crates.io](https://img.shields.io/crates/v/memflow.svg)](https://crates.io/crates/memflow)\n![build and test](https://github.com/memflow/memflow/workflows/Build%20and%20test/badge.svg?branch=dev)\n[![codecov](https://codecov.io/gh/memflow/memflow/branch/master/graph/badge.svg?token=XT7R158N6W)](https://codecov.io/gh/memflow/memflow)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Discord](https://img.shields.io/discord/738739624976973835?color=%20%237289da\u0026label=Discord)](https://discord.gg/afsEtMR)\n\n## machine introspection made easy\n\nmemflow is a library that enables introspection of various machines (hardware, virtual machines, memory dumps) in a generic fashion. There are 2 primary types of objects in memflow - _Connectors_ and _OS layers_. Connector provides raw access to physical memory of a machine. Meanwhile, OS layer builds a higher level abstraction over running operating system, providing access to running processes, input events, etc. These objects are incredibly flexible as they can be chained together to gain access to a process running multiple levels of virtualization deep (see figure below).\n\n```\n+-----------+        +-----------+\n| native OS |        | leechcore |\n+-+---------+        +-+---------+\n  |                    |\n  |  +-----------+     |  +----------+\n  +-\u003e|  QEMU VM  |     +-\u003e| Win32 OS |\n     +-+---------+        +-+--------+\n       |                    |\n       |  +----------+      |  +-----------+\n       +-\u003e| Win32 OS |      +-\u003e| lsass.exe |\n          +-+--------+         +-----------+\n            |\n            |  +-----------+\n            +-\u003e|  Hyper-V  |\n               +-+---------+\n                 |\n                 |  +----------+\n                 +-\u003e| Linux OS |\n                    +-+--------+\n                      |\n                      |  +-----------+\n                      +-\u003e| SSHD Proc |\n                         +-----------+\n\n(Example chains of access. For illustrative purposes only - Hyper-V Connector and Linux OS are not yet available)\n```\n\nAs a library user, you do not have to worry about delicacies of chaining - everything is provided, batteries included. See one of our [examples](memflow/examples/process_list.rs) on how simple it is to build a chain (excluding parsing). All Connectors and OS layers are dynamically loadable with common interface binding them.\n\nAll of this flexibility is provided with very robust and efficient backend - memory interface is batchable and divisible, which gets taken advantage of by our throughput optimized virtual address translation pipeline that is able to walk the entire process virtual address space in under a second. Connectors and OS layers can be composed with the vast library of generic caching mechanisms, utility functions and data structures.\n\nThe memflow ecosystem is not bound to just Rust - Connector and OS layer functions are linked together using C ABI, thus users can write code that interfaces with them in other languages, such as C, C++, Zig, etc. In addition, these plugins can too be implemented in foreign languages - everything is open.\n\nOverall, memflow is the most robust, efficient and flexible solution out there for machine introspection.\n\n## Getting started\n\nMake sure that your rustc version is at least `1.74.0` or newer.\n\nmemflow uses a plugin based approach and is capable of loading different physical memory backends (so-called [`connectors`](#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.\n\nTo get started, you want to at least install one connector. For that, use the [memflowup](https://github.com/memflow/memflowup) utility (use dev channel).\n\n### Manual installation\n\nThe recommended installation locations for connectors on Linux are:\n```\n/usr/lib/memflow/libmemflow_xxx.so\n$HOME/.local/lib/memflow/libmemflow_xxx.so\n```\n\nThe recommended installation locations for connectors on Windows are:\n```\n[Username]/Documents/memflow/libmemflow_xxx.dll\n```\n\nAdditionally, connectors can be placed in any directory of the environment PATH or the working directory of the program as well.\n\nFor more information about how to get started with memflow please head over to the YouTube series produced by [h33p](https://github.com/h33p/):\n\n- [memflow basics](https://www.youtube.com/playlist?list=PLrC4R7zDrxB3RSJQk9ahmXNCw8m3pdP6z)\n- [memflow applied](https://www.youtube.com/watch?v=xJXkRMy71dc\u0026list=PLrC4R7zDrxB17iWCy9eEdCaluCR3Bkn8q) (*the series is intended for memflow 0.1 so most of the code might actually need changes*)\n\n## Running Examples\n\nYou can either run one of the examples with `cargo run --release --example`. Pass nothing to get a list of examples.\n\nSome connectors like `qemu` will require elevated privileges. Refer to the readme of the connector for additional information on their required access rights.\n\nTo simplify running examples, tests, and benchmarks through different connectors, we added a simple cargo runner script for Linux to this repository.\nSimply set any of the following environment variables when running the `cargo` command to elevate privileges:\n\n- `RUST_SUDO` will start the resulting binary via sudo.\n- `RUST_SETPTRACE` will enable PTRACE permissions on the resulting binary before executing it.\n\nAlternatively, you can run the benchmarks via `cargo bench` (can pass regex filters). Win32 benchmarks currently work only on Linux.\n\nAll examples support the memflow connector `plugins` inventory system.\nYou will have to install at least one `connector` to use the examples. Refer to the [getting started](#getting-started) section for more details.\n\nRun memflow/read\\_keys example with a qemu connector:\n\n`RUST_SETPTRACE=1 cargo run --example read_keys -- -vv -c qemu -a [vmname] -o win32`\n\nRun memflow/read\\_bench example with a coredump connector:\n\n`cargo run --example read_bench --release -- -vv -c coredump -a coredump_win10_64bit.raw -o win32`\n\nNote: 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.\n\n## Documentation\n\nExtensive code documentation can be found at [docs.rs](https://docs.rs/memflow/0.2.0-beta/)\n(it currently is relatively out of date).\n\nAn additional getting started guide as well as a higher level\nexplanation of the inner workings of memflow can be found at [memflow.github.io](https://memflow.github.io).\n\nIf you decide to build the latest documentation you can do it by issuing:\n\n`cargo doc --workspace --no-deps --open`\n\n## Compilation support\n\nmemflow currently requires at least rustc version `1.74.0` or newer.\n\n| target        | build              | tests              | benches            | compiles on stable |\n|---------------|--------------------|--------------------|--------------------|--------------------|\n| linux x86_64  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| mac x86_64    | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| win x86_64    | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| linux aarch64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| linux i686    | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| linux armv7   | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| no-std        | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x:                |\n\n## Target support\n\nBy default, memflow supports analyzing 64-bit machines on any machine - be it 32 or 64 bit. Using memflow without `default_features` can disable 64-bit support on 32-bit machines for an efficiency gain, while enabling `128_bit_mem` feature can be done for theoretical future 128-bit machine analysis. Note that all connectors and OS layers must be compiled with the same memory features enabled, and memflowup currently only compiles the default set of features.\n\nmemflow-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.\n\n## Connectors\n\nAll examples provided in this repository are using the `plugins` inventory to\ndynamically load a connector at runtime. When using the library programmatically it is possible to just statically link a connector into the code.\n\nSome connectors also require different permissions. Please refer to the individual connector repositories for more information.\n\nThese are the currently officially existing connectors:\n- [qemu](https://github.com/memflow/memflow-qemu-procfs)\n- [kvm](https://github.com/memflow/memflow-kvm)\n- [pcileech](https://github.com/memflow/memflow-pcileech)\n- [coredump](https://github.com/memflow/memflow-coredump)\n\nIn 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.\n\n## Build on memflow\n\nOfficialy supported projects:\n- [memflow-py](https://github.com/memflow/memflow-py) Python Wrapper for memflow (thanks to [emesare](https://github.com/emesare))\n\n\nAdditional projects from the community:\n- [.NET wrapper for memflow-ffi](https://github.com/uberhalit/memflow.NET) by [uberhalit](https://github.com/uberhalit)\n- [rhai integration](https://github.com/dankope/rhai-memflow) by [emesare](https://github.com/emesare)\n- [connectors that exploit vulnerable windows drivers](https://github.com/a2x/memflow-vdm) by [a2x](https://github.com/a2x)\n\n## Acknowledgements\n- [CasualX](https://github.com/casualx/) for his wonderful pelite crate\n- [ufrisk](https://github.com/ufrisk/) for his prior work on the subject and many inspirations\n\n## Contributing\n\nPlease check [CONTRIBUTE.md](CONTRIBUTE.md)\n","funding_links":[],"categories":["Rust","Exploitation Tools"],"sub_categories":["Unikernel-like"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemflow%2Fmemflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmemflow%2Fmemflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemflow%2Fmemflow/lists"}