CoreHook

A library that simplifies intercepting application function calls using managed code and the .NET Core runtime.

Inspired and based on the great EasyHook.

Contents

• Donations
• Build Status
• Features
• Supported Platforms
• Tested Platforms
• Dependencies
• Examples
• Plugin Examples
• Usage
  • Windows
• Contributing
• License
• Credits

Donations

If the project has helped you in any way and you want to give back, consider donating to great organizations such as Black Girls Code and Hack the Hood, or volunteering at others like The Hidden Genius Project.

Build status

| Build server | Platform | Build status | | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AppVeyor | Windows | | | Azure Pipelines | Linux, Windows | | | Travis CI | Linux | |

Features

• Intercept public API functions such as CreateFile
• Intercept internal functions by address or name if symbol files are available
• Supports NuGet package references for the plugin libraries
• Supports multiple architectures for the plugins

For more information, see the wiki.

Supported Platforms

CoreHook supports application function call interception on various architectures running Windows. Linux and macOS support is also planned.

| Architecture | Operating System | | ------------- |:---------------------:| | x86 | Windows | | x64 | Windows | | ARM | Windows 10 IoT Core |

Tested Platforms

| Operating System | Architecture(s) | | ------------------ |:---------------------:| | Windows 7 SP1 | x86, x64 | | Windows 8.1 | x86, x64 | | Windows 10 (Win32) | x86, x64, ARM | | Windows 10 (UWP) | x86, x64 | | Windows Server 2008 | x86, x64 | | Windows Server 2012 | x86, x64 | | Windows Server 2016 | x86, x64 | | Windows Server 2019 | x86, x64 |

Dependencies

• .NET Core
• CoreHook.Hooking
• CoreHook.Host

Examples

• FileMonitor - Universal Windows Platform (UWP)
• FileMonitor - Windows Desktop Applications (Win32)

Plugin Examples

• More examples for the plugins can be found in this repository

Usage

Windows

If you are building the CoreHook project (for example, with dotnet build) and not publishing it, you must setup the project configuration as described below.

Project Configuration

The project provides two options for configuring the runtime:

1. A local configuration file named CoreHook.CoreLoad.runtimeconfig.json (which is located next to CoreHook.CoreLoad.dll assembly in the CoreHook output directory) to initialize CoreCLR.
2. A global configuration file named dotnet.runtimeconfig.json.

The host module will first attempt to use the local configuration file, then it will check for the global configuration file and use that if it exists, and finally it will use the directory of the CoreHook.CoreLoad.dll assembly for resolving dependencies.

The runtimeconfig file must contain the framework information for hosting .NET Core in the target application. When you build any .NET Core application, these files are generated to the output directory. For more information on the configuration options, see here.

You can use the CoreHook.FileMonitor.runtimeconfig.json and CoreHook.FileMonitor.runtimeconfig.dev.json files found in your build output directory as references for creating the global or local configuration files.

The runtime configuration file should look like the one below, where additionalProbingPaths contains file paths the host module can check for additional dependencies. This guide assumes you have installed the .NET Core 2.2 runtime or SDK for both x86 and x64 architectures.

Notice: Either replace <user> with your local computer user name or modify the paths to point to where your NuGet packages are installed. Take a look at CoreHook.FileMonitor.runtimeconfig.dev.json in the output directory to find your paths.

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.2",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "2.2.0"
    },
    "additionalProbingPaths": [
      "C:\\Users\\<user>\\.dotnet\\store\\|arch|\\|tfm|",
      "C:\\Users\\<user>\\.nuget\\packages",
      "C:\\Program Files\\dotnet\\sdk\\NuGetFallbackFolder"
    ]
  }
}

Local Configuration

To use a local configuration, create a file with the contents described above called CoreHook.CoreLoad.runtimeconfig.json and save it to the project output directory where CoreHook.CoreLoad.dll is located.

Global Configuration

To use a global configuration, first create a dotnet.runtimeconfig.json file with the contents described above and save it to a folder. This will be the global configuration file the project uses to initialize the runtime in the target processs. In this example, our file is saved at C:\CoreHook\dotnet.runtimeconfig.json.

Set the environment variables for the x86 and x64 applications to the directory of the runtime configuration file. This allows you to have different configuration files for 32-bit and 64-bit applications.

For example (if you saved the file another installation directory or drive, make sure to use that path instead):

• Set CORE_ROOT_32 to C:\CoreHook for 32-bit applications.

• Set CORE_ROOT_64 to C:\CoreHook for 64-bit applications.

setx CORE_ROOT_64 "C:\CoreHook"
setx CORE_ROOT_32 "C:\CoreHook"

Or set them for the current command prompt session with:

set CORE_ROOT_64=C:\CoreHook
set CORE_ROOT_32=C:\CoreHook

Then, you can either open the CoreHook solution in Visual Studio or run dotnet build to build the library and the examples.

Installing Dependencies

Build or download the binary releases from CoreHook.Hooking and CoreHook.Host. You can use the download-deps script, which downloads the latest binary releases to a folder called deps in the root of the project. Place the coreload32.dll (X86, ARM) and/or coreload64.dll (X64, ARM64) binaries in the output directory of your program. Then, place the corehook32.dll (X86, ARM) and/or corehook64.dll (X64, ARM64) binaries in the same output directory. These are all of the required files for using the examples above.

You can then start the program you built above.

Windows 10 UWP

You can get the Application User Model Id (AUMID) required for launching UWP apps for the FileMonitor example with this script:

$installedapps = get-AppxPackage

$aumidList = @()
foreach ($app in $installedapps)
{
    foreach ($id in (Get-AppxPackageManifest $app).package.applications.application.id)
    {
        $aumidList += $app.packagefamilyname + "!" + $id
    }
}

$aumidList

You can print the list using the $aumidList variable.

Notes: There is currently no way to set the proper access control on our pipes on the .NET Core platform and the issue is being tracked here so we use P/Invoke to call kernel32.dll!CreateNamedPipe directly.

Windows 10 IoT Core (ARM)

Raspberry Pi itself is supported only as deployment target but there is an unsupported version of the SDK available as well. Read more about the publishing process by following this link.

For Windows 10 IoT Core, you can publish the application by running the publish.ps1 PowerShell script.

.\publish -example win32 -runtime win-arm

Make sure to also