1+++
  2title = "Writing our own Cheat Engine: Introduction"
  3date = 2021-02-07
  4updated = 2021-02-19
  5[taxonomies]
  6category = ["sw"]
  7tags = ["windows", "rust", "hacking"]
  8+++
  9
 10This is part 1 on the *Writing our own Cheat Engine* series:
 11
 12* Part 1: Introduction
 13* [Part 2: Exact Value scanning](/blog/woce-2)
 14* [Part 3: Unknown initial value](/blog/woce-3)
 15* [Part 4: Floating points](/blog/woce-4)
 16* [Part 5: Code finder](/blog/woce-5)
 17
 18[Cheat Engine][ce] is a tool designed to modify single player games and contains other useful tools within itself that enable its users to debug games or other applications. It comes with a memory scanner, (dis)assembler, inspection tools and a handful other things. In this series, we will be writing our own tiny Cheat Engine capable of solving all steps of the tutorial, and diving into how it all works underneath.
 19
 20Needless to say, we're doing this for private and educational purposes only. One has to make sure to not violate the EULA or ToS of the specific application we're attaching to. This series, much like cheatengine.org, does not condone the illegal use of the code shared.
 21
 22Cheat Engine is a tool for Windows, so we will be developing for Windows as well. However, you can also [read memory from Linux-like systems][linux-readmem]. [GameConqueror][game-conqueror] is a popular alternative to Cheat Engine on Linux systems, so if you feel adventurous, you could definitely follow along too! The techniques shown in this series apply regardless of how we read memory from a process. You will learn a fair bit about doing FFI in Rust too.
 23
 24We will be developing the application in Rust, because it enables us to interface with the Windows API easily, is memory safe (as long as we're careful with `unsafe`!), and is speedy (we will need this for later steps in the Cheat Engine tutorial). You could use any language of your choice though. For example, [Python also makes it relatively easy to use the Windows API][python-ctypes]. You don't need to be a Rust expert to follow along, but this series assumes some familiarity with C-family languages. Slightly advanced concepts like the use of `unsafe` or the `MaybeUninit` type will be briefly explained. What a `fn` is or what `let` does will not be explained.
 25
 26[Cheat Engine's source code][ce-code] is mostly written in Pascal and C. And it's *a lot* of code, with a very flat project structure, and files ranging in the thousand lines of code each. It's daunting[^1]. It's a mature project, with a lot of knowledge encoded in the code base, and a lot of features like distributed scanning or an entire disassembler. Unfortunately, there's not a lot of comments. For these reasons, I'll do some guesswork when possible as to how it's working underneath, rather than actually digging into what Cheat Engine is actually doing.
 27
 28With that out of the way, let's get started!
 29
 30## Welcome to the Cheat Engine Tutorial
 31
 32<details open><summary>Cheat Engine Tutorial: Step 1</summary>
 33
 34> This tutorial will teach you the basics of cheating in video games. It will also show you foundational aspects of using Cheat Engine (or CE for short). Follow the steps below to get started.
 35>
 36> 1. Open Cheat Engine if it currently isn't running.
 37> 2. Click on the "Open Process" icon (it's the top-left icon with the computer on it, below "File".).
 38> 3. With the Process List window now open, look for this tutorial's process in the list. It will look something like > "00001F98-Tutorial-x86_64.exe" or "0000047C-Tutorial-i386.exe". (The first 8 numbers/letters will probably be different.)
 39> 4. Once you've found the process, click on it to select it, then click the "Open" button. (Don't worry about all the > other buttons right now. You can learn about them later if you're interested.)
 40>
 41> Congratulations! If you did everything correctly, the process window should be gone with Cheat Engine now attached to the > tutorial (you will see the process name towards the top-center of CE).
 42>
 43> Click the "Next" button below to continue, or fill in the password and click the "OK" button to proceed to that step.)
 44>
 45> If you're having problems, simply head over to forum.cheatengine.org, then click on "Tutorials" to view beginner-friendly > guides!
 46
 47</details>
 48
 49## Enumerating processes
 50
 51Our first step is attaching to the process we want to work with. But we need a way to find that process in the first place! Having to open the task manager, look for the process we care about, noting down the process ID (PID), and slapping it in the source code is not satisfying at all. Instead, let's enumerate all the processes from within the program, and let the user select one by typing its name.
 52
 53From a quick [DuckDuckGo search][ddg-enumproc], we find an official tutorial for [Enumerating All Processes][tut-enumproc], which leads to the [`EnumProcesses`][api-enumproc] call. Cool! Let's slap in the [`winapi`][winapi-crate] crate on `Cargo.toml`, because I don't want to write all the definitions by myself:
 54
 55```toml
 56[dependencies]
 57winapi = { version = "0.3.9", features = ["psapi"] }
 58```
 59
 60Because [`EnumProcesses`][api-enumproc] is in `Psapi.h` (you can see this in the online page of its documentation), we know we'll need the `psapi` crate feature. Another option is to search for it in the [`winapi` documentation][winapi-doc] and noting down the parent module where its stored.
 61
 62The documentation for the method has the following remark:
 63
 64> It is a good idea to use a large array, because it is hard to predict how many processes there will be at the time you call **EnumProcesses**.
 65
 66*Sidenote: reading the documentation for the methods we'll use from the Windows API is extremely important. There's a lot of gotchas involved, so we need to make sure we're extra careful.*
 67
 681024 is a pretty big number, so let's go with that:
 69
 70```rust
 71use std::io;
 72use std::mem;
 73use winapi::shared::minwindef::{DWORD, FALSE};
 74
 75pub fn enum_proc() -> io::Result<Vec<u32>> {
 76    let mut pids = Vec::<DWORD>::with_capacity(1024);
 77    let mut size = 0;
 78    // SAFETY: the pointer is valid and the size matches the capacity.
 79    if unsafe {
 80        winapi::um::psapi::EnumProcesses(
 81            pids.as_mut_ptr(),
 82            (pids.capacity() * mem::size_of::<DWORD>()) as u32,
 83            &mut size,
 84        )
 85    } == FALSE
 86    {
 87        return Err(io::Error::last_os_error());
 88    }
 89
 90    todo!()
 91}
 92```
 93
 94We allocate enough space[^2] for 1024 `pids` in a vector[^3], and pass a mutable pointer to the contents to `EnumProcesses`. Note that the size of the array is in *bytes*, not items, so we need to multiply the capacity by the size of `DWORD`. The API likes to use `u32` for sizes, unlike Rust which uses `usize`, so we need a cast.
 95
 96Last, we need another mutable variable where the amount of bytes written is stored, `size`.
 97
 98> If the function fails, the return value is zero. To get extended error information, call [`GetLastError`][getlasterr].
 99
100That's precisely what we do. If it returns false (zero), we return the last OS error. Rust provides us with [`std::io::Error::last_os_error`][lasterr], which essentially makes that same call but returns a proper `io::Error` instance. Cool!
101
102> To determine how many processes were enumerated, divide the *lpcbNeeded* value by `sizeof(DWORD)`.
103
104Easy enough:
105
106```rust
107let count = size as usize / mem::size_of::<DWORD>();
108// SAFETY: the call succeeded and count equals the right amount of items.
109unsafe { pids.set_len(count) };
110Ok(pids)
111```
112
113Rust doesn't know that the memory for `count` items were initialized by the call, but we do, so we make use of the [`Vec::set_len`][vecsetlen] call to indicate this. The Rust documentation even includes a FFI similar to our code!
114
115Let's give it a ride:
116
117```rust
118fn main() {
119    dbg!(enum_proc().unwrap().len());
120}
121```
122
123```
124>cargo run
125   Compiling memo v0.1.0
126    Finished dev [unoptimized + debuginfo] target(s) in 0.20s
127     Running `target\debug\memo.exe`
128[src\main.rs:27] enum_proc().unwrap().len() = 178
129```
130
131It works! But currently we only have a bunch of process identifiers, with no way of knowing which process they refer to.
132
133> To obtain process handles for the processes whose identifiers you have just obtained, call the [`OpenProcess`][openproc] function.
134
135Oh!
136
137## Opening a process
138
139The documentation for `OpenProcess` also contains the following:
140
141> When you are finished with the handle, be sure to close it using the [`CloseHandle`](closehandle) function.
142
143This sounds to me like the perfect time to introduce a custom `struct Process` with an `impl Drop`! We're using `Drop` to cleanup resources, not behaviour, so it's fine. [Using `Drop` to cleanup behaviour is a bad idea][drop-behaviour]. But anyway, let's get back to the code:
144
145```rust
146use std::ptr::NonNull;
147use winapi::ctypes::c_void;
148
149pub struct Process {
150    pid: u32,
151    handle: NonNull<c_void>,
152}
153
154impl Process {
155    pub fn open(pid: u32) -> io::Result<Self> {
156        todo!()
157    }
158}
159
160impl Drop for Process {
161    fn drop(&mut self) {
162        todo!()
163    }
164}
165```
166
167For `open`, we'll want to use `OpenProcess` (and we also need to add the `processthreadsapi` feature to the `winapi` dependency in `Cargo.toml`). It returns a `HANDLE`, which is a nullable mutable pointer to `c_void`. If it's null, the call failed, and if it's non-null, it succeeded and we have a valid handle. This is why we use Rust's [`NonNull`][nonnull]:
168
169```rust
170// SAFETY: the call doesn't have dangerous side-effects.
171NonNull::new(unsafe { winapi::um::processthreadsapi::OpenProcess(0, FALSE, pid) })
172    .map(|handle| Self { pid, handle })
173    .ok_or_else(io::Error::last_os_error)
174```
175
176`NonNull` will return `Some` if the pointer is non-null. We map the non-null pointer to a `Process` instance with `Self { .. }`. `ok_or_else` converts the `Option` to a `Result` with the error builder function we provide if it was `None`.
177
178The first parameter is a bitflag of permissions we want to have. For now, we can leave it as zero (all bits unset, no specific permissions granted). The second one is whether we want to inherit the handle, which we don't, and the third one is the process identifier. Let's close the resource handle on `Drop` (after adding `handleapi` to the crate features):
179
180```rust
181// SAFETY: the handle is valid and non-null.
182unsafe { winapi::um::handleapi::CloseHandle(self.handle.as_mut()) };
183```
184
185`CloseHandle` can actually fail (for example, on double-close), but given our invariants, it won't. You could add an `assert!` to panic if this is not the case.
186
187We can now open processes, and they will be automatically closed on `Drop`. Does any of this work though?
188
189```rust
190fn main() {
191    let mut success = 0;
192    let mut failed = 0;
193    enum_proc().unwrap().into_iter().for_each(|pid| match Process::open(pid) {
194        Ok(_) => success += 1,
195        Err(_) => failed += 1,
196    });
197
198    eprintln!("Successfully opened {}/{} processes", success, success + failed);
199}
200```
201
202```
203>cargo run
204   Compiling memo v0.1.0
205    Finished dev [unoptimized + debuginfo] target(s) in 0.36s
206     Running `target\debug\memo.exe`
207Successfully opened 0/191 processes
208```
209
210…nope. Maybe the documentation for `OpenProcess` says something?
211
212> `dwDesiredAccess`
213>
214> The access to the process object. This access right is checked against the security descriptor for the process. This parameter can be **one or more** of the process access rights.
215
216One or more, but we're setting zero permissions. I told you, reading the documentation is important[^4]! The [Process Security and Access Rights][proc-rights] page lists all possible values we could use. `PROCESS_QUERY_INFORMATION` seems to be appropriated:
217
218> Required to retrieve certain information about a process, such as its token, exit code, and priority class
219
220```rust
221OpenProcess(winapi::um::winnt::PROCESS_QUERY_INFORMATION, ...)
222```
223
224Does this fix it?
225
226```rust
227>cargo run
228   Compiling memo v0.1.0
229    Finished dev [unoptimized + debuginfo] target(s) in 0.36s
230     Running `target\debug\memo.exe`
231Successfully opened 69/188 processes
232```
233
234*Nice*. It does solve it. But why did we only open 69 processes out of 188? Does it help if we run our code as administrator? Let's search for `cmd` in the Windows menu and right click to Run as administrator, then `cd` into our project and try again:
235
236```
237>cargo run
238    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
239     Running `target\debug\memo.exe`
240Successfully opened 77/190 processes
241```
242
243We're able to open a few more, so it does help. In general, we'll want to run as administrator, so normal programs can't sniff on what we're doing, and so that we have permission to do more things.
244
245## Getting the name of a process
246
247We're not done enumerating things just yet. To get the "name" of a process, we need to enumerate the modules that it has loaded, and only then can we get the module base name. The first module is the program itself, so we don't need to enumerate *all* modules, just the one is enough.
248
249For this we want [`EnumProcessModules`][mod-enumproc] and [`GetModuleBaseNameA`][mod-name]. I'm using the ASCII variant of `GetModuleBaseName` because I'm too lazy to deal with UTF-16 of the `W` (wide, unicode) variants.
250
251```rust
252use std::mem::MaybeUninit;
253use winapi::shared::minwindef::HMODULE;
254
255pub fn name(&self) -> io::Result<String> {
256    let mut module = MaybeUninit::<HMODULE>::uninit();
257    let mut size = 0;
258    // SAFETY: the pointer is valid and the size is correct.
259    if unsafe {
260        winapi::um::psapi::EnumProcessModules(
261            self.handle.as_ptr(),
262            module.as_mut_ptr(),
263            mem::size_of::<HMODULE>() as u32,
264            &mut size,
265        )
266    } == FALSE
267    {
268        return Err(io::Error::last_os_error());
269    }
270
271    // SAFETY: the call succeeded, so module is initialized.
272    let module = unsafe { module.assume_init() };
273    todo!()
274}
275```
276
277`EnumProcessModules` takes a pointer to an array of `HMODULE`. We could use a `Vec` of capacity one to hold the single module, but in memory, a pointer a single item can be seen as a pointer to an array of items. `MaybeUninit` helps us reserve enough memory for the one item we need.
278
279With the module handle, we can retrieve its base name:
280
281```rust
282let mut buffer = Vec::<u8>::with_capacity(64);
283// SAFETY: the handle, module and buffer are all valid.
284let length = unsafe {
285    winapi::um::psapi::GetModuleBaseNameA(
286        self.handle.as_ptr(),
287        module,
288        buffer.as_mut_ptr().cast(),
289        buffer.capacity() as u32,
290    )
291};
292if length == 0 {
293    return Err(io::Error::last_os_error());
294}
295
296// SAFETY: the call succeeded and length represents bytes.
297unsafe { buffer.set_len(length as usize) };
298Ok(String::from_utf8(buffer).unwrap())
299```
300
301Similar to how we did with `EnumProcesses`, we create a buffer that will hold the ASCII string of the module's base name[^5]. The call wants us to pass a pointer to a mutable buffer of `i8`, but Rust's `String::from_utf8` wants a `Vec<u8>`, so instead we declare a buffer of `u8` and `.cast()` the pointer in the call. You could also do this with `as _`, and Rust would infer the right type, but `cast` is neat.
302
303We `unwrap` the creation of the UTF-8 string because the buffer should contain only ASCII characters (which are also valid UTF-8). We could use the `unsafe` variant to create the string, but what if somehow it contains non-ASCII characters? The less `unsafe`, the better.
304
305Let's see it in action:
306
307```rust
308fn main() {
309    enum_proc()
310        .unwrap()
311        .into_iter()
312        .for_each(|pid| match Process::open(pid) {
313            Ok(proc) => match proc.name() {
314                Ok(name) => println!("{}: {}", pid, name),
315                Err(e) => println!("{}: (failed to get name: {})", pid, e),
316            },
317            Err(e) => eprintln!("failed to open {}: {}", pid, e),
318        });
319}
320```
321
322```
323>cargo run
324   Compiling memo v0.1.0
325    Finished dev [unoptimized + debuginfo] target(s) in 0.32s
326     Running `target\debug\memo.exe`
327failed to open 0: The parameter is incorrect. (os error 87)
328failed to open 4: Access is denied. (os error 5)
329...
330failed to open 5940: Access is denied. (os error 5)
3315608: (failed to get name: Access is denied. (os error 5))
332...
3331704: (failed to get name: Access is denied. (os error 5))
334failed to open 868: Access is denied. (os error 5)
335...
336```
337
338That's not good. What's up with that? Maybe…
339
340> The handle must have the `PROCESS_QUERY_INFORMATION` and `PROCESS_VM_READ` access rights.
341
342…I should've read the documentation. Okay, fine:
343
344```rust
345use winapi::um::winnt;
346OpenProcess(winnt::PROCESS_QUERY_INFORMATION | winnt::PROCESS_VM_READ, ...)
347```
348
349```
350>cargo run
351   Compiling memo v0.1.0 (C:\Users\L\Desktop\memo)
352    Finished dev [unoptimized + debuginfo] target(s) in 0.35s
353     Running `target\debug\memo.exe`
354failed to open 0: The parameter is incorrect. (os error 87)
355failed to open 4: Access is denied. (os error 5)
356...
3579348: cheatengine-x86_64.exe
3583288: Tutorial-x86_64.exe
3598396: cmd.exe
3604620: firefox.exe
3617964: cargo.exe
36210052: cargo.exe
3635756: memo.exe
364```
365
366Hooray 🎉! There's some processes we can't open, but that's because they're system processes. Security works!
367
368## Finale
369
370That was a fairly long post when all we did was print a bunch of pids and their corresponding name. But in all fairness, we also laid out a good foundation for what's coming next.
371
372You can [obtain the code for this post][code] over at my GitHub. At the end of every post, the last commit will be tagged, so you can `git checkout step1` to see the final code for any blog post.
373
374In the [next post](/blog/woce-2), we'll tackle the second step of the tutorial: Exact Value scanning.
375
376### Footnotes
377
378[^1]: You could say I simply love reinventing the wheel, which I do, but in this case, the codebase contains *far* more features than we're interested in. The (apparent) lack of structure and documentation regarding the code, along with the unfortunate [lack of license][lack-license] for the source code, make it a no-go. There's a license, but I think that's for the distributed program itself.
379
380[^2]: If it turns out that there are more than 1024 processes, our code will be unaware of those extra processes. The documentation suggests to perform the call again with a larger buffer if `count == provided capacity`, but given I have under 200 processes on my system, it seems unlikely we'll reach this limit. If you're worried about hitting this limit, simply use a larger limit or retry with a larger vector.
381
382[^3]: C code would likely use [`GlobalAlloc`][global-alloc] here, but Rust's `Vec` handles the allocation for us, making the code both simpler and more idiomatic. In general, if you see calls to `GlobalAlloc` when porting some code to Rust, you can probably replace it with a `Vec`.
383
384[^4]: This will be a recurring theme.
385
386[^5]: …and similar to `EnumProcesses`, if the name doesn't fit in our buffer, the result will be truncated.
387
388[ce]: https://cheatengine.org/
389[python-ctypes]: https://lonami.dev/blog/ctypes-and-windows/
390[ce-code]: https://github.com/cheat-engine/cheat-engine/
391[linux-readmem]: https://stackoverflow.com/q/12977179/4759433
392[game-conqueror]: https://github.com/scanmem/scanmem
393[ddg-enumproc]: https://ddg.gg/winapi%20enumerate%20all%20processes
394[tut-enumproc]: https://docs.microsoft.com/en-us/windows/win32/psapi/enumerating-all-processes
395[api-enumproc]: https://docs.microsoft.com/en-us/windows/win32/api/psapi/nf-psapi-enumprocesses
396[winapi-crate]: https://crates.io/crates/winapi
397[winapi-doc]: https://docs.rs/winapi/
398[getlasterr]: https://docs.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror
399[lasterr]: https://doc.rust-lang.org/stable/std/io/struct.Error.html#method.last_os_error
400[vecsetlen]: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#method.set_len
401[openproc]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-openprocess
402[closehandle]: https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle
403[drop-behaviour]: https://internals.rust-lang.org/t/pre-rfc-leave-auto-trait-for-reliable-destruction/13825
404[nonnull]: https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html
405[proc-rights]: https://docs.microsoft.com/en-us/windows/win32/procthread/process-security-and-access-rights
406[mod-enumproc]: https://docs.microsoft.com/en-us/windows/win32/api/psapi/nf-psapi-enumprocessmodules
407[mod-name]: https://docs.microsoft.com/en-us/windows/win32/api/psapi/nf-psapi-getmodulebasenamea
408[code]: https://github.com/lonami/memo
409[lack-license]: https://github.com/cheat-engine/cheat-engine/issues/60
410[global-alloc]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-globalalloc