wraith/
error.rs

1//! Unified error types for wraith-rs
2
3use core::fmt;
4
5/// all errors that can occur in wraith-rs
6#[derive(Debug)]
7pub enum WraithError {
8    // === version/architecture ===
9    /// windows version not supported by this library
10    UnsupportedWindowsVersion { major: u32, minor: u32, build: u32 },
11
12    /// architecture not supported (e.g., ARM)
13    UnsupportedArchitecture,
14
15    // === structure access ===
16    /// failed to access PEB
17    InvalidPebAccess,
18
19    /// failed to access TEB
20    InvalidTebAccess,
21
22    /// structure data appears corrupted
23    CorruptedStructure {
24        name: &'static str,
25        reason: &'static str,
26    },
27
28    /// null pointer where non-null expected
29    NullPointer { context: &'static str },
30
31    // === navigation ===
32    /// module with given name not found
33    ModuleNotFound { name: String },
34
35    /// address does not belong to any loaded module
36    AddressNotInModule { address: u64 },
37
38    /// thread with given ID not found
39    ThreadNotFound { tid: u32 },
40
41    // === manipulation ===
42    /// failed to unlink module from PEB lists
43    UnlinkFailed { module: String, reason: String },
44
45    /// failed to restore module links
46    RelinkFailed { module: String, reason: String },
47
48    /// PEB module list appears corrupted
49    ListCorrupted { list_type: ModuleListType },
50
51    // === manual mapping ===
52    /// PE file format invalid or unsupported
53    InvalidPeFormat { reason: String },
54
55    /// memory allocation failed
56    AllocationFailed { size: usize, protection: u32 },
57
58    /// failed to map PE section
59    MappingFailed { section: String, reason: String },
60
61    /// failed to process relocation entry
62    RelocationFailed { rva: u32, reason: String },
63
64    /// failed to resolve import
65    ImportResolutionFailed { dll: String, function: String },
66
67    /// export is forwarded to another module
68    ForwardedExport { forwarder: String },
69
70    /// TLS callback execution failed
71    TlsCallbackFailed { index: usize },
72
73    /// DllMain returned FALSE
74    EntryPointFailed { status: i32 },
75
76    // === syscalls ===
77    /// failed to enumerate syscalls from ntdll
78    SyscallEnumerationFailed { reason: String },
79
80    /// syscall with given name/hash not found
81    SyscallNotFound { name: String },
82
83    /// syscall returned error status
84    SyscallFailed { name: String, status: i32 },
85
86    /// ntdll.dll not found in loaded modules
87    NtdllNotFound,
88
89    // === hooks ===
90    /// failed to detect hooks in function
91    HookDetectionFailed { function: String, reason: String },
92
93    /// failed to remove hook
94    UnhookFailed { function: String, reason: String },
95
96    /// function integrity check failed
97    IntegrityCheckFailed { function: String },
98
99    /// clean copy of module not available
100    CleanCopyUnavailable,
101
102    // === inline hooks ===
103    /// failed to install inline hook
104    HookInstallFailed { target: u64, reason: String },
105
106    /// failed to restore hook
107    HookRestoreFailed { target: u64, reason: String },
108
109    /// instruction decoding failed
110    InstructionDecodeFailed { address: u64, reason: String },
111
112    /// trampoline allocation failed
113    TrampolineAllocationFailed { near: u64, size: usize },
114
115    /// hook conflict detected (target already hooked)
116    HookConflict { target: u64, existing_type: String },
117
118    /// insufficient space for hook at target
119    InsufficientHookSpace { target: u64, available: usize, required: usize },
120
121    // === memory ===
122    /// memory read operation failed
123    ReadFailed { address: u64, size: usize },
124
125    /// memory write operation failed
126    WriteFailed { address: u64, size: usize },
127
128    /// failed to change memory protection
129    ProtectionChangeFailed { address: u64, size: usize },
130
131    // === pattern scanning ===
132    /// failed to parse pattern string
133    PatternParseFailed { reason: String },
134
135    // === win32 ===
136    /// underlying Win32 API returned error
137    Win32Error { code: u32, context: &'static str },
138}
139
140/// which PEB module list had an issue
141#[derive(Debug, Clone, Copy, PartialEq, Eq)]
142pub enum ModuleListType {
143    InLoadOrder,
144    InMemoryOrder,
145    InInitializationOrder,
146}
147
148impl fmt::Display for ModuleListType {
149    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
150        match self {
151            Self::InLoadOrder => write!(f, "InLoadOrderModuleList"),
152            Self::InMemoryOrder => write!(f, "InMemoryOrderModuleList"),
153            Self::InInitializationOrder => write!(f, "InInitializationOrderModuleList"),
154        }
155    }
156}
157
158impl std::error::Error for WraithError {}
159
160impl fmt::Display for WraithError {
161    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
162        match self {
163            Self::UnsupportedWindowsVersion { major, minor, build } => {
164                write!(f, "unsupported Windows version: {major}.{minor}.{build}")
165            }
166            Self::UnsupportedArchitecture => {
167                write!(f, "unsupported architecture (only x86/x64 supported)")
168            }
169            Self::InvalidPebAccess => {
170                write!(f, "failed to access PEB")
171            }
172            Self::InvalidTebAccess => {
173                write!(f, "failed to access TEB")
174            }
175            Self::CorruptedStructure { name, reason } => {
176                write!(f, "corrupted structure {name}: {reason}")
177            }
178            Self::NullPointer { context } => {
179                write!(f, "unexpected null pointer in {context}")
180            }
181            Self::ModuleNotFound { name } => {
182                write!(f, "module not found: {name}")
183            }
184            Self::AddressNotInModule { address } => {
185                write!(f, "address {address:#x} not in any loaded module")
186            }
187            Self::ThreadNotFound { tid } => {
188                write!(f, "thread {tid} not found")
189            }
190            Self::UnlinkFailed { module, reason } => {
191                write!(f, "failed to unlink {module}: {reason}")
192            }
193            Self::RelinkFailed { module, reason } => {
194                write!(f, "failed to relink {module}: {reason}")
195            }
196            Self::ListCorrupted { list_type } => {
197                write!(f, "PEB {list_type} appears corrupted")
198            }
199            Self::InvalidPeFormat { reason } => {
200                write!(f, "invalid PE format: {reason}")
201            }
202            Self::AllocationFailed { size, protection } => {
203                write!(
204                    f,
205                    "failed to allocate {size} bytes with protection {protection:#x}"
206                )
207            }
208            Self::MappingFailed { section, reason } => {
209                write!(f, "failed to map section {section}: {reason}")
210            }
211            Self::RelocationFailed { rva, reason } => {
212                write!(f, "relocation failed at RVA {rva:#x}: {reason}")
213            }
214            Self::ImportResolutionFailed { dll, function } => {
215                write!(f, "failed to resolve {dll}!{function}")
216            }
217            Self::ForwardedExport { forwarder } => {
218                write!(f, "export forwarded to {forwarder}")
219            }
220            Self::TlsCallbackFailed { index } => {
221                write!(f, "TLS callback {index} failed")
222            }
223            Self::EntryPointFailed { status } => {
224                write!(f, "entry point returned {status}")
225            }
226            Self::SyscallEnumerationFailed { reason } => {
227                write!(f, "syscall enumeration failed: {reason}")
228            }
229            Self::SyscallNotFound { name } => {
230                write!(f, "syscall not found: {name}")
231            }
232            Self::SyscallFailed { name, status } => {
233                write!(f, "syscall {name} failed with status {status:#x}")
234            }
235            Self::NtdllNotFound => {
236                write!(f, "ntdll.dll not found in loaded modules")
237            }
238            Self::HookDetectionFailed { function, reason } => {
239                write!(f, "hook detection failed for {function}: {reason}")
240            }
241            Self::UnhookFailed { function, reason } => {
242                write!(f, "unhook failed for {function}: {reason}")
243            }
244            Self::IntegrityCheckFailed { function } => {
245                write!(f, "integrity check failed for {function}")
246            }
247            Self::CleanCopyUnavailable => {
248                write!(f, "clean copy of module not available for comparison")
249            }
250            Self::HookInstallFailed { target, reason } => {
251                write!(f, "failed to install hook at {target:#x}: {reason}")
252            }
253            Self::HookRestoreFailed { target, reason } => {
254                write!(f, "failed to restore hook at {target:#x}: {reason}")
255            }
256            Self::InstructionDecodeFailed { address, reason } => {
257                write!(f, "instruction decode failed at {address:#x}: {reason}")
258            }
259            Self::TrampolineAllocationFailed { near, size } => {
260                write!(f, "failed to allocate {size} bytes trampoline near {near:#x}")
261            }
262            Self::HookConflict { target, existing_type } => {
263                write!(f, "hook conflict at {target:#x}: already hooked ({existing_type})")
264            }
265            Self::InsufficientHookSpace { target, available, required } => {
266                write!(
267                    f,
268                    "insufficient hook space at {target:#x}: need {required} bytes, have {available}"
269                )
270            }
271            Self::ReadFailed { address, size } => {
272                write!(f, "failed to read {size} bytes at {address:#x}")
273            }
274            Self::WriteFailed { address, size } => {
275                write!(f, "failed to write {size} bytes at {address:#x}")
276            }
277            Self::ProtectionChangeFailed { address, size } => {
278                write!(
279                    f,
280                    "failed to change protection for {size} bytes at {address:#x}"
281                )
282            }
283            Self::PatternParseFailed { reason } => {
284                write!(f, "failed to parse pattern: {reason}")
285            }
286            Self::Win32Error { code, context } => {
287                write!(f, "Win32 error {code:#x} in {context}")
288            }
289        }
290    }
291}
292
293/// result type alias using WraithError
294pub type Result<T> = std::result::Result<T, WraithError>;
295
296impl WraithError {
297    /// create Win32Error from GetLastError
298    pub fn from_last_error(context: &'static str) -> Self {
299        // SAFETY: GetLastError is always safe to call
300        let code = unsafe { GetLastError() };
301        Self::Win32Error { code, context }
302    }
303}
304
305#[link(name = "kernel32")]
306extern "system" {
307    fn GetLastError() -> u32;
308}
wraith/error.rs

wraith/
error.rs
