Scanner API

This document specifies the public API surface of the scanner module — the functions exposed in scanner_api.h and the named pipe contract for external consumers.

Related: Scanner Module · PE Parser Module · Data Types Reference

1. Public C API

Defined in scanner/scanner_api.h:

classDiagram
    class ScannerAPI {
        <<extern "C">>
        +InitializeScanner() void
        +SubmitScanRequest(req: SCAN_REQUEST*) void
        +ShutdownScanner() void
    }

    class SCAN_RESULT {
        <<enumeration>>
        SCAN_CLEAN = 0
        SCAN_SUSPICIOUS = 1
        SCAN_MALICIOUS = 2
        SCAN_ERROR = 3
    }

    class SCAN_MODE {
        <<enumeration>>
        SCAN_FULL = 1
        SCAN_SINGLE = 2
    }

    ScannerAPI ..> SCAN_RESULT : returns via policy

Function Reference

InitializeScanner

void InitializeScanner()

Initializes the scan queue and starts the worker thread.

Aspect Detail
Thread safety Must be called once from the main thread
Side effects Creates g_QueueEvent, starts ScanWorker thread
Preconditions None
Postconditions Queue is ready, worker is running

SubmitScanRequest

void SubmitScanRequest(const SCAN_REQUEST* req)

Enqueues a scan request for asynchronous processing by the worker thread.

Aspect Detail
Thread safety Thread-safe (uses internal mutex)
Blocking Non-blocking (returns immediately after enqueue)
Backpressure If queue is full (10,000), oldest entry is dropped
Ownership Copies the SCAN_REQUEST — caller retains ownership of req

ShutdownScanner

void ShutdownScanner()

Stops the worker thread and destroys the queue.

Aspect Detail
Blocking Blocks until worker thread exits (WaitForSingleObject(INFINITE))
Side effects Sets g_Running = FALSE, closes thread handle, drains queue
Postconditions All resources released

2. Named Pipe Contract

The scanner exposes a named pipe server for receiving scan requests from the monitor.

sequenceDiagram
    participant Client as Monitor (Client)
    participant Server as Scanner (Server)

    Note over Server: CreateNamedPipe("\\.\pipe\ScannerPipe")
    Note over Server: ConnectNamedPipe() — blocks

    Client->>Server: CreateFile("\\.\pipe\ScannerPipe")
    Note over Server: Connection accepted

    loop Scan Requests
        Client->>Server: WriteFile(SCAN_REQUEST, 280 bytes)
        Server->>Server: ReadFile(&req, sizeof(SCAN_REQUEST))
        Server->>Server: SubmitScanRequest(&req)
    end

    Client->>Server: Disconnect (close handle)
    Note over Server: ReadFile returns FALSE → exit loop

Pipe Specification

Property Value
Name \\.\pipe\ScannerPipe
Direction Client → Server (monitor writes, scanner reads)
Message Format Raw SCAN_REQUEST struct (280 bytes)
Pipe Mode PIPE_TYPE_MESSAGE \| PIPE_READMODE_MESSAGE \| PIPE_WAIT
Access PIPE_ACCESS_DUPLEX
Max Instances 1
Buffer Size 1024 bytes (in and out)
Security Default (NULL security attributes)

Message Format

Each pipe message is a raw SCAN_REQUEST struct written/read as a single message:

Field Offset Size Description
filePath 0 520 bytes Null-terminated wide-character file path (WCHAR[260])
pid 520 4 bytes Process ID from kernel notification
timestamp 524 8 bytes FILETIME set by monitor via GetSystemTimeAsFileTime()
Total   ~532 bytes Padded to struct alignment

3. Internal Queue API

Defined in scanner/queue.h:

Function Signature Description
InitializeQueue void InitializeQueue() Creates the auto-reset event
Enqueue void Enqueue(const SCAN_REQUEST* req) Thread-safe enqueue with backpressure
Dequeue BOOL Dequeue(SCAN_REQUEST* req) Thread-safe dequeue, returns FALSE if empty
WaitForQueueSignal void WaitForQueueSignal() Blocks up to 500ms on queue event
DestroyQueue void DestroyQueue() Drains queue and closes event handle

4. PE Parser API

Defined in scanner/pe_parser.h:

Function Signature Description
NormalizePath bool NormalizePath(const wchar_t* input, wstring& output) Convert NT path to Win32 path
SafeParsePE bool SafeParsePE(const wchar_t* path, ParsedFile* out) Parse PE with path normalization
SafeParsePE_SEH bool SafeParsePE_SEH(const wchar_t* path, ParsedFile* out) Parse PE with SEH exception protection

5. Feature & Classification API

Function File Signature Description
ExtractFeatures features.h void ExtractFeatures(const ParsedFile*, FeatureVector*) Extract ML features from parsed PE
Classify ml.h SCAN_RESULT Classify(const FeatureVector*) Classify features into verdict
ApplyPolicy policy.h void ApplyPolicy(const wchar_t*, SCAN_RESULT) Execute policy action for verdict

Next Steps