Keval
Keval allows you to call arbitrary Windows kernel-mode functions from user mode, even (and primarily) on another machine.
The user mode portion is written in Python, which allows you to quickly declare, call, and inspect the results of a kernel function without compiling anything again.
Example
import ctypes
from pykeval.frontend import Client
from pykeval.broker import RemoteBroker
class UNICODE_STRING(ctypes.Structure):
_fields_ = [
("Length", ctypes.c_ushort),
("MaximumLength", ctypes.c_ushort),
("Buffer", ctypes.c_wchar_p)
]
client = Client(RemoteBroker("192.168.233.156"))
temp = UNICODE_STRING()
# We declare the signature of `RtlInitUnicodeString` like we'd do in a C header. Note that we don't actually
# need to declare `struct UNICODE_STRING` because we're passing a pointer.
client.declare("ntoskrnl",
"void RtlInitUnicodeString(UNICODE_STRING* DestinationString, wchar_t* SourceString);")
return_value, args, allocations = client.ex_call("ntoskrnl",
"RtlInitUnicodeString",
ctypes.pointer(temp), # This is an out param
"Hello\0".encode("UTF-16LE"),
read_back_args=True)
# We don't need the allocations that were made during this call since we read back the arguments.
for allocation in allocations:
allocation.free()
# BrokerAllocation objects are also garbage-collected by Python, but it's best not to rely on that.
out_param = args[0]
# The type of `out_param` has the same fields as `UNICODE_STRING` but `Buffer` was converted to a type
# compatible with the broker's machine (in case of a 64-bit machine, `c_uint64`).
# Since read_back_args=True, the returned argument is the *value* of the pointer after the call.
assert "Hello" == client.read_wstring(out_param.Buffer)
How it works
kevald.sys is a driver that accepts requests to run kernel functions over IOCTL. Each request contains the signature of the function, and so the driver calls it appropriately.
pykeval is a python package that, in the end, passes the correct requests to the driver. It contains:
Client: The main interface through which the library is used.- Brokers: Responsible to pass the request to the driver
LocalBroker: Passes the request to the driver via IOCTL.RemoteBroker: Passes the request to aRemoteBrokerServer(over TCP) which delegates the request to another broker. This is used when running code on another machine.
It's possible to run code both on the local machine or a remote machine by replacing the type of broker the client uses. When using a remote broker, the setup looks like this:
Getting started
See Getting started
TODO:
-
Predefine common Windows types in the client (
BYTE,DWORD,PVOID) so declarations can be a simpler copy-paste. -
Allow uploading and installing the driver directly from the client.
-
Add Github CI/CD to compile
kevald.sysand publishpyekvalto PyPI. -
More logs, an option for verbose logging.
-
32-bit support. Currently,
libffidoes not compile for 32-bit, so the driver isn't available. However, the client is able to run on a 32-bit machine. -
Parse PDB files for automatic inference of function signatures.
-
Support calling an address or a PDB symbol (generally functions which are not exported).
-
Support high IRQL functions.
Won't do:
- Support structs as parameters/return values. There seems to be no use case, as most if not all kernel functions use pointers when passing structures.
Acknowledgements
This project wouldn't be possible without:
- The LLVM Project, specifically libclang
- libffi, specifically @am11's fork which makes it much easier to build under Windows.
- stlkrn and vcrtl
79 Nov 15, 2022
11 May 22, 2022
1 Nov 17, 2021
5 Dec 22, 2022
39 Dec 23, 2022
24 Nov 18, 2022
15 Aug 27, 2022
0 Mar 24, 2022
32 Jan 5, 2023
4 Sep 23, 2021
2 Jan 07, 2022
259 Dec 13, 2022
3.5k Jan 06, 2023
769 Jan 03, 2023
5 Jan 08, 2022
22 Dec 20, 2022
7 May 29, 2022
33 Nov 24, 2022
2 Oct 19, 2021
4 Dec 01, 2022
6 Dec 01, 2021
5 Nov 08, 2021
1 Oct 30, 2021
2 Oct 29, 2021
112 Dec 19, 2022
191 Dec 30, 2022
5 Dec 02, 2021
2 Dec 11, 2021
18 Dec 14, 2022