# mwemuorg/mwemu architecture

> Architecture diagram of the GitHub repository mwemuorg/mwemu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mwemuorg/mwemu
- Repository: https://github.com/mwemuorg/mwemu

## Overview

MWEmu is a hardware emulator and OS process simulator aimed at malware analysis. Its central workflow is to load a PE, ELF, or shellcode image, configure an emulated architecture and process, execute instructions while simulating OS services, then inspect or trace the resulting state. Users can access the runtime through the CLI, Rust library, Python/C bindings, or an MCP server. The graph preserves documented execution, debugging, exception, and platform capabilities; many internal links are omitted because their implementation paths were not sampled.

Main entry points: [`crates/libmwemu/src/emu/execution/mod.rs`](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/execution/mod.rs) (Instruction execution), [`crates/libmwemu/src/emu/emu_context.rs`](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/emu_context.rs) (Emulator context), [`crates/libmwemu/src/emu/loaders.rs`](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/loaders.rs) (Image loading), [`crates/mwemu/src/main.rs`](https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu/src/main.rs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.rs]"]
  node_rust["Rust API<br/>[lib.rs]"]
  node_python["Python binding<br/>[lib.rs]"]
  node_capi["C binding<br/>[lib.rs]"]
  node_mcp["MCP server<br/>[server.rs]"]
  node_mcp_tools["MCP tools<br/>[tools.rs]"]
end

subgraph group_runtime["Emulation runtime"]
  node_loader["Image loading<br/>[loaders.rs]"]
  node_emulator["Emulator context<br/>[emu_context.rs]"]
  node_execution["Instruction execution<br/>[mod.rs]"]
  node_engine["Instruction engine<br/>[mod.rs]"]
  node_memory["Virtual memory<br/>[memory.rs]"]
end

subgraph group_platform["OS simulation"]
  node_api_sim["OS API simulation<br/>[export_index.rs]"]
  node_syscalls["Linux syscalls<br/>[libc.rs]"]
  node_exceptions["Exception handling"]
end

subgraph group_analysis["Analysis and state"]
  node_debugger["Interactive debugger<br/>[console.rs]"]
  node_tracking["State tracking<br/>[trace.rs]"]
  node_snapshots["Process snapshots<br/>[linux.rs]"]
end

subgraph group_formats["Executable formats"]
  node_pe["PE parsing<br/>[parser.rs]"]
  node_elf["ELF loading<br/>[loader.rs]"]
end

node_user(("Analyst"))

node_user -->|"runs"| node_cli
node_cli -->|"uses library"| node_rust
node_user -->|"connects"| node_mcp
node_mcp -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"controls session"| node_emulator
node_user -->|"uses library"| node_rust
node_user -->|"uses binding"| node_python
node_user -->|"uses binding"| node_capi
node_emulator -.->|"loads images"| node_loader
node_loader -.->|"parses PE"| node_pe
node_loader -.->|"loads ELF"| node_elf
node_emulator -.->|"runs instructions"| node_execution
node_execution -.->|"executes decoded"| node_engine
node_execution -.->|"accesses memory"| node_memory
node_execution -.->|"dispatches APIs"| node_api_sim
node_execution -.->|"dispatches syscalls"| node_syscalls
node_execution -->|"handles faults"| node_exceptions
node_user -->|"inspects state"| node_debugger
node_emulator -.->|"tracks state"| node_tracking
node_user -.->|"captures state"| node_snapshots

click node_cli "https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu/src/main.rs"
click node_rust "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/lib.rs"
click node_python "https://github.com/mwemuorg/mwemu/blob/main/crates/pymwemu/src/lib.rs"
click node_capi "https://github.com/mwemuorg/mwemu/blob/main/crates/cmwemu/src/lib.rs"
click node_mcp "https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-mcp/src/server.rs"
click node_mcp_tools "https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-mcp/src/tools.rs"
click node_loader "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/loaders.rs"
click node_emulator "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/emu_context.rs"
click node_execution "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/execution/mod.rs"
click node_engine "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/engine/mod.rs"
click node_memory "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/memory.rs"
click node_pe "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/libraries/rs-header/src/pe/pe32/parser.rs"
click node_elf "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/libraries/rs-header/src/elf/loader.rs"
click node_api_sim "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/api/windows/export_index.rs"
click node_syscalls "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/api/linux/libc.rs"
click node_exceptions "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/exception_handlers.rs"
click node_debugger "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/debug/console.rs"
click node_tracking "https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/trace.rs"
click node_snapshots "https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-snapshot/src/linux.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_rust,node_python,node_capi,node_mcp,node_mcp_tools toneBlue
class node_loader,node_emulator,node_execution,node_engine,node_memory toneAmber
class node_api_sim,node_syscalls,node_exceptions toneMint
class node_debugger,node_tracking,node_snapshots toneRose
class node_pe,node_elf,node_user toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu/src/main.rs): `crates/mwemu/src/main.rs`
- [Rust API](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/lib.rs): `crates/libmwemu/src/lib.rs`
- [Python binding](https://github.com/mwemuorg/mwemu/blob/main/crates/pymwemu/src/lib.rs): `crates/pymwemu/src/lib.rs`
- [C binding](https://github.com/mwemuorg/mwemu/blob/main/crates/cmwemu/src/lib.rs): `crates/cmwemu/src/lib.rs`
- [MCP server](https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-mcp/src/server.rs): `crates/mwemu-mcp/src/server.rs`
- [MCP tools](https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-mcp/src/tools.rs): `crates/mwemu-mcp/src/tools.rs`

### Emulation runtime

- [Image loading](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/loaders.rs): `crates/libmwemu/src/emu/loaders.rs`
- [Emulator context](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/emu_context.rs): `crates/libmwemu/src/emu/emu_context.rs`
- [Instruction execution](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/execution/mod.rs): `crates/libmwemu/src/emu/execution/mod.rs`
- [Instruction engine](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/engine/mod.rs): `crates/libmwemu/src/engine/mod.rs`
- [Virtual memory](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/memory.rs): `crates/libmwemu/src/emu/memory.rs`

### OS simulation

- [OS API simulation](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/api/windows/export_index.rs): `crates/libmwemu/src/api/windows/export_index.rs`
- [Linux syscalls](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/api/linux/libc.rs): `crates/libmwemu/src/api/linux/libc.rs`
- [Exception handling](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/exception_handlers.rs): `crates/libmwemu/src/emu/exception_handlers.rs`

### Analysis and state

- [Interactive debugger](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/debug/console.rs): `crates/libmwemu/src/debug/console.rs`
- [State tracking](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/src/emu/trace.rs): `crates/libmwemu/src/emu/trace.rs`
- [Process snapshots](https://github.com/mwemuorg/mwemu/blob/main/crates/mwemu-snapshot/src/linux.rs): `crates/mwemu-snapshot/src/linux.rs`

### Executable formats

- [PE parsing](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/libraries/rs-header/src/pe/pe32/parser.rs): `crates/libmwemu/libraries/rs-header/src/pe/pe32/parser.rs`
- [ELF loading](https://github.com/mwemuorg/mwemu/blob/main/crates/libmwemu/libraries/rs-header/src/elf/loader.rs): `crates/libmwemu/libraries/rs-header/src/elf/loader.rs`

### Other components

- **Analyst**

## Connections

- Analyst → CLI: runs (evidence: `README.md`)
- CLI → Rust API: uses library
- Analyst → MCP server: connects
- MCP server → MCP tools: dispatches tools (evidence: `crates/mwemu-mcp/src/server.rs`)
- MCP tools → Emulator context: controls session (evidence: `crates/mwemu-mcp/src/tools.rs`)
- Analyst → Rust API: uses library (evidence: `README.md`)
- Analyst → Python binding: uses binding (evidence: `README.md`)
- Analyst → C binding: uses binding (evidence: `README.md`)
- Emulator context → Image loading: loads images
- Image loading → PE parsing: parses PE
- Image loading → ELF loading: loads ELF
- Emulator context → Instruction execution: runs instructions
- Instruction execution → Instruction engine: executes decoded
- Instruction execution → Virtual memory: accesses memory
- Instruction execution → OS API simulation: dispatches APIs
- Instruction execution → Linux syscalls: dispatches syscalls
- Instruction execution → Exception handling: handles faults (evidence: `crates/libmwemu/src/emu/exception_handlers.rs`)
- Analyst → Interactive debugger: inspects state (evidence: `README.md`)
- Emulator context → State tracking: tracks state
- Analyst → Process snapshots: captures state
