The WinGecko server provides plenty of features you can use from a respective WinGecko client. In the following, the server commands will be listed including the parameters as well as returned data.
TODOs:
Please note that the server commands may not be identical to the commands provided in a client implementation. Client implementations may offer more wrapper functions for convenience such as reading and writing more specific data type primitives such as int, short, double, float, char or bool.
If you have any feedback regarding the set of functionalities of WinGecko, such as different types or commands or parameters for commands, feel free to get in touch and we can discuss the details. Your feedback is valuable in making WinGecko the best it can be.
- Attach: This command will allow you to supply information regarding to which game/process you want to attach to. You may pass the process id, the process name, the class name, the window title, the start process URL (or file path to the executable) and whether the server will wait for a successful connection or return immediately. When the target process is crashed or restarted, another attach command is not necessary to be invoked. WinGecko will always re-attach automatically.
- Detach: This command detaches from a process and informs the client once the detach succeeded. If no attach happened yet, no error is generated.
- Inject DLL: This command will inject a DLL into the attached process. Required parameters are the file path to the DLL to inject and the injection method to use ("Create Windows thread" or "Set Windows Hook"). On failure, an error is returned.
- Is DLL injected: This command will check whether the DLL specified by the passed module file path is currently loaded/injected or not. On failure, an error is returned.
- Unload DLL: This command unloads a DLL from the process. You need to specify a function to be called for performing cleanup and the module file path to the DLL to unload. On failure, an error is returned.
- Get Process ID: This command will return the process ID of a process by process name. On failure, an error is returned.
- Kill Process: This command kills/terminates a process by process name. Since multiple processes with the same process name could run on this system, all of them are terminated and the amount of terminated processes is returned on success, on failure an error is returned.
- Execute Lua Script: This command will execute a Lua script specified by the parameter which is the Lua script itself. The documentation for Lua and the available custom functions may be provided at a later time. On command failure, an error is returned.
- Read Memory: This command can read memory from an address. You also have to specify the length of memory to read. On success, the read memory is returned, on failure an error is returned. Reading from unmapped memory will make the command fail even if valid memory was partially available.
- Read String: This convenience command will read a string from the memory starting at the given address. You must also specify whether the string is unicode and the maximum length of a string. The maximum length may be Integer.MAX without causing issues since reading the string will stop at this first dectected null-byte (0x00).
- Dump Memory: This command dumps all memory ranges from the process into the specified target directory on the system. Please be a patient until the command completed since it may take a couple seconds. On command failure, an error is returned.
- Write Memory: This command writes to the specified address with the data specified. If any write in the specified memory range fails, the entire command will return an error similar to the Read Memory command.
- Write String: This command is a convenience function for writing a string into the memory at a specific address. You need to specify the text and also whether it should be written as unicode or not. The difference is that unicode has a 00 byte after every regular character while non-unicode does not have them.
- Follow Pointer: This command follows a memory pointer by taking a memory pointer object which may specify the module name of where the pointer is located at, the offset within the module, alternatively the base address, the custom name of the memory pointer and the array/list of pointer offsets. Pointers can be found with the pointer searcher in e.g. Cheat Engine.
- Patch Bytes: This command will patch enabled or default bytes into the memory at the given address. The benefit of using this function is that you will get an error if the current value in the memory is not either the enabled or default value. This is useful for detecting whether you are really writing to the right address. On validation error or if any other failure occurred, an error is returned.
- Find Exported Function: This command will return the address of an exported function. For this you need to specify the module name and the function name. Upon failure, an error is returned.
- Remote Procedure Call: This function performs an RPC on the given function address and the parameters. Note that not all parameter datatypes may be supported (such as floating point data types) and the data types must be compatible with the native code at hand (e.g. some experience in C/C++ programming or native code calling conventions may be helpful). Parameters consist of the data type and the long (= 64-bit integer) value. Note that all function parameters in C/C++ can be specified as long values. When the process crashed, the process exit value is returned. Otherwise, success is returned to the client.
- Get Module Information: This command will return information about the provided module name such as the start and end address in memory where the module is located at.
- Search Memory: This command searches the memory based on a search pattern. Currently, search patterns with placeholders (??) are not yet supported. You can specify the module to search or the search range (= start address and end address). Also, you can specify the maximum match count. This command returns all matched addresses. Upon failure, an error is returned without any results.
- Suspend Process: This command suspends the target process. If the process is already suspended, no error is generated. Upon failure, an error is returned.
- Resume Process: This command resumes the target process. If the process is already running, no error is generated. Upon failure, an error is returned.
- Terminate Process: This command terminates the target process. Upon failure, an error is returned.
- Start Process: This command will start the target process based on the start process URL supplied with the attach command. Upon failure, an error is returned.
- Restart Process: This command will restart the target process based on the start process URL supplied with the attach command. Upon failure, an error is returned.
- Allocate Module Memory: This command allocates memory within a module. You need to specify the module's base address and the length of memory to allocate. Upon success, the allocated address is returned. Upon failure, an error is returned. The allocated memory does not have to be de-allocated since it is allocated manually through null-byte (0x00) pattern finding and not through a dedicated operating system allocation function. Hence, there is no dedicated de-allocation command for it.
- Allocate Process Memory: This command allocates memory with the target process. You need to specify the length of the memory to allocate. Upon success, the allocated address is returned. Upon failure, an error is returned. Alternatively, you can pre-initialize the memory with null-bytes (0x00). After you're finished working with the allocated memory, you must free the memory using the free process memory command. Failure to do so will result in a memory leak.
- Allocate String: Allocates process memory for the given text. You furthermore need to specify the string type (C-string or C# string) and whether the string should be unicode or not. On success, the allocated address and the length of allocated memory is returned. The text will already be written into the allocated memory area.
- Free Process Memory: This command frees memory allocated by the allocate process memory command. You need to specify the allocated address. Upon success or failure, no error is returned.
- Insert Hook: This command can inject executable code in the form of x86 assembly into the memory at the provided hook address. An alternative name for this feature is code cave. You need to specify the injected bytes, the default instruction bytes and whether to drop the default instruction(s). The insertion address of the injected bytes will be allocated automatically by finding closeby "empty" memory (only comtaining null-bytes). This command is fairly difficult to use correctly and may fail or crash target process in certain circumstances. You e.g. cannot insert a hook at a jump instruction. Upon failure, an error is returned.
- Delete Hook: This command will deleted an inserted hook again. You need to specify the hook address and the default bytes to overwrite the hook address with. Potentially allocated memory will be nulled out (0x00) again. Upon failure, an error is returned.
- Is Hooked: This command checks whether the provided address is hooked. Any jump instruction will also return success. Upon failure, an error is returned.
- Server Details: This command returns the server details including the name (e.g. WinGecko Server), the version, the author, the person it is licensed to, the supported bit version and the application it is licensed for
- Stop Server: This command stops the server and shuts down WinGecko
TODOs:
- Support floating pointer datatypes for RPC
- Support pattern memory searching with placeholders
- Add more Lua custom functions/document them
Please note that the server commands may not be identical to the commands provided in a client implementation. Client implementations may offer more wrapper functions for convenience such as reading and writing more specific data type primitives such as int, short, double, float, char or bool.
If you have any feedback regarding the set of functionalities of WinGecko, such as different types or commands or parameters for commands, feel free to get in touch and we can discuss the details. Your feedback is valuable in making WinGecko the best it can be.
