Musa.CoreLite 1.1.0

Musa.CoreLite

• 中文

Musa.CoreLite is a lightweight core library extracted from the Musa.Core project, providing complete support for calling all Zw* system routines for Windows developers.

This project aims to solve the problem of incomplete export symbols for Zw* system routines, allowing developers to directly call all Zw* system routines in both user mode and kernel mode without worrying about missing symbols.

Usage

Right-click your project, select "Manage NuGet Packages", search for Musa.CoreLite, choose the appropriate version, and click "Install".

The NuGet package depends on Musa.Veil. You can directly include <Veil.h>.

Header-only Mode

Add the following code to your .vcxproj file. In this mode, the lib file will not be automatically linked.

  <PropertyGroup>
    <MusaCoreOnlyHeader>true</MusaCoreOnlyHeader>
  </PropertyGroup>

Code Example

Kernel Mode (Driver)

Musa.CoreLite.TestForDriver.cpp

EXTERN_C NTSTATUS DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
)
{
    PAGED_CODE();
    UNREFERENCED_PARAMETER(DriverObject);
    UNREFERENCED_PARAMETER(RegistryPath);

    NTSTATUS Status;

    do {
        DriverObject->DriverUnload = Main::DriverUnload;

        Status = MusaCoreLiteStartup();
        if (!NT_SUCCESS(Status)) {
            MusaLOG("Failed to initialize MusaCoreLite, 0x%08lX", Status);
            break;
        }

        MusaLOG("Test ZwGetCurrentProcessorNumber() return %lu",
            ZwGetCurrentProcessorNumber());
    } while (false);

    if (!NT_SUCCESS(Status)) {
        Main::DriverUnload(DriverObject);
    }

    return Status;
}

// In DriverUnload:
(void)MusaCoreLiteShutdown();

User Mode

#include <Veil.h>
#include <Musa.CoreLite/Musa.CoreLite.h>

int main()
{
    NTSTATUS Status = MusaCoreLiteStartup();
    if (!NT_SUCCESS(Status)) {
        return Status;
    }

    // Call any Zw* system routine
    auto ZwGetCurrentProcessorNumber =
        reinterpret_cast<decltype(&::ZwGetCurrentProcessorNumber)>(
            MusaCoreLiteGetSystemRoutine("ZwGetCurrentProcessorNumber"));

    if (ZwGetCurrentProcessorNumber) {
        printf("Current processor number: %lu\n", ZwGetCurrentProcessorNumber());
    }

    (void)MusaCoreLiteShutdown();
    return 0;
}

API Usage Convention

• Parameter validity is the caller's responsibility. The library does not validate input parameters for performance reasons. Passing invalid pointers or mismatched hash values results in undefined behavior.
• MusaCoreLiteStartup() must be called exactly once before any other API, and must not be called concurrently. MusaCoreLiteShutdown() is the reverse.
• MusaCoreLiteGetSystemRoutine / MusaCoreLiteGetSystemRoutineByNameHash are safe to call concurrently after MusaCoreLiteStartup() returns successfully.

License

This project is licensed under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please read the Code of Conduct before submitting issues or pull requests.

Acknowledgements

• Thanks: The implementation was provided by @xiaobfly.