GitHub - cristeigabriela/bb: Benowin Blanc — Windows through a detective's lens.

What is this?

Windows ships with thousands of C/C++ headers (the Windows SDK) that define every struct, enum, constant, macro, and function the OS exposes. Separately, the community-maintained PHNT (Process Hacker NT headers) documents internal structures and syscalls that Microsoft doesn't publish.

bb parses these headers with libclang and gives you fast, searchable, pretty-printed access to all of it — struct layouts, constant values, function ABIs with per-parameter register/stack locations, and more (hell, even TUIs!) — no debugger, no IDE, no digging through .h files by hand.

Quick start

Building

On a Windows host, you will need the following:

• Visual Studio 2019/2022 Build Tools
• LLVM + Clang (libclang.dll) version >=18.1
• Rust 2024 edition
• uv (Python package + project manager — winget install --id=astral-sh.uv -e). Plain Python >=3.10 also works as a fallback.

Afterwards, you may produce the binaries by invoking the following command:

.\update-submodules.ps1   # init + generate submodule data
cargo build --release

The project uses two submodules, managed by update-submodules.ps1:

You can update them individually or all at once (.\update-submodules.ps1). Both support env var overrides for custom data:

AST cache

After the first bb-funcs / bb-types / bb-consts invocation, the parsed translation unit is saved (via clang_saveTranslationUnit) under %LOCALAPPDATA%\bb\ast\<sha256>.ast. Subsequent runs with the same SDK

• arch + mode load the AST directly and skip libclang's full re-parse. Typical numbers on this SDK / WDK combo:

The cache key hashes the synthetic header content, every clang argument, and the bb-sdk crate version — any change to header config, SDK install path, target arch, or a bb-sdk release invalidates automatically. Saved ASTs are ~80 MB; delete the bb/ast/ directory to nuke them, or set BB_NO_CACHE=1 to bypass per-invocation.

First commands

Inspect a struct layout:

Recurse into nested types:

bb-types --phnt --struct _PEB --depth 2

Search for constants by wildcard:

bb-consts --name GENERIC_*

Scope to a specific enum:

bb-consts --enum _MINIDUMP_TYPE

Use Enum::Constant syntax to search within enums:

bb-consts --name "_MINIDUMP_TYPE::*"

Target a different architecture from your host:

bb-types --arch arm64 --struct _CONTEXT

Inspect a function's ABI breakdown:

bb-funcs --name CreateFileW

List exported functions from a header:

bb-funcs --name "Create*" --filter fileapi.h --exported

Filter functions with SQL WHERE clauses:

bb-funcs --where "params > 3 AND return_type = 'BOOL'"
bb-funcs --where "name LIKE '%File%' AND is_exported = true"

Filter kernel/driver functions by IRQL constraint:

bb-funcs --mode kernel --name "Wdf*" --irql "<= DISPATCH_LEVEL"
bb-funcs --mode kernel --irql PASSIVE_LEVEL

Export as JSON or SQLite for your own tooling:

bb-types --arch arm64 --struct _CONTEXT --json
bb-consts --name "PROCESS_*" --json
bb-funcs --name "Nt*" --phnt --json

# or export to SQLite
bb-funcs --name "Create*" --sqlite funcs.db
bb-types --struct "_*" --sqlite types.db

JSON mode in bb-types performs full nested type expansion, producing all matched types alongside their deduplicated referenced_types — regardless of the --depth flag. SQLite exports mirror the same level of detail as JSON.

Typo? Both CLIs suggest close matches:

bb-types --struct _PBE
error: no structs matching '_PBE'

  did you mean?

    _ABC
    _PSP
    _PEB

The tools

Web viewer

Supported headers

bb-types  --mode kernel --winsdk --struct *DRIVER_OBJECT*
bb-funcs  --mode kernel --name NetAdapterCreate
bb-funcs  --mode kernel --name WdfCollectionAdd

bb-types --phnt win11 --struct _PEB
bb-consts --phnt --name "STATUS_*"

Header coverage

Measured against the documented MSDN free-function surface that bb-sparse embeds (sdk-api for user mode, windows-driver-docs-ddi for kernel) — see cargo test -p bb-tests sparse_coverage_dump -- --ignored --nocapture to run it yourself. Interface methods aren't counted because bb-funcs filters on EntityKind::FunctionDecl, and IDL vtables surface those as function-pointer fields inside IFoo::Vtbl structs.

Architecture support

All tools support cross-compilation via --arch — inspect layouts and ABIs for any target from any host:

bb-types --arch arm64 --struct _CONTEXT

How it works

The flow is described below:

We use bb-sdk to discover (or gather) the SDK environment, then we generate a SDK-specific "synthetic header" (also known as an Unsaved/CXUnsavedFile in the Clang-world) which will be passed through partial compilation with libclang.dll and in turn give us a TranslationUnit.

From the translation unit, we lift the AST entities into bb-clang serializable objects, and we use the information that we expose there to develop the tools.

For functions, bb-clang computes the full ABI layout: which register or stack slot each parameter occupies, per architecture and calling convention (cdecl, stdcall, fastcall). bb-funcs enriches this with MSDN metadata (DLL, lib, min Windows version, and — for kernel/WDF DDIs — IRQL constraints, KMDF/UMDF versions, etc.) from sparse and cross-references known constant values for each parameter. SQL WHERE clause filtering is supported via bb-sql.

For macros specifically, bb-consts does a two-pass resolution: first pass evaluates simple literals and variables, second pass substitutes known constant names into unresolved macro token streams before re-evaluating. This handles things like #define PROCESS_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0xFFFF).