How hasherezade/pe-sieve works
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: scanner.h Scanner base · pe_sieve.cpp Engine core · scan_report.h Scan report · pe_sieve_api.h Public API
Components 18
Front ends
CLI, DLL boundary, and external bindings.
- CLI entry · Standalone command-line entry point.
main.cpp - DLL entry · DLL boundary for embedded use.
dll_main.cpp - Public API · Exported scanning API and return codes/types.
include/pe_sieve_api.h
Core engine
Orchestration, configuration, and process access.
- API impl · Top-level orchestration behind the public API.
pe_sieve_api.cpp - Engine core · Coordinates one-process scan workflow end to end.
pe_sieve.cpp - Options model · Command-line and runtime parameter definitions.
params.h - Param info · Active-configuration description and printing helpers.
params_info/pe_sieve_params_info.cpp - Process utils · Process privileges, modules, threads, paths, and minidumps.
utils/process_util.cpp
Detection
Specialized scanners and heuristics over target memory.
- Scanner base · Shared scanner interfaces and process-level context.
scanners/scanner.h - Module model · Module cache, scanned modules, and per-module data.
scanners/module_data.h - Code scan · Checks code and patched regions for tampering.
scanners/code_scanner.cpp - Header scan · Validates PE headers against expected structure.
scanners/headers_scanner.cpp - IAT scan · Inspects imports and hook-related targets.
scanners/iat_scanner.cpp - Memory scan · Analyzes memory pages, mappings, and workingset evidence.
scanners/mapping_scanner.cpp - Thread scan · Examines threads as a signal for injected activity.
scanners/thread_scanner.cpp
Output
Reporting, dumping, and reconstruction.
- Scan report · Aggregates per-module and per-process findings.
scanners/scan_report.h - Postprocess · Formats results, dumps artifacts, and reconstructs PE images.
postprocessors/report_formatter.cpp
Dependencies
Vendored PE utilities used by the reconstruction path.
- libpeconv · Vendored PE processing and reconstruction primitives.
libpeconv
Connections 21
- 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.