# jthuraisamy/syswhispers architecture

> Architecture diagram of the GitHub repository jthuraisamy/syswhispers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jthuraisamy/syswhispers
- Repository: https://github.com/jthuraisamy/syswhispers

## Overview

##### What this project is (type + purpose)

**SysWhispers is a single-purpose CLI code generator** (Python script) that produces **two artifacts** for Windows x64 implants/tools:

- a **C/C++ header** (`.h`) containing syscall prototypes + needed typedefs
- an **x64 MASM assembly** file (`.asm`) implementing syscall stubs that **invoke syscalls directly** (bypassing user-mode API hooks in `ntdll.dll`)

It targets **core kernel (`ntoskrnl.exe`) syscalls** across **Windows XP → Windows 10 19042**, and intentionally **doesn’t call `RtlGetVersion`**; it reads OS info in assembly via **PEB access** so a single stub can support multiple versions.

##### What the file tree implies architecturally

Top-level:

- `syswhispers.py`
The entire “application” entrypoint: CLI arg parsing, selection of syscalls, and file generation.

- `data/` (all of SysWhispers’ “knowledge base”)
- `prototypes.json` — function prototypes (names, args, return types)
- `typedefs.json` — typedefs required by prototypes
- `syscall_numbers.json` — mapping of syscall → numbers per Windows version/build

- `example-output/`

This strongly suggests a **data-driven generator**: the “logic” is in Python, the “content” is in JSON.

##### Key behaviors from README to capture

- **Inputs**: presets (`--preset all/common`), explicit functions (`--functions`), versions (`--versions`), output name (`-o/--out-file`)
- **Core processing**:
- choose syscall set (preset/function list)
- filter/version-compat resolve (based on versions requested)
- lookup numbers (from `syscall_numbers.json`)
- merge prototypes and typedefs (from JSON)
- emit `.h` + `.asm`
- **Output consumption**:
- imported into a **Visual Studio x64 project**
- MASM build customization enabled
- **Runtime effect (why it exists)**:
- generated stubs call syscalls directly rather than via hooked user-mode APIs
- OS version handling done by **PEB query in assembly**

##### User / Operator
- Provides CLI args: `--preset`, `--functions`, `--versions`, `-o`

##### SysWhispers CLI (syswhispers.py)
- **Argument Parser / Options**
- **Syscall Selection**
- “Preset resolver” (common/all)
- “Function list resolver”
- **Version Compatibility Filter**
- **Metadata Loader**
- loads `data/syscall_numbers.json`
- loads `data/prototypes.json`
- loads `data/typedefs.json`
- **Code Generator / Emitter**
- Header emitter (`*.h`)
- ASM emitter (`*.asm`)

##### Data Files (JSON)
- Prototypes DB (`prototypes.json`)
- Typedefs DB (`typedefs.json`)
- Syscall Numbers Matrix (`syscall_numbers.json`)

##### Outputs
- `syscalls.h` (or `syscalls_*.h`)
- `syscalls.asm` (or `syscalls_*.asm`)

##### Downstream Consumer
- “Implant / C++ Project (VS x64 + MASM)”
- shows include of `.h` and compilation of `.asm`

##### Generated Stub Layer
- “SysWhispers syscall stubs (ASM)”
- “PEB-based OS version detection”
- “select correct syscall number per version”
- “invoke syscall instruction”

##### Windows User Mode Context
- PEB (explicit object)

##### Kernel
- `ntoskrnl.exe` (syscall dispatcher / system service)
- Target syscalls (e.g., `NtAllocateVirtualMemory`, etc.)

##### Architectural patterns/principles to call out

- **Data-driven code generation**: JSON “databases” drive emitted code.
- **Separation of concerns**:
- metadata (JSON) vs generator (Python) vs emitted artifacts (C header/ASM)
- **Cross-version abstraction**:
- one generated API surface supports multiple Windows versions
- **Evasion tactic**:
- bypass user-mode hooks by not using the hooked API path

##### Operator
→ 2. **SysWhispers CLI (syswhispers.py)**

##### Runtime section: Implant calls generated functions
→ **ASM stub** (PEB query + syscall number selection)
→ **syscall transition**
→ **Kernel (ntoskrnl.exe)**

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Generator-time (Build-time)
    %% =========================
    subgraph "Generator-time (Build-time): Data-driven code generation"
        direction TB

        Operator["Operator / User"]:::external

        subgraph "SysWhispers CLI (Python)"
            direction TB

            CLI["syswhispers.py (CLI code generator)"]:::generator

            ArgParse["Argument Parser / Options\n(--preset, --functions, --versions, -o/--out-file)"]:::generator
            Selection["Syscall Selection\n(Preset resolver + Function list resolver)"]:::generator
            VersionFilter["Version Compatibility Filter\n(resolve requested versions/builds)"]:::generator

            subgraph "Metadata Loader (JSON readers)"
                direction TB
                Loader["Metadata Loader"]:::generator
                DataDir[("data/ (knowledge base)")]:::data

                PrototypesDB[("prototypes.json\n(function signatures)")]:::data
                TypedefsDB[("typedefs.json\n(C typedefs)")]:::data
                NumbersDB[("syscall_numbers.json\n(per-version syscall IDs)")]:::data
            end

            subgraph "Code Generator / Emitters"
                direction TB
                Emit["Code Generator / Emitters"]:::generator
                HeaderEmit["Header emitter\n(writes .h)"]:::generator
                AsmEmit["ASM emitter\n(writes .asm)"]:::generator
            end
        end

        Deps["Python runtime dependencies\n(requirements.txt)"]:::deps

        subgraph "Generated Artifacts"
            direction TB
            OutH["Generated: syscalls.h (C/C++ header)"]:::artifact
            OutASM["Generated: syscalls.asm (x64 MASM stubs)"]:::artifact
        end

        subgraph "Downstream Consumer (Build Integration)"
            direction TB
            VSProj["Implant / C++ Project\n(Visual Studio x64 + MASM enabled)"]:::consumer
        end
    end

    %% =========================
    %% Runtime (Implant execution)
    %% =========================
    subgraph "Runtime (Implant execution): Direct syscalls"
        direction TB

        Implant["Implant code (C/C++)"]:::runtime
        ProtoUse["Calls generated prototypes\n(from header)"]:::runtime

        Stub["SysWhispers syscall stubs (ASM)\n- PEB-based OS version detection\n- Select correct syscall number\n- Invoke syscall instruction"]:::runtime

        PEB["PEB (OS version/build info)\n(read directly in assembly)"]:::runtime

        SyscallTrans["CPU syscall transition\n(syscall instruction)"]:::runtime

        Kernel["Kernel: ntoskrnl.exe\n(System Service Dispatcher + syscalls)"]:::kernel

        subgraph "Avoided / Bypassed path (conceptual)"
            direction TB
            Win32API["Win32 / NT API call path"]:::bypass
            NTDLL["ntdll.dll user-mode stubs\n(potentially hooked)"]:::bypass
            Hooks["User-mode hooks / EDR"]:::bypass
        end
    end

    %% =========================
    %% Generator-time flows
    %% =========================
    Operator -->|"provides_CLI_args"| ArgParse
    ArgParse -->|"configures"| Selection
    Selection -->|"selected_syscalls"| VersionFilter
    VersionFilter -->|"requests_metadata"| Loader

    CLI -->|"orchestrates"| ArgParse
    CLI -->|"orchestrates"| Selection
    CLI -->|"orchestrates"| VersionFilter
    CLI -->|"orchestrates"| Loader
    CLI -->|"orchestrates"| Emit

    Loader -->|"reads"| PrototypesDB
    Loader -->|"reads"| TypedefsDB
    Loader -->|"reads"| NumbersDB
    DataDir -->|"contains"| PrototypesDB
    DataDir -->|"contains"| TypedefsDB
    DataDir -->|"contains"| NumbersDB

    VersionFilter -->|"uses"| NumbersDB
    Selection -->|"uses"| PrototypesDB
    Selection -->|"uses"| TypedefsDB

    Loader -->|"feeds_metadata"| Emit
    Emit -->|"writes"| HeaderEmit
    Emit -->|"writes"| AsmEmit
    HeaderEmit -->|"outputs"| OutH
    AsmEmit -->|"outputs"| OutASM

    Deps -->|"runtime_dep_for"| CLI

    OutH -->|"included_by"| VSProj
    OutASM -->|"assembled_by_MASM"| VSProj

    %% =========================
    %% Runtime flows
    %% =========================
    VSProj -->|"builds_and_runs"| Implant
    Implant -->|"calls"| ProtoUse
    ProtoUse -->|"jumps_to"| Stub

    Stub -->|"reads"| PEB
    Stub -->|"executes"| SyscallTrans
    SyscallTrans -->|"enters"| Kernel

    %% Bypassed path (dotted)
    Implant -.->|"would_have_called"| Win32API
    Win32API -.->|"typically_flows_through"| NTDLL
    NTDLL -.->|"may_be_intercepted_by"| Hooks
    Implant -.->|"bypassed_via_direct_syscalls"| Stub

    %% =========================
    %% Click events (component_mapping)
    %% =========================
    click CLI "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"
    click ArgParse "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"
    click Selection "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"
    click VersionFilter "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"
    click Loader "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"
    click Emit "https://github.com/jthuraisamy/syswhispers/blob/master/syswhispers.py"

    click DataDir "https://github.com/jthuraisamy/syswhispers/tree/master/data/"
    click PrototypesDB "https://github.com/jthuraisamy/syswhispers/blob/master/data/prototypes.json"
    click TypedefsDB "https://github.com/jthuraisamy/syswhispers/blob/master/data/typedefs.json"
    click NumbersDB "https://github.com/jthuraisamy/syswhispers/blob/master/data/syscall_numbers.json"

    click OutH "https://github.com/jthuraisamy/syswhispers/blob/master/example-output/syscalls.h"
    click OutASM "https://github.com/jthuraisamy/syswhispers/blob/master/example-output/syscalls.asm"
    click Deps "https://github.com/jthuraisamy/syswhispers/blob/master/requirements.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#EEF2FF,stroke:#3730A3,stroke-width:1.5px,color:#111827
    classDef generator fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0F172A
    classDef data fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5px,color:#0F172A
    classDef artifact fill:#DCFCE7,stroke:#16A34A,stroke-width:1.5px,color:#052E16
    classDef consumer fill:#D1FAE5,stroke:#047857,stroke-width:1.5px,color:#052E16
    classDef deps fill:#E5E7EB,stroke:#6B7280,stroke-width:1.5px,color:#111827
    classDef runtime fill:#FFEDD5,stroke:#EA580C,stroke-width:1.5px,color:#111827
    classDef kernel fill:#FED7AA,stroke:#9A3412,stroke-width:2px,color:#111827
    classDef bypass fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,stroke-dasharray: 6 4,color:#111827
```
