ApiScope

ApiScope é uma ferramenta de pesquisa para Windows x64 que rastreia chamadas de API selecionadas em um processo novo ou em execução. Ela acompanha eventos de carregamento de DLL por meio da API de depuração do Windows e instala hooks antes de o processo depurado continuar a partir de cada evento.

Hooks incluídos:

• ntdll.dll!NtCreateFile (registra o caminho de destino)
• ntdll.dll!NtOpenFile (registra o caminho de destino)
• ntdll.dll!NtReadFile
• ntdll.dll!NtWriteFile
• ntdll.dll!NtClose
• ntdll.dll!NtOpenKey (registra o caminho da chave)
• ntdll.dll!NtSetValueKey
• ntdll.dll!NtQueryValueKey
• bcrypt.dll!BCryptOpenAlgorithmProvider

Demonstração

Assista ao vídeo MP4.

Build

Requisitos:

• Windows x64
• Visual Studio 2019 ou mais recente com a carga de trabalho de C++
• CMake 3.20 ou mais recente
• Git, usado pelo CMake para buscar o decoder Zydis fixado

cmake -S . -B build -A x64
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure
powershell -ExecutionPolicy Bypass -File .\scripts\validate-apiscope-hooks.ps1 .\build\bin\Release\apiscope-hooks.dll
powershell -ExecutionPolicy Bypass -File .\scripts\smoke.ps1 -SkipBuild

O Zydis v4.1.1 é obtido em um commit fixado e vinculado somente ao apiscope.exe. O apiscope-hooks.dll injetado permanece livre de imports.

Uso

apiscope.exe [--help | --version | --list-hooks]
apiscope.exe run -k <module!export|all> [-k <module!export>] [-f text|jsonl] [-o <path>] [-q] -- <program> [args...]
apiscope.exe attach -p <pid> -k <module!export|all> [-k <module!export>] [-f text|jsonl] [-o <path>] [-q]

Os nomes de hooks são sempre qualificados por módulo. A correspondência de módulos não diferencia maiúsculas de minúsculas; a correspondência de exports diferencia.

.\apiscope.exe run `
  --hook ntdll.dll!NtCreateFile `
  --hook bcrypt.dll!BCryptOpenAlgorithmProvider `
  -- C:\path\app.exe

.\apiscope.exe attach --pid 4242 --hook all

.\apiscope.exe run --hook all --format jsonl --output trace.jsonl --quiet -- app.exe

Os eventos de terminal permanecem legíveis enquanto --output opcionalmente grava texto ou JSONL em um arquivo. --quiet suprime o espelhamento de eventos no terminal. --color auto|always|never controla a cor do terminal (padrão auto: ativo em um TTY, desativado quando redirecionado ou sob NO_COLOR); a cor nunca aparece em arquivos --output. Em um TTY, o ApiScope também mostra um rodapé de status ao vivo (eventos, descartes, taxa e contagens por hook) que é redesenhado no lugar; controle-o com --status auto|always|never.

[*] ntdll.dll!NtWriteFile ----------
    timestamp      : 2026-06-07T17:44:23.3834340Z
    thread_id      : 3508
    sequence       : 3
    file_handle    : 0x000000000000008C
    length         : 16
    buffer_ascii   : Hello, ApiScope!
    result         : STATUS_SUCCESS (0x00000000)

Os eventos JSONL contêm metadados genéricos e campos específicos do hook:

{"schema_version":1,"sequence":1,"module":"bcrypt.dll","api":"BCryptOpenAlgorithmProvider","hook":"bcrypt.dll!BCryptOpenAlgorithmProvider","fields":{"flags":0,"result":"STATUS_SUCCESS (0x00000000)"}}

Consulte SCHEMA.md para o envelope de eventos e as codificações de campos por tipo (ponteiros e status são exibidos como strings hexadecimais 0x).

Pressione Ctrl+C ou Ctrl+Break para restaurar os hooks ativos, liberar a instrumentação remota e desanexar. O alvo continua em execução. Na saída natural, o ApiScope imprime o status do alvo em decimal e hexadecimal, seguido por um resumo da sessão (eventos, descartes e contagens por hook) no stderr.

Caminhos De Arquivo E Correlação De Handles

NtCreateFile, NtOpenFile e NtOpenKey resolvem o path de destino a partir de OBJECT_ATTRIBUTES e relatam o handle resultante. O ApiScope registra cada abertura bem-sucedida e anota operações posteriores no mesmo handle — leituras, gravações, acesso a valores de registro e o NtClose correspondente — com o path resolvido, para que a atividade seja legível sem rastrear handles manualmente. NtClose também remove o handle, e aberturas relativas são resolvidas por meio de um handle root_directory visto anteriormente.

[*] ntdll.dll!NtCreateFile ----------
    sequence          : 2
    path              : test_file.txt
    file_handle       : 0x000000000000008C
    result            : STATUS_SUCCESS (0x00000000)

[*] ntdll.dll!NtReadFile ----------
    sequence       : 3
    file_handle    : 0x000000000000008C
    buffer_ascii   : Hello, ApiScope!
    result         : STATUS_SUCCESS (0x00000000)
    path           : test_file.txt

O path em eventos de leitura e gravação é correlacionado a partir do handle, não observado na própria chamada.

Adicionando Um Hook

Cada hook é um arquivo sob src/apiscope-hooks/hooks/ e declara seu módulo de origem, export, handler, slot de trampoline, convenção de chamada e assinatura juntos:

DEFINE_API_HOOK(
    BCryptOpenAlgorithmProvider,
    "bcrypt.dll",
    "BCryptOpenAlgorithmProvider",
    NTSTATUS,
    WINAPI,
    PVOID* Algorithm,
    const wchar_t* AlgorithmId,
    const wchar_t* Implementation,
    ULONG Flags) {
    TraceEvent event;
    InitializeTraceEvent(&event, "bcrypt.dll", "BCryptOpenAlgorithmProvider");
    AddTraceUInt32(&event, "flags", Flags);

    NTSTATUS result = CALL_ORIGINAL(
        BCryptOpenAlgorithmProvider,
        Algorithm,
        AlgorithmId,
        Implementation,
        Flags);
    AddTraceStatus(&event, "result", result);
    EmitTraceEvent(&event);
    return result;
}

apiscope.exe --list-hooks descobre descritores de layout fixo exportados pela DLL de hooks. Não é necessária uma lista central de APIs ou um esquema de eventos no lado do lançador.

Como Funciona

sequenceDiagram
    actor User
    participant ApiScope as apiscope.exe
    participant Debugger as Windows debugger API
    participant Target as Target process
    participant Modules as Loaded DLLs
    participant Hooks as apiscope-hooks.dll
    participant Ring as Shared-memory ring

    User->>ApiScope: run program or attach PID
    alt run
        ApiScope->>Debugger: CreateProcess(DEBUG_ONLY_THIS_PROCESS)
    else attach
        ApiScope->>Debugger: DebugActiveProcess(PID)
    end
    ApiScope->>Debugger: DebugSetProcessKillOnExit(FALSE)
    Debugger-->>ApiScope: CREATE_PROCESS_DEBUG_EVENT
    ApiScope->>Target: Map import-free hook image
    ApiScope->>Ring: Create and initialize bounded ring
    ApiScope->>Target: Map shared section with NtMapViewOfSection

    loop CREATE_PROCESS / LOAD_DLL events
        Debugger-->>ApiScope: Module base and file handle
        ApiScope->>Modules: Register module name and base
        alt ntdll.dll loaded
            ApiScope->>Target: Build unpatched NtReadVirtualMemory bypass
        end
        ApiScope->>Modules: Resolve module.dll!Export and forwarders
        alt export and dependencies are loaded
            ApiScope->>Hooks: Resolve handler and trampoline slot
            ApiScope->>Target: Allocate trampoline and patch export
        else dependency is not loaded yet
            ApiScope->>ApiScope: Keep hook pending
        end
        ApiScope->>Debugger: ContinueDebugEvent
    end