NetHook SDK

Overview

When the NetHook payload is injected into a target process it starts a named-pipe server at \\.\pipe\nethook_<pid>. Everything the target sends or receives through the hooked APIs (sockets, TLS, WinINet / WinHTTP, file I/O…) is emitted over that pipe.

This SDK is the other end: a small client that connects to the pipe, turns on the hooks it cares about, and receives every captured packet. It is the same wire protocol the NetHook GUI speaks, distilled to a single drop-in file per language with no third-party dependencies.

Package layout

This release contains only what you need to build on top of the SDK. The C# binding ships as a compiled DLL (no C# source); the Python binding ships as a single module.

SdkRelease/
  documentation.html    All documentation (this single file)
  csharp/
    NetHook.Sdk.dll     The library — reference this DLL (net8.0)
    NetHook.Sdk.xml     IntelliSense / XML docs for the DLL
  python/
    nethook.py          The SDK — single module, standard library only
    pyproject.toml      Optional pip packaging
  example/
    python/             01_capture_traffic.py, 02_intercept_edit.py
    csharp/             01-capture-traffic/, 02-intercept-edit/

Quick start

Both SDKs mirror the same shape. Given a hooked process with PID 1234:

from nethook import NetHookClient, Func

with NetHookClient(1234) as nh:
    nh.send_config(Func.ALL)
    for ev in nh.events():
        if ev.kind == "data":
            print(ev.packet.summary())

using NetHook.Sdk;

using var nh = new NetHookClient(1234);
await nh.ConnectAsync();
nh.Data += p => Console.WriteLine(p.Summary());
nh.SendConfig(Func.All);
nh.Run();   // blocks until the pipe closes

The pipe protocol

Every message is a fixed 20-byte header followed by a type-specific payload, all little-endian and packed. The client and server exchange these framed messages over the byte-mode pipe.

Header (20 bytes)

Conversation

Constants

Enums

nh_data payload layout (68 bytes, then payload)

The body of a DATA / INTERCEPT message; Python struct "<QIIQIHH16s16sI".

CONFIG is 16 bytes ("<IBBxxII": enabled_funcs u32, intercept u8, block u8, pad, max_capture u32, file_cap u32; a short 12-byte config without file_cap is still accepted); DECISION is 16 bytes ("<QII": ref_id u64, action u32, data_len u32) followed by replacement bytes when the action is Modify.

Examples

The example/ folder ships two runnable samples per language, each using the shipped SDK. Every sample needs a target that is already injected with the NetHook payload.

# Python (module on the import path)
python example/python/01_capture_traffic.py 1234
python example/python/02_intercept_edit.py  1234

# C# (each project references csharp/NetHook.Sdk.dll)
dotnet run --project example/csharp/01-capture-traffic -- 1234
dotnet run --project example/csharp/02-intercept-edit  -- 1234

Python Install & connect

Copy python/nethook.py next to your script — there is nothing mandatory to pip install. It uses only the standard library (ctypes, socket, struct). A pyproject.toml is included if you prefer pip install ./python.

from nethook import NetHookClient, Func, Action

nh = NetHookClient(pid=1234)        # or NetHookClient(pipe_name=r"\\.\pipe\nethook_1234")
nh.connect(timeout_ms=4000)         # waits for the pipe to appear
# ... use nh ...
nh.close()

# Or as a context manager (auto connect on enter, close on exit):
with NetHookClient(1234) as nh:
    nh.send_config(Func.SSL_WRITE | Func.SSL_READ)
    for ev in nh.events():
        ...

Intercept example

with NetHookClient(1234) as nh:
    nh.send_config(Func.ALL, intercept=True)
    for ev in nh.events():
        if ev.kind == "intercept":
            pkt = ev.packet
            if b"password" in pkt.data.lower():
                nh.drop(pkt)                       # block it
            else:
                nh.forward(pkt)                    # or nh.forward(pkt, new_bytes)

Python API reference

class NetHookClient

class Event

ev.kind is one of "hello", "data", "intercept", "log", "bye". Populated fields by kind:

class Packet

See the packet field reference. Helpers: packet.summary(), packet.ascii_preview(limit=64), packet.api, packet.out, packet.source, packet.dest. Raw bytes are packet.data.

Constants

Func (hook bits, see table), Action.FORWARD / DROP / MODIFY, Direction.SEND / RECV, MsgType.*.

C# Install & connect

The C# SDK ships as a compiled library, csharp/NetHook.Sdk.dll (namespace NetHook.Sdk, targets .NET 8, uses only System.IO.Pipes). There is no C# source to build — reference the DLL from your project, keeping NetHook.Sdk.xml beside it for IntelliSense:

<ItemGroup>
  <Reference Include="NetHook.Sdk">
    <HintPath>path\to\csharp\NetHook.Sdk.dll</HintPath>
  </Reference>
</ItemGroup>

Two ready-to-run example projects that already reference the DLL are in example/csharp/. Basic usage:

using NetHook.Sdk;

using var nh = new NetHookClient(1234);   // or new NetHookClient("nethook_1234", 1234)
await nh.ConnectAsync(timeoutMs: 4000);   // or nh.Connect(4000) for the sync path

nh.Hello += (pid, arch, image) => Console.WriteLine($"{image} ({arch}-bit)");
nh.Data  += pkt => Console.WriteLine(pkt.Summary());

nh.SendConfig(Func.SslWrite | Func.SslRead);
nh.Run();      // blocking read loop; use RunAsync() for a Task

Intercept example

nh.Intercepted += pkt =>
{
    var text = System.Text.Encoding.ASCII.GetString(pkt.Data);
    if (text.Contains("password")) nh.Drop(pkt);
    else                           nh.Forward(pkt);   // or nh.Forward(pkt, newBytes)
};
nh.SendConfig(Func.All, intercept: true);
nh.Run();

C# API reference

class NetHookClient : IDisposable

Events (raised on the read loop)

class Packet

Fields per the reference; helpers Summary(), AsciiPreview(limit), properties Api, Out, Source, Dest. Raw bytes are Data.

Constants

Enums Func (hook bits, see table), NhAction, Direction, MsgType; constants NetHookClient.Magic, NetHookClient.HeaderSize.

Message types

Hook functions

Pass any OR-combination to send_config / SendConfig. Use Func.ALL (Func.All) for everything.

Packet fields

A Packet is the decoded nh_data record plus its captured bytes. Not every field is meaningful for every hook — TLS, file and WinHTTP captures carry no socket endpoint, so the address/port fields are empty for them.

Error handling