# hasherezade/pe-sieve architecture

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

- Interactive diagram: https://gitdiagram.com/hasherezade/pe-sieve
- Repository: https://github.com/hasherezade/pe-sieve

## Overview

1. **Project purpose and shape**
   - PE-sieve is a Windows C++ security tool that inspects a single running process for in-memory tampering: injected/replaced PE images, shellcode, hooks, and patched code.
   - The repository builds into either a **CLI EXE** or a **DLL API library**, so the architecture has both a command-line front end and an embeddable engine.

2. **Top-level execution entry points**
   - `main.cpp` is the EXE entry point.
   - `dll_main.cpp` plus the headers in `include/` expose the DLL-facing boundary.
   - `pe_sieve.cpp`, `pe_sieve.h`, and `pe_sieve_api.cpp` appear to host the core orchestration and exported API surface.

3. **Core engine boundary**
   - The engine is centered around a scan of one target process at a time.
   - It coordinates: parameter parsing, process access, module enumeration, scanning, report assembly, and optional dumping/reconstruction.
   - The public API lives in `include/pe_sieve_api.h`, with return codes and data types split into `include/pe_sieve_return_codes.h` and `include/pe_sieve_types.h`.

4. **Input/configuration subsystem**
   - `params.h`, `params_info/`, and `paramkit/` define the command-line/options model.
   - `params_info/pe_sieve_params_info.*` and `params_info/params_dump.*` support describing and printing the active configuration.
   - This subsystem is the primary boundary between user intent and the scanning engine.

5. **Process and Windows interop utilities**
   - `utils/` contains the OS-facing helper layer: process privileges, process utilities, module enumeration, thread utilities, path conversion, string/format helpers, minidump support, and syscall extraction.
   - These helpers isolate Windows-specific APIs from the scanner logic and are used across the engine for target-process access and metadata collection.

6. **Scan pipeline and subsystem layout**
   - The `scanners/` directory is the main detection pipeline.
   - It includes specialized scanners for headers, code, imports, memory pages, workingset data, threads, mappings, artifacts, and patches.
   - The architecture is modular: each scanner focuses on one evidence source in the target process, then contributes findings to a shared report model.

7. **Module-centric scanning model**
   - Files such as `module_cache.*`, `module_data.*`, `scanned_modules.*`, `module_scan_report.h`, and `module_scanner.h` indicate that the scan is organized around discovered modules and their memory regions.
   - `process_details.h` and `process_feature_scanner.h` suggest the engine gathers process-wide context first, then applies feature-specific checks per module or memory page.
   - This is the key data boundary: “target process state” becomes “structured findings per module/page.”

8. **Detection logic and heuristics**
   - `patch_analyzer.*`, `patch_list.*`, `hook_targets_resolver.*`, and the scanners for `code`, `iat`, `headers`, and `workingset` show that PE-sieve compares expected on-disk structure against in-memory reality.
   - `stats/` adds entropy and statistical helpers, likely used to characterize suspicious memory regions or shellcode-like data.
   - Detection is therefore evidence-driven rather than signature-only.

9. **Report model and result aggregation**
   - `scanners/scan_report.*` and `scanners/module_scan_report.h` collect per-module/per-process findings.
   - This report is the primary handoff from scanning to downstream actions.
   - `pe_sieve_report.h` defines the higher-level report contract used by the engine and output layers.

10. **Post-processing and dumping**
   - `postprocessors/` handles what happens after scanning: formatting results, dumping artifacts, reconstructing PE images, and reconstructing import tables.
   - `pe_reconstructor.*`, `pe_buffer.*`, and `imp_rec/` indicate the tool can recover a usable PE from memory when corruption or unpacking is detected.
   - `dump_report.*`, `results_dumper.*`, and `report_formatter.*` form the reporting/output boundary.

11. **External library dependency**
   - The repository vendors `libpeconv/` as a submodule dependency.
   - This library is important because it likely provides PE reconstruction, validation, and conversion primitives used by the dump/rebuild path.
   - Architecturally, PE-sieve builds its own detection pipeline on top of this PE-processing core.

12. **Bindings and integration surface**
   - `bindings/python/` exposes a Python wrapper/demo around the DLL/API.
   - This shows the engine is designed for reuse outside the standalone executable, with the DLL boundary as the stable integration point.
   - The Python layer is a consumer, not a separate engine.

13. **Build and packaging structure**
   - The project uses CMake (`CMakeLists.txt`) as the main build system, with Windows packaging assets like `.rc`, `.manifest`, `.def`, and version headers.
   - CI files (`.github/workflows/main.yml`, `.appveyor.yml`) indicate automated Windows builds.
   - `mingw_build.sh` suggests MinGW support in addition to the native Windows toolchain.

14. **How data flows through the system**
   - User input/configuration enters through CLI or DLL API.
   - The engine obtains process privileges and enumerates target-process modules/memory.
   - Scanner modules analyze code, imports, headers, threads, memory pages, and mappings for anomalies.
   - Findings are aggregated into scan reports.
   - Postprocessors optionally dump, format, and reconstruct suspicious artifacts for offline analysis.

15. **What to draw as the main architectural boundaries**
   - Front ends: EXE, DLL API, Python binding.
   - Core engine: orchestration, process access, and scan coordination.
   - Detection layer: specialized scanners and heuristics.
   - Output layer: reports, dumps, reconstruction.
   - Dependency boundary: external PE utilities via `libpeconv`.

Main entry points: [`scanners/scanner.h`](https://github.com/hasherezade/pe-sieve/blob/master/scanners/scanner.h) (Scanner base), [`pe_sieve.cpp`](https://github.com/hasherezade/pe-sieve/blob/master/pe_sieve.cpp) (Engine core), [`scanners/scan_report.h`](https://github.com/hasherezade/pe-sieve/blob/master/scanners/scan_report.h) (Scan report), [`include/pe_sieve_api.h`](https://github.com/hasherezade/pe-sieve/blob/master/include/pe_sieve_api.h) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Front ends"]
  node_main["CLI entry<br/>exe entry<br/>[main.cpp]"]
  node_dll_main["DLL entry<br/>[dll_main.cpp]"]
  node_api["Public API<br/>api surface<br/>[pe_sieve_api.h]"]
end

subgraph group_engine["Core engine"]
  node_api_impl["API impl<br/>[pe_sieve_api.cpp]"]
  node_core["Engine core<br/>orchestrator<br/>[pe_sieve.cpp]"]
  node_params["Options model<br/>config<br/>[params.h]"]
  node_params_info["Param info<br/>config docs"]
  node_proc_utils["Process utils<br/>win interop<br/>[process_util.cpp]"]
end

subgraph group_detection["Detection"]
  node_scanner_base["Scanner base<br/>scan framework<br/>[scanner.h]"]
  node_module_model["Module model<br/>scan model<br/>[module_data.h]"]
  node_code_scan["Code scan<br/>scanner<br/>[code_scanner.cpp]"]
  node_header_scan["Header scan<br/>scanner"]
  node_iat_scan["IAT scan<br/>scanner<br/>[iat_scanner.cpp]"]
  node_memory_scan["Memory scan<br/>scanner"]
  node_thread_scan["Thread scan<br/>scanner<br/>[thread_scanner.cpp]"]
end

subgraph group_output["Output"]
  node_report["Scan report<br/>result model<br/>[scan_report.h]"]
  node_post["Postprocess<br/>output stage"]
end

subgraph group_deps["Dependencies"]
  node_peconv["libpeconv<br/>pe utils"]
end

node_main -->|"runs"| node_core
node_dll_main -->|"exports"| node_api
node_api -->|"implemented by"| node_api_impl
node_api_impl -->|"delegates"| node_core
node_core -->|"reads"| node_params
node_core -->|"describes"| node_params_info
node_core -->|"uses"| node_proc_utils
node_core -->|"coordinates"| node_scanner_base
node_scanner_base -->|"organizes"| node_module_model
node_scanner_base -->|"dispatches"| node_code_scan
node_scanner_base -->|"dispatches"| node_header_scan
node_scanner_base -->|"dispatches"| node_iat_scan
node_scanner_base -->|"dispatches"| node_memory_scan
node_scanner_base -->|"dispatches"| node_thread_scan
node_code_scan -->|"contributes"| node_report
node_header_scan -->|"contributes"| node_report
node_iat_scan -->|"contributes"| node_report
node_memory_scan -->|"contributes"| node_report
node_thread_scan -->|"contributes"| node_report
node_report -->|"feeds"| node_post
node_post -->|"uses"| node_peconv

click node_main "https://github.com/hasherezade/pe-sieve/blob/master/main.cpp"
click node_dll_main "https://github.com/hasherezade/pe-sieve/blob/master/dll_main.cpp"
click node_api "https://github.com/hasherezade/pe-sieve/blob/master/include/pe_sieve_api.h"
click node_api_impl "https://github.com/hasherezade/pe-sieve/blob/master/pe_sieve_api.cpp"
click node_core "https://github.com/hasherezade/pe-sieve/blob/master/pe_sieve.cpp"
click node_params "https://github.com/hasherezade/pe-sieve/blob/master/params.h"
click node_params_info "https://github.com/hasherezade/pe-sieve/blob/master/params_info/pe_sieve_params_info.cpp"
click node_proc_utils "https://github.com/hasherezade/pe-sieve/blob/master/utils/process_util.cpp"
click node_scanner_base "https://github.com/hasherezade/pe-sieve/blob/master/scanners/scanner.h"
click node_module_model "https://github.com/hasherezade/pe-sieve/blob/master/scanners/module_data.h"
click node_code_scan "https://github.com/hasherezade/pe-sieve/blob/master/scanners/code_scanner.cpp"
click node_header_scan "https://github.com/hasherezade/pe-sieve/blob/master/scanners/headers_scanner.cpp"
click node_iat_scan "https://github.com/hasherezade/pe-sieve/blob/master/scanners/iat_scanner.cpp"
click node_memory_scan "https://github.com/hasherezade/pe-sieve/blob/master/scanners/mapping_scanner.cpp"
click node_thread_scan "https://github.com/hasherezade/pe-sieve/blob/master/scanners/thread_scanner.cpp"
click node_report "https://github.com/hasherezade/pe-sieve/blob/master/scanners/scan_report.h"
click node_post "https://github.com/hasherezade/pe-sieve/blob/master/postprocessors/report_formatter.cpp"
click node_peconv "https://github.com/hasherezade/pe-sieve/tree/master/libpeconv"

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_main,node_dll_main,node_api toneBlue
class node_api_impl,node_core,node_params,node_params_info,node_proc_utils toneAmber
class node_scanner_base,node_module_model,node_code_scan,node_header_scan,node_iat_scan,node_memory_scan,node_thread_scan toneMint
class node_report,node_post toneRose
class node_peconv toneIndigo
```

## Components

### Front ends

CLI, DLL boundary, and external bindings.

- [CLI entry](https://github.com/hasherezade/pe-sieve/blob/master/main.cpp): exe entry · Standalone command-line entry point. · `main.cpp`
- [DLL entry](https://github.com/hasherezade/pe-sieve/blob/master/dll_main.cpp): dll entry · DLL boundary for embedded use. · `dll_main.cpp`
- [Public API](https://github.com/hasherezade/pe-sieve/blob/master/include/pe_sieve_api.h): api surface · Exported scanning API and return codes/types. · `include/pe_sieve_api.h`

### Core engine

Orchestration, configuration, and process access.

- [API impl](https://github.com/hasherezade/pe-sieve/blob/master/pe_sieve_api.cpp): api impl · Top-level orchestration behind the public API. · `pe_sieve_api.cpp`
- [Engine core](https://github.com/hasherezade/pe-sieve/blob/master/pe_sieve.cpp): orchestrator · Coordinates one-process scan workflow end to end. · `pe_sieve.cpp`
- [Options model](https://github.com/hasherezade/pe-sieve/blob/master/params.h): config · Command-line and runtime parameter definitions. · `params.h`
- [Param info](https://github.com/hasherezade/pe-sieve/blob/master/params_info/pe_sieve_params_info.cpp): config docs · Active-configuration description and printing helpers. · `params_info/pe_sieve_params_info.cpp`
- [Process utils](https://github.com/hasherezade/pe-sieve/blob/master/utils/process_util.cpp): win interop · Process privileges, modules, threads, paths, and minidumps. · `utils/process_util.cpp`

### Detection

Specialized scanners and heuristics over target memory.

- [Scanner base](https://github.com/hasherezade/pe-sieve/blob/master/scanners/scanner.h): scan framework · Shared scanner interfaces and process-level context. · `scanners/scanner.h`
- [Module model](https://github.com/hasherezade/pe-sieve/blob/master/scanners/module_data.h): scan model · Module cache, scanned modules, and per-module data. · `scanners/module_data.h`
- [Code scan](https://github.com/hasherezade/pe-sieve/blob/master/scanners/code_scanner.cpp): scanner · Checks code and patched regions for tampering. · `scanners/code_scanner.cpp`
- [Header scan](https://github.com/hasherezade/pe-sieve/blob/master/scanners/headers_scanner.cpp): scanner · Validates PE headers against expected structure. · `scanners/headers_scanner.cpp`
- [IAT scan](https://github.com/hasherezade/pe-sieve/blob/master/scanners/iat_scanner.cpp): scanner · Inspects imports and hook-related targets. · `scanners/iat_scanner.cpp`
- [Memory scan](https://github.com/hasherezade/pe-sieve/blob/master/scanners/mapping_scanner.cpp): scanner · Analyzes memory pages, mappings, and workingset evidence. · `scanners/mapping_scanner.cpp`
- [Thread scan](https://github.com/hasherezade/pe-sieve/blob/master/scanners/thread_scanner.cpp): scanner · Examines threads as a signal for injected activity. · `scanners/thread_scanner.cpp`

### Output

Reporting, dumping, and reconstruction.

- [Scan report](https://github.com/hasherezade/pe-sieve/blob/master/scanners/scan_report.h): result model · Aggregates per-module and per-process findings. · `scanners/scan_report.h`
- [Postprocess](https://github.com/hasherezade/pe-sieve/blob/master/postprocessors/report_formatter.cpp): output stage · Formats results, dumps artifacts, and reconstructs PE images. · `postprocessors/report_formatter.cpp`

### Dependencies

Vendored PE utilities used by the reconstruction path.

- [libpeconv](https://github.com/hasherezade/pe-sieve/tree/master/libpeconv): pe utils · Vendored PE processing and reconstruction primitives. · `libpeconv`

## Connections

- CLI entry → Engine core: runs · CLI invokes the scanning engine.
- DLL entry → Public API: exports · DLL exposes the public API boundary.
- Public API → API impl: implemented by · Declarations are realized by the API implementation.
- API impl → Engine core: delegates · API entry forwards work into the engine core.
- Engine core → Options model: reads · Engine consumes runtime options.
- Engine core → Param info: describes · Engine can render configuration details.
- Engine core → Process utils: uses · Engine relies on Windows/process helpers.
- Engine core → Scanner base: coordinates · Core orchestrates the scanning framework.
- Scanner base → Module model: organizes · Scanning is organized around discovered modules and regions.
- Scanner base → Code scan: dispatches · Shared framework runs code analysis.
- Scanner base → Header scan: dispatches · Shared framework runs header checks.
- Scanner base → IAT scan: dispatches · Shared framework runs import analysis.
- Scanner base → Memory scan: dispatches · Shared framework runs memory and mapping checks.
- Scanner base → Thread scan: dispatches · Shared framework runs thread analysis.
- Code scan → Scan report: contributes · Scanner findings are accumulated into the report.
- Header scan → Scan report: contributes · Scanner findings are accumulated into the report.
- IAT scan → Scan report: contributes · Scanner findings are accumulated into the report.
- Memory scan → Scan report: contributes · Scanner findings are accumulated into the report.
- Thread scan → Scan report: contributes · Scanner findings are accumulated into the report.
- Scan report → Postprocess: feeds · Report drives dumping, formatting, and reconstruction.
- Postprocess → libpeconv: uses · Reconstruction path depends on vendored PE utilities.
