Awesome

WslReverse

Experiments with hidden COM interface and LxBus IPC mechanism in WSL. Heavily inspired by kernel guru Alex Ionescu's project lxss. This project is just a concept, not a fully developed program and should be used for testing purposes.

How to build

Clone this repository. Open the solution (.sln) or project (.vcxproj) file in Visual Studio and build it. Alternatively, run Visual Studio developer command prompt, go to the cloned folder and run msbuild command. This project can also be built with mingw-w64 toolchain. Open terminal in the cloned folder and run make command. The binaries will be in /bin folder.

How to use

Download the binary from Release page, no installation steps are required. This project only shows the hidden COM methods which may change in future Windows version. The COM vtable, used in this project, is according to latest Windows 10 20H1 Insider Preview, that is build 18917 and above. Here are the options of WslReverse:

Usage: WslReverse.exe [-] [option] [argument]

Options:
  -b, --bus          [Distro]      Create own LxBus server (as administrator).
  -d, --get-id       [Distro]      Get distribution ID.
  -e, --export       [Distro]  [File Name]
                                   Exports selected distribution to a tar file.
  -G, --get-default                Get default distribution ID.
  -g, --get-config   [Distro]      Get distribution configuration.
  -h, --help                       Show this help information.
  -i, --install      [Distro]  [Install Folder]  [File Name]
                                   Install tar file as a new distribution.
  -l, --list                       List all distributions with pending ones.
  -r, --run          [Distro]      Run bash in provided distribution.
  -S, --set-default  [Distro]      Set default distribution.
  -s, --set-config   [Distro]      Set configuration for distribution.
  -t, --terminate    [Distro]      Terminate running distribution.
  -u, --uninstall    [Distro]      Uninstall distribution.

Project layout

Most of the definitions are in LxBus.h and WinInternal.h header files. The project layout of source files:

• common:

  • CreateLxProcess: Run WSL1 pico processes
  • CreateProcessAsync: Create worker thread for LxBus IPC mechanism
  • CreateWinProcess: Create Windows process with LxBus server
  • GetConhostServerId: Shows associated ConHost PID by IOCTL from condrv.sys
  • Helpers: Helping functions to log return values and more
  • LxBus: Required IOCTLs and associated structures
  • LxBusServer: Send/Receive various types of messages with LxBus Server
  • LxssUserSession: LxssUserSession COM interface
  • SpawnWslHost: Compose backend process command line and create process
  • VmModeWorker: Run WSL2 processes
  • wgetopt: Converted from Cygwin getopt file for wide characters
  • WinInternal: Crafted RTL_USER_PROCESS_PARAMETERS and PEB structures

• frontend:

  • WslReverse: Main function with option processing

• backend:

  • WslReverseHost: Main function for backend processing

• linux_files:

  • LxBusClient: Client process which connect to LxBus server in forntend

• wslcli:

  • WslClient: WslClient COM interface for wsl.exe, bash.exe, wslconfig.exe and wslhost.exe.

Take a long ride with :minibus:

To use LxBus, import the LxCoreFlags registry file. Then reboot PC. Compile the LxBusClient.c with make in WSL. Execute WslRevese with -b or --bus option as administrator and LxBusClient as root user in WSL. Those two binaries exchange some messages between WSL and Windows side using LxBus via. LxCore driver. Here are some of them:

For detailed explanation, see Alex Ionescu's presentation @34min at BlackHat USA 2016. There are many things that can be done with LxBus IPC mechanism. What interesting thing do you want to do with LxBus? :yum:

Trace Syscalls

This works with WSL1 only because LxCore does not involve directly with WSL2. First import LxCoreFlags registry file. Then enable local kernel mode debugging with these two command as administrator and reboot PC.

bcdedit /debug on
bcdedit /dbgsettings local

This enables some DWORD registry flags. Behind the scene, LxCore mainly checks if PrintSysLevel and PrintLogLevel are both zero and TraceLastSyscall is present. For the same host machine, use DebugView as administrator or use KD for VM.

<img src=Others/LxCoreSyscalls.PNG>

Run any WSL1 distribution and see the logs and every syscalls and dmesg. The functions behind these logs format are like this:

DbgPrintEx(0, 0, "LX: (%p, %p) %s", PEPROCESS, PKTHREAD, Syscall);
DbgPrintEx(0, 0, "LX: (%p, %p) /dev/kmsg: %Z", PEPROCESS, PKTHREAD, Version);
DbgPrintEx(0, 0, "LX: (%p, %p) /dev/log: %d: %Z: %Z\n", PEPROCESS, PKTHREAD, x, y, z);
DbgPrintEx(0, 0, "LX: (%p, %p) (%Z) %s\n", PEPROCESS, PKTHREAD, Command, LxCoreFunction);

Trace Events

• List of Event Providers and associated GUID:

Acknowledgments

This project uses some definitions and data types from followings. Thanks to:

• Alex Ionescu for lxss project and all the IOCTLs details (MIT License).
• Steven G, Wen Jia Liu and others for ProcessHacker's collection of native API (GPLv3 License).
• Petr Beneš for pdbex tool.

License

WslReverse is licensed under the GNU General Public License v3. A full copy of the license is provided in LICENSE.

WslReverse -- Experiments with COM interface and LxBus IPC mechanism in WSL.
Copyright (c) 2018-19 Biswapriyo Nath

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.