# wavestone-cdt/edrsandblast architecture

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

- Interactive diagram: https://gitdiagram.com/wavestone-cdt/edrsandblast
- Repository: https://github.com/wavestone-cdt/edrsandblast

## Overview

1. **Overall shape**
   - This repo is a Windows x64 offensive toolkit centered on a shared C codebase plus multiple front-end binaries.
   - The core design splits into:
     - a **common library layer** with reusable primitives and parsing logic,
     - **user-mode evasion** logic,
     - **kernel-mode evasion** logic mediated by a vulnerable driver,
     - small **CLI entrypoints** that choose actions,
     - and a separate **Python offset-extraction pipeline** used to prepare version-specific data.

2. **Top-level build products**
   - `EDRSandblast` is the main project containing the reusable implementation.
   - `EDRSandblast_StaticLibrary` packages the core API for reuse by other binaries.
   - `EDRSandblast_CLI` is the primary command-line front end.
   - `EDRSandblast_LsassDump` is a specialized launcher focused on LSASS dumping.
   - The solution is Visual Studio–based (`.sln`, `.vcxproj`) and targets native Windows, not .NET.

3. **Core subsystem layout**
   - The code is organized by concern rather than by executable:
     - `UserlandBypass/` handles DLL unhooking, direct syscalls, and other in-process evasion.
     - `KernellandBypass/` handles kernel callback removal and ETW Threat Intelligence neutralization.
     - `LSASSProtectionBypass/` handles `RunAsPPL` and `Credential Guard`-related bypasses.
     - `Drivers/` contains driver-specific implementations for vulnerable-driver read/write primitives.
     - `Utils/` contains shared utilities for parsing, offsets, memory primitives, process inspection, and Windows plumbing.
   - `Includes/` is the public header surface for these subsystems.

4. **Primary control flow**
   - The CLI front ends call into `EDRSandblast_API` in the static library.
   - That API dispatches into one of several modes: audit, dump, cmd, credguard, firewall, or driver-loading actions.
   - Each mode composes lower-level capabilities:
     - user-mode hooks discovery/removal,
     - kernel memory read/write,
     - process dumping,
     - Windows service / firewall manipulation,
     - or driver installation and cleanup.

5. **User-mode evasion path**
   - The user-mode path is built around inspecting loaded modules from the process PEB, comparing memory-backed DLLs to on-disk DLLs, and identifying tampering/hooking.
   - The implementation has multiple ways to obtain a clean `NtProtectVirtualMemory`-equivalent path:
     - standard unhooking,
     - custom trampoline,
     - reusing an EDR trampoline,
     - loading a duplicate DLL,
     - or direct syscalls.
   - This subsystem’s boundary is entirely in-process user memory, but it often exists to prepare for later operations that need reliable system calls.

6. **Kernel-mode bypass path**
   - Kernel-mode operations depend on a vulnerable signed driver to provide arbitrary kernel **read/write** capability.
   - With that primitive, the tool can manipulate kernel structures to:
     - remove process/thread/image notify routines,
     - unlink minifilter callbacks,
     - disable the ETW Threat Intelligence provider,
     - change process protection state for LSASS access.
   - The kernel path is sensitive to Windows build differences, so it relies on version-specific offsets rather than runtime pattern guessing.

7. **Driver abstraction boundary**
   - Driver support is intentionally isolated behind a small primitive interface:
     - read kernel memory,
     - write kernel memory,
     - close driver handle.
   - `KernelMemoryPrimitives.h` selects the concrete backend at compile time (`GDRV`, `RTCore64`, or `DBUtil_2_3` in the current tree).
   - The architecture treats the driver as a thin transport layer; all higher-level bypass logic is driver-agnostic once the primitive is available.

8. **LSASS protection bypass features**
   - `RunAsPPL` bypass uses kernel writes to raise the current process protection level so it can access protected LSASS memory.
   - `CredGuard` bypass patches `wdigest.dll`-related state so cleartext credentials can be cached again in LSASS for new logons.
   - These two features are separate from EDR-bypass mechanisms, but they share the same kernel-memory and offsets infrastructure.

9. **Offsets and versioning subsystem**
   - A major architectural dependency is the `Offsets/` data set and the code that consumes it.
   - CSV files store build-specific offsets for:
     - `ntoskrnl.exe`,
     - `fltmgr.sys`,
     - `wdigest.dll`,
     - `ci.dll`.
   - `ExtractOffsets.py` can generate/update these files using PDB metadata from Microsoft symbol servers or Winbindex sources.
   - At runtime, the C code uses these offsets to safely find internal kernel fields without guessing.

10. **Process and binary parsing utilities**
   - The `Utils/` layer contains the repo’s “plumbing”:
     - PE parsing and relocation handling,
     - PDB/symbol parsing,
     - string/list helpers,
     - file version inspection,
     - remote PEB browsing,
     - syscall number discovery,
     - Windows service management,
     - firewall rules,
     - HTTP client support.
   - These utilities support both detection logic and the reconstruction of clean code paths or memory structures.

11. **Audit and detection logic**
   - The `audit` mode is architecturally important because it is both a reconnaissance mode and a validation mode for the tool itself.
   - It enumerates:
     - user-mode hook modifications,
     - kernel callbacks,
     - and EDR-related drivers/processes.
   - Detection uses naming heuristics, signer information, and known security-driver catalogs, which then feed later bypass stages.

12. **External dependencies and operational inputs**
   - The repository assumes the presence of:
     - a vulnerable signed driver file,
     - correct offsets CSVs,
     - and optionally internet access for symbol retrieval.
   - External sources that materially shape the workflow include Microsoft Symbol Server, Winbindex, and LOLDrivers-style driver samples.
   - The runtime behavior therefore depends heavily on offline artifacts prepared ahead of execution.

13. **Language and platform boundaries**
   - Core implementation is native C/C++, with a small assembly component for syscall stubs.
   - The offset extractor is Python-based and only prepares data; it is not part of the runtime attack path.
   - The entire repo is Windows-specific and centered on kernel structures, PEB/PE parsing, and Windows driver/service APIs.

14. **How to draw the architecture**
   - A good diagram would show:
     - **CLI binaries** at the top,
     - feeding a **shared static library / core API**,
     - which branches into **user-mode evasion**, **kernel-mode evasion**, and **LSASS protection bypass**,
     - all of which depend on **offset CSVs** and, for kernel features, a **vulnerable driver transport**,
     - with a side pipeline for **Python offset extraction** and symbol downloads.
   - The key trust boundary is between **user mode** and **kernel mode**; almost every advanced feature crosses it via the vulnerable driver primitive.

Main entry points: [`EDRSandblast_StaticLibrary/EDRSandblast_API.c`](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_StaticLibrary/EDRSandblast_API.c) (Core API), [`EDRSandblast/UserlandBypass`](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/UserlandBypass) (Userland bypass), [`EDRSandblast/KernellandBypass`](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/KernellandBypass) (Kernel bypass), [`Offsets`](https://github.com/wavestone-cdt/edrsandblast/tree/master/Offsets) (Offsets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontends["Front ends"]
  node_node_cli["CLI<br/>binary<br/>[EDRSandblast.c]"]
  node_node_lsassdump["LSASS dump<br/>binary"]
  node_node_api["Core API<br/>static lib<br/>[EDRSandblast_API.c]"]
end

subgraph group_grp_core["Core engine"]
  node_node_common["Common layer<br/>native core"]
  node_node_userland["Userland bypass<br/>in-process evasion"]
  node_node_kernelland["Kernel bypass<br/>kernel evasion"]
  node_node_lsass["LSASS bypass<br/>protection bypass"]
  node_node_driverops["Driver ops<br/>transport<br/>[DriverOps.c]"]
  node_node_kmem["Kernel RW<br/>primitive"]
  node_node_peb["PEB / PE<br/>parsing<br/>[PEBBrowse.c]"]
  node_node_syscalls["Syscalls<br/>native stubs<br/>[SW2_Syscalls.c]"]
  node_node_processdump["Process dump<br/>memory ops<br/>[ProcessDump.c]"]
  node_node_fw["Firewall ops<br/>system ops<br/>[FirewallOps.cpp]"]
  node_node_edrcheck["EDR checks<br/>detection<br/>[IsEDRChecks.c]"]
end

subgraph group_grp_offsets["Offsets pipeline"]
  node_node_offsets[("Offsets<br/>version data")]
  node_node_extract["Extractor<br/>python pipeline<br/>[ExtractOffsets.py]"]
  node_node_pdb["Symbol parse<br/>metadata ingest<br/>[PdbParser.h]"]
end

subgraph group_grp_external["External inputs"]
  node_node_vulndriver[("Vulnerable driver<br/>external artifact")]
  node_node_symbolsrv[("Symbol sources<br/>external source")]
  node_node_os{{"Windows kernel<br/>platform boundary"}}
end

node_node_cli -->|"calls"| node_node_api
node_node_lsassdump -->|"calls"| node_node_api
node_node_api -->|"audit"| node_node_edrcheck
node_node_api -->|"mode"| node_node_userland
node_node_api -->|"mode"| node_node_kernelland
node_node_api -->|"mode"| node_node_lsass
node_node_api -->|"mode"| node_node_fw
node_node_userland -->|"inspect"| node_node_peb
node_node_userland -->|"fallback"| node_node_syscalls
node_node_userland -->|"prepare"| node_node_processdump
node_node_kernelland -->|"uses"| node_node_driverops
node_node_driverops -->|"provides"| node_node_kmem
node_node_kernelland -->|"depends"| node_node_offsets
node_node_lsass -->|"writes"| node_node_kmem
node_node_lsass -->|"depends"| node_node_offsets
node_node_offsets -->|"generated by"| node_node_extract
node_node_extract -->|"queries"| node_node_symbolsrv
node_node_extract -->|"parses"| node_node_pdb
node_node_offsets -->|"feeds"| node_node_kernelland
node_node_offsets -->|"feeds"| node_node_lsass
node_node_kmem -->|"requires"| node_node_vulndriver
node_node_api -->|"targets"| node_node_os
node_node_kernelland -->|"crosses"| node_node_os
node_node_userland -->|"runs on"| node_node_os
node_node_common -->|"contains"| node_node_peb
node_node_common -->|"contains"| node_node_pdb
node_node_common -->|"contains"| node_node_processdump

click node_node_cli "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_CLI/EDRSandblast.c"
click node_node_lsassdump "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_LsassDump/EDRSandblast_LsassDump.c"
click node_node_api "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_StaticLibrary/EDRSandblast_API.c"
click node_node_common "https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/Utils"
click node_node_userland "https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/UserlandBypass"
click node_node_kernelland "https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/KernellandBypass"
click node_node_lsass "https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/LSASSProtectionBypass"
click node_node_driverops "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/DriverOps.c"
click node_node_kmem "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Includes/KernelMemoryPrimitives.h"
click node_node_offsets "https://github.com/wavestone-cdt/edrsandblast/tree/master/Offsets"
click node_node_extract "https://github.com/wavestone-cdt/edrsandblast/blob/master/Offsets/ExtractOffsets.py"
click node_node_pdb "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Includes/PdbParser.h"
click node_node_peb "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/PEBBrowse.c"
click node_node_syscalls "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/SW2_Syscalls.c"
click node_node_processdump "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/ProcessDump.c"
click node_node_fw "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/FirewallOps.cpp"
click node_node_edrcheck "https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/IsEDRChecks.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_lsassdump,node_node_api toneBlue
class node_node_common,node_node_userland,node_node_kernelland,node_node_lsass,node_node_driverops,node_node_kmem,node_node_peb,node_node_syscalls,node_node_processdump,node_node_fw,node_node_edrcheck toneAmber
class node_node_offsets,node_node_extract,node_node_pdb toneMint
class node_node_vulndriver,node_node_symbolsrv,node_node_os toneRose
```

## Components

### Front ends

CLI binaries and shared API entrypoints

- [CLI](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_CLI/EDRSandblast.c): binary · Primary command-line entrypoint · `EDRSandblast_CLI/EDRSandblast.c`
- [LSASS dump](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_LsassDump/EDRSandblast_LsassDump.c): binary · Specialized launcher for protected process dumping · `EDRSandblast_LsassDump/EDRSandblast_LsassDump.c`
- [Core API](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast_StaticLibrary/EDRSandblast_API.c): static lib · Shared dispatcher used by all front ends · `EDRSandblast_StaticLibrary/EDRSandblast_API.c`

### Core engine

Reusable native implementation and major bypass subsystems

- [Common layer](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/Utils): native core · Reusable utilities and shared primitives · `EDRSandblast/Utils`
- [Userland bypass](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/UserlandBypass): in-process evasion · Hook discovery, unhooking, and direct syscall paths · `EDRSandblast/UserlandBypass`
- [Kernel bypass](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/KernellandBypass): kernel evasion · Kernel callback removal and ETW TI neutralization · `EDRSandblast/KernellandBypass`
- [LSASS bypass](https://github.com/wavestone-cdt/edrsandblast/tree/master/EDRSandblast/LSASSProtectionBypass): protection bypass · RunAsPPL and Credential Guard-related logic · `EDRSandblast/LSASSProtectionBypass`
- [Driver ops](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/DriverOps.c): transport · Vulnerable-driver abstraction for kernel read/write · `EDRSandblast/Utils/DriverOps.c`
- [Kernel RW](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Includes/KernelMemoryPrimitives.h): primitive · Arbitrary kernel memory read/write and handle cleanup · `EDRSandblast/Includes/KernelMemoryPrimitives.h`
- [PEB / PE](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/PEBBrowse.c): parsing · Process, module, and binary inspection helpers · `EDRSandblast/Utils/PEBBrowse.c`
- [Syscalls](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/SW2_Syscalls.c): native stubs · Direct syscall resolution and stubs · `EDRSandblast/Utils/SW2_Syscalls.c`
- [Process dump](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/ProcessDump.c): memory ops · LSASS and process dumping helpers · `EDRSandblast/Utils/ProcessDump.c`
- [Firewall ops](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/FirewallOps.cpp): system ops · Firewall and service manipulation helpers · `EDRSandblast/Utils/FirewallOps.cpp`
- [EDR checks](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Utils/IsEDRChecks.c): detection · Heuristics for identifying EDR-related processes and drivers · `EDRSandblast/Utils/IsEDRChecks.c`

### Offsets pipeline

Version-specific data and extraction tooling

- [Offsets](https://github.com/wavestone-cdt/edrsandblast/tree/master/Offsets): version data · Build-specific kernel and DLL offsets consumed at runtime · `Offsets`
- [Extractor](https://github.com/wavestone-cdt/edrsandblast/blob/master/Offsets/ExtractOffsets.py): python pipeline · Generates offsets from symbols and Winbindex sources · `Offsets/ExtractOffsets.py`
- [Symbol parse](https://github.com/wavestone-cdt/edrsandblast/blob/master/EDRSandblast/Includes/PdbParser.h): metadata ingest · PDB and symbol parsing used to derive offsets · `EDRSandblast/Includes/PdbParser.h`

### External inputs

Required runtime artifacts and trust-boundary dependencies

- **Vulnerable driver**: external artifact · Signed driver used to obtain kernel primitive
- **Symbol sources**: external source · Microsoft Symbol Server and Winbindex inputs
- **Windows kernel**: platform boundary · Native Windows user-mode and kernel-mode environment

## Connections

- CLI → Core API: calls · Primary CLI dispatch
- LSASS dump → Core API: calls · Specialized launcher dispatch
- Core API → EDR checks: audit · Reconnaissance and validation mode
- Core API → Userland bypass: mode · User-mode evasion paths
- Core API → Kernel bypass: mode · Kernel-mode bypass paths
- Core API → LSASS bypass: mode · Protected-process access features
- Core API → Firewall ops: mode · Firewall or service manipulation actions
- Userland bypass → PEB / PE: inspect · Locate loaded modules and compare memory-backed DLLs
- Userland bypass → Syscalls: fallback · Direct syscall paths when hooks are present
- Userland bypass → Process dump: prepare · Reliable process access for dumping operations
- Kernel bypass → Driver ops: uses · All kernel actions go through driver transport
- Driver ops → Kernel RW: provides · Read/write primitive and handle management
- Kernel bypass → Offsets: depends · Build-specific fields and structure locations
- LSASS bypass → Kernel RW: writes · Adjusts protection or cached-credential state
- LSASS bypass → Offsets: depends · Uses version-specific LSASS and DLL offsets
- Offsets → Extractor: generated by · Offsets are produced by the Python pipeline
- Extractor → Symbol sources: queries · Retrieves symbols and metadata from external sources
- Extractor → Symbol parse: parses · Derives offsets from PDB metadata
- Offsets → Kernel bypass: feeds · Runtime lookup data for kernel bypasses
- Offsets → LSASS bypass: feeds · Runtime lookup data for protection bypasses
- Kernel RW → Vulnerable driver: requires · Kernel primitive depends on a vulnerable signed driver
- Core API → Windows kernel: targets · Native Windows execution boundary
- Kernel bypass → Windows kernel: crosses · User to kernel trust boundary
- Userland bypass → Windows kernel: runs on · In-process user-mode operations
- Common layer → PEB / PE: contains · Core utility layer includes binary and process parsing
- Common layer → Symbol parse: contains · Shared symbol and metadata parsing utilities
- Common layer → Process dump: contains · Shared memory and dump helpers
