1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
//! .NET Runtime simulation for emulation.
//!
//! This module provides runtime services for .NET Common Language Runtime (CLR) emulation,
//! enabling the execution of .NET bytecode in a controlled, sandboxed environment. The runtime
//! module is essential for deobfuscation, malware analysis, and static analysis of .NET
//! assemblies where actual execution is not desirable or possible.
//!
//! # Overview
//!
//! The runtime module simulates key aspects of the .NET CLR:
//!
//! - **Hook System**: Flexible method interception with pattern matching and pre/post hooks
//! - **BCL Implementations**: Native implementations of Base Class Library methods
//! - **Native Interop**: P/Invoke support for Windows API calls commonly used by obfuscators
//! - **Application Domain**: Simulation of .NET AppDomain behavior including assembly loading
//!
//! # Key Components
//!
//! - [`RuntimeState`] - Central runtime state management that coordinates all runtime services
//! - [`HookManager`] - Registry for method interception hooks
//! - [`Hook`] - Builder for creating method hooks with matchers and handlers
//! - [`AppDomainState`] - Application domain simulation with type hierarchy tracking
//! - [`native`] - P/Invoke hooks for Windows API emulation
//!
//! # Architecture
//!
//! The runtime module integrates with the emulation engine through several layers:
//!
//! ```text
//! +-------------------+
//! | EmulationEngine |
//! +--------+----------+
//! |
//! v
//! +--------+----------+ +-------------------+
//! | RuntimeState +---->| HookManager |
//! +--------+----------+ | (BCL + Native) |
//! | +-------------------+
//! |
//! +--------------->+-------------------+
//! | AppDomainState |
//! +-------------------+
//! ```
//!
//! ## Hook Resolution Order
//!
//! When a method call is encountered during emulation:
//!
//! 1. **Hook Matching**: Check [`HookManager`] for matching hooks (by priority)
//! 2. **Pre-Hook**: Execute pre-hook (can bypass original method)
//! 3. **Original Method**: Execute if not bypassed
//! 4. **Post-Hook**: Execute post-hook (can modify return value)
//! 5. **Default Behavior**: Apply [`UnknownMethodBehavior`] if no hook matches
//!
//! # Examples
//!
//! ## Basic Runtime Setup
//!
//! ```ignore
//! use dotscope::emulation::runtime::{RuntimeState, RuntimeStateBuilder};
//!
//! // Create runtime with default BCL hooks
//! let runtime = RuntimeState::new();
//!
//! // Or use the builder for custom configuration
//! let runtime = RuntimeStateBuilder::new()
//! .config(EmulationConfig::minimal())
//! .build();
//! ```
//!
//! ## Registering Custom Hooks
//!
//! ```ignore
//! use dotscope::emulation::runtime::{RuntimeState, Hook, PreHookResult};
//!
//! let mut runtime = RuntimeState::new();
//! runtime.hooks_mut().register(
//! Hook::new("my-hook")
//! .match_name("MyNamespace", "MyType", "MyMethod")
//! .pre(|ctx, thread| {
//! PreHookResult::Bypass(Some(EmValue::I32(42)))
//! })
//! );
//! ```
//!
//! # Use Cases
//!
//! ## Deobfuscation
//!
//! The runtime module is designed to support deobfuscation of protected .NET assemblies:
//!
//! - **String Decryption**: Emulate decryption methods to recover original strings
//! - **Control Flow**: Execute dispatcher methods to reconstruct original control flow
//! - **Anti-Debug Bypass**: Native stubs return "not debugged" for anti-debugging checks
//!
//! ## Malware Analysis
//!
//! Safe analysis of potentially malicious .NET code:
//!
//! - **Sandboxed Execution**: Methods execute in a controlled environment
//! - **API Monitoring**: Track what native APIs the code attempts to call
//! - **Behavior Analysis**: Observe runtime behavior without actual execution
//!
//! # Thread Safety
//!
//! The runtime module is designed for single-threaded emulation. While [`RuntimeState`]
//! uses thread-safe primitives internally, concurrent access to a single runtime instance
//! from multiple threads is not supported. For multi-threaded scenarios, create separate
//! runtime instances per thread.
pub use ;
pub use get_bcl_static_field;
pub use ;
pub use ;