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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
//! Hook system for method interception during emulation.
//!
//! This module provides the hook system for intercepting method calls during .NET
//! emulation. Hooks support:
//!
//! - **Multiple matching criteria**: Match by name, signature types, or runtime data
//! - **Pre/post execution**: Run code before and/or after the original method
//! - **Bypass capability**: Pre-hooks can skip the original method entirely
//! - **Closure-based handlers**: Less boilerplate than trait implementations
//!
//! # Overview
//!
//! The hook system provides flexible method interception with multiple matching
//! criteria:
//!
//! - **Name matching**: Match by namespace, type name, and/or method name
//! - **Signature matching**: Match by parameter types and return type
//! - **Internal method matching**: Match only methods defined in the target assembly
//! - **Runtime matching**: Match by inspecting actual argument values
//!
//! # Organization
//!
//! | Module | Description |
//! |--------|-------------|
//! | [`types`] | Core types: priorities, results, context |
//! | [`matcher`] | Matcher trait and implementations |
//! | [`hook`] | The [`Hook`] builder and executor |
//! | [`manager`] | [`HookManager`] for hook registration and lookup |
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │ HookManager │
//! │ ┌─────────────────────────────────────────────────────┐ │
//! │ │ hooks: Vec<Hook> (sorted by priority) │ │
//! │ └─────────────────────────────────────────────────────┘ │
//! │ │ │
//! │ ▼ │
//! │ ┌─────────────────────────────────────────────────────┐ │
//! │ │ find_matching(context) -> Option<&Hook> │ │
//! │ │ execute_pre(hook, context) -> PreHookResult │ │
//! │ │ execute_post(hook, context, result) -> PostResult │ │
//! │ └─────────────────────────────────────────────────────┘ │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Hook Execution Flow
//!
//! ```text
//! Method call intercepted
//! │
//! ▼
//! ┌───────────────────┐
//! │ Find matching │───► No match ───► Execute original
//! │ hook │
//! └───────────────────┘
//! │ Match found
//! ▼
//! ┌───────────────────┐
//! │ Execute pre_hook │───► Bypass(value) ───► Return value
//! └───────────────────┘
//! │ Continue
//! ▼
//! ┌───────────────────┐
//! │ Execute original │
//! │ method │
//! └───────────────────┘
//! │
//! ▼
//! ┌───────────────────┐
//! │ Execute post_hook│───► Can modify result
//! └───────────────────┘
//! │
//! ▼
//! Return result
//! ```
//!
//! # Examples
//!
//! ## Simple Name-Based Hook
//!
//! ```rust,ignore
//! use dotscope::emulation::{Hook, HookManager, PreHookResult};
//!
//! let mut manager = HookManager::new();
//!
//! manager.register(
//! Hook::new("log-assembly-load")
//! .match_name("System.Reflection", "Assembly", "Load")
//! .pre(|ctx, thread| {
//! println!("Assembly.Load called!");
//! PreHookResult::Continue
//! })
//! );
//! ```
//!
//! ## Signature-Based Hook with Bypass
//!
//! ```rust,ignore
//! use dotscope::emulation::{Hook, HookManager, PreHookResult};
//! use dotscope::metadata::typesystem::CilFlavor;
//!
//! let mut manager = HookManager::new();
//!
//! // Intercept byte[] -> byte[] methods that look like LZMA
//! manager.register(
//! Hook::new("confuserex-lzma")
//! .match_internal_method()
//! .match_signature(vec![CilFlavor::Array { .. }], Some(CilFlavor::Array { .. }))
//! .match_runtime("lzma-header", |ctx, thread| {
//! // Check if input looks like LZMA data
//! is_confuserex_lzma_header(ctx, thread)
//! })
//! .pre(|ctx, thread| {
//! let decompressed = decompress_lzma(ctx, thread);
//! PreHookResult::Bypass(Some(decompressed))
//! })
//! );
//! ```
//!
//! # Use Cases
//!
//! ## Deobfuscation
//!
//! Hooks are particularly useful for deobfuscation scenarios:
//!
//! - **LZMA decompression**: Bypass embedded LZMA decompressors with native code
//! - **String decryption**: Capture arguments to custom decryption methods
//! - **Control flow recovery**: Monitor dispatcher state variable updates
//!
//! ## BCL Method Emulation
//!
//! Hooks provide implementations for .NET Base Class Library methods:
//!
//! - **String operations**: `String.Concat`, `String.Substring`, etc.
//! - **Encoding**: `Encoding.GetBytes`, `Encoding.GetString`
//! - **Cryptography**: MD5, SHA1, SHA256 hash computations
//! - **Array operations**: `Array.Copy`, `Buffer.BlockCopy`
//!
//! ## Malware Analysis
//!
//! For malware analysis, hooks can:
//!
//! - Capture encryption keys passed to crypto methods
//! - Log all method calls matching certain patterns
//! - Replace dangerous operations with safe alternatives
pub use Hook;
pub use HookManager;
pub use ;
pub use ;