Windows Hardware Documentation

Syscall Filter WDF KM Samples

This section provides sample code for implementing a syscall filter using the Windows Driver Framework (WDF) in Kernel Mode (KM).

Overview

A syscall filter is a kernel-mode driver that intercepts system calls made by user-mode applications. This allows for advanced scenarios such as security monitoring, application control, and performance analysis. Implementing such filters requires a deep understanding of the Windows kernel and WDF.

Sample Files

The following sample demonstrates the core concepts of building a syscall filter with WDF KM:

Key Concepts Demonstrated

• WDF Driver Initialization: Setting up the WDF driver object and framework.
• Hooking System Calls: Techniques for intercepting system calls at the kernel level. This often involves interacting with the system's call gate or other internal mechanisms.
• Callback Functions: Implementing custom logic to process intercepted system calls.
• Data Structures: Handling kernel-mode data structures related to system calls and process context.
• Security Considerations: Best practices for developing secure kernel-mode drivers to prevent system instability or security vulnerabilities.
• Driver Unload: Properly cleaning up resources when the driver is unloaded.

Implementation Details

The primary mechanism for filtering syscalls in this sample involves:

• Finding the System Service Descriptor Table (SSDT): This table maps system service numbers to their kernel-mode implementations.
• Patching the SSDT: Replacing the original function pointer in the SSDT with a pointer to a custom handler function.
• Custom Handler: This function will:
  • Record information about the intercepted syscall (e.g., process ID, syscall number, arguments).
  • Optionally, modify arguments or return values.
  • Call the original system service function.
  • Return the result.
• Restoring the SSDT: Ensuring the original function pointer is restored when the filter is unloaded or disabled.

Example: Intercepting NtCreateFile

To intercept the NtCreateFile system call, the driver would typically:

1. Locate the address of the NtCreateFile kernel function.
2. Determine its corresponding entry in the SSDT.
3. Save the original address from the SSDT.
4. Replace the SSDT entry with the address of a custom handler, MyNtCreateFileHandler.

The MyNtCreateFileHandler function would then have access to the arguments passed to NtCreateFile, such as the file name and desired access rights.

// Simplified example of a syscall handler
NTSTATUS MyNtCreateFileHandler(
    OUT PHANDLE FileHandle,
    IN ACCESS_MASK DesiredAccess,
    IN POBJECT_ATTRIBUTES ObjectAttributes,
    OUT PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG ShareAccess,
    IN ULONG CreateDisposition,
    IN ULONG CreateOptions,
    IN ULONG EaLength,
    IN PVOID EaBuffer,
    IN ULONG FileAttributes,
    IN ULONG SecurityFlags
)
{
    // Log the syscall event
    DbgPrint("SyscallFilter: NtCreateFile called by PID %d\n", PsGetCurrentProcessId());

    // Call the original NtCreateFile function
    // ... (requires saving the original function pointer)
    NTSTATUS status = OriginalNtCreateFile(
        FileHandle,
        DesiredAccess,
        ObjectAttributes,
        IoStatusBlock,
        ShareAccess,
        CreateDisposition,
        CreateOptions,
        EaLength,
        EaBuffer,
        FileAttributes,
        SecurityFlags
    );

    // Process the return status if needed
    return status;
}
        

Prerequisites

• Windows Driver Kit (WDK) installed.
• Visual Studio with C/C++ development workload.
• Understanding of C/C++ and Windows kernel programming concepts.
• Familiarity with WDF.

Building and Testing

To build and test this sample:

1. Open the solution in Visual Studio.
2. Configure the build for a kernel-mode driver (e.g., WinDbg target).
3. Build the driver.
4. Install and load the driver on a test system. Use tools like WinDbg for debugging.
5. Monitor driver output and system behavior.

Important Notes

• Directly patching the SSDT is a powerful but dangerous technique. Incorrect implementation can lead to system instability, Blue Screen of Death (BSOD), or security vulnerabilities.
• Microsoft may change internal kernel structures, including the SSDT, in future Windows versions. Drivers relying on these internal details might break.
• Consider alternative, more stable methods for kernel-mode hooking if possible, such as using undocumented APIs or hooking specific driver functions rather than direct system call table patching.
• This sample is for educational purposes. Use extreme caution when deploying such drivers in production environments.