How franckferman/systematic works
1. Repository purpose
SYSTEMatic is a single-purpose native Windows C tool that escalates an already-elevated Administrator session to NT AUTHORITY\SYSTEM by harvesting and reusing a SYSTEM process token. The core runtime is a small Win32 console program; everything else supports building, packaging, and optional binary transformation.
2. Top-level architecture
The repo splits cleanly into:
- src/ for the executable’s runtime logic
- scripts/ for build-time source/binary rewriting
- .github/workflows/ for CI/release automation
- docs/ for static project documentation and assets
There is no backend service or networked subsystem; the architecture is local, process-centric, and Windows API driven.
3. Execution orchestration
src/main.c is the entrypoint and orchestration layer. It handles CLI parsing, validates that the caller is an administrator, enables required privileges, resolves the target command, and coordinates token discovery plus process launch. Conceptually, it is the controller that binds together the token and process subsystems.
4. Token subsystem
src/token.c and src/token.h implement the privilege and token workflow:
- enabling SeDebugPrivilege
- enumerating processes
- finding candidate SYSTEM processes
- opening process tokens
- validating that a token belongs to SYSTEM
- duplicating the token into a primary token
This is the main security-sensitive boundary in the repo: it converts “Administrator on the machine” into “usable SYSTEM token for process creation.”
5. Process discovery strategy
Token discovery is intentionally layered. The code first prioritizes stable SYSTEM-owned processes such as services.exe, winlogon.exe, and lsass.exe, then falls back to full process enumeration if needed. This is a runtime selection boundary: fast-path lookup first, broad scan second, with token validation deciding whether a candidate is accepted.
6. Process creation subsystem
src/process.c and src/process.h encapsulate spawning the final SYSTEM process. The primary path uses CreateProcessWithTokenW with the duplicated SYSTEM token. If that fails, the code can fall back to parent-process spoofing via extended startup attributes and CreateProcessW. This subsystem is responsible for taking a validated token and turning it into a live child process.
7. Error handling and diagnostics
src/error.c and src/error.h provide shared Win32 error formatting, likely centered around FormatMessage-based reporting. This keeps user-facing diagnostics out of the control flow modules and gives the application a consistent error boundary for token, privilege, and process-launch failures.
8. Shared platform headers
src/common.h centralizes Windows includes and common definitions used across modules. This is a small but important architectural boundary: it reduces header churn and keeps the rest of the codebase focused on behavior rather than repetitive Win32 setup.
9. Build-time transformation pipeline
The Makefile and scripts/ directory implement several output profiles rather than one fixed build:
- standard MSVC or MinGW builds
- an “evasive” build that rewrites imports to runtime resolution
- a “polymorphic” build that patches PE metadata for unique hashes
- a combined “full” build that applies both
These scripts do not affect runtime behavior directly; they alter the binary’s static shape and import surface before release.
10. CI, release, and documentation
.github/workflows/release.yml and static.yml automate release and site/docs publication. docs/index.html and the graphics under docs/github/graphical_resources/ provide project presentation and static hosting content. These are support surfaces around the binary, not part of the runtime path.
11. External dependencies and runtime boundary
The executable depends on standard Windows kernel/user-mode APIs only; there is no third-party runtime or service dependency. The only “external” requirement is the local Windows security context: the tool assumes it is run from an elevated Administrator session on Windows and that the target SYSTEM process can be queried.
12. End-to-end data flow
The overall flow is: command-line input → admin/privilege validation → SYSTEM process enumeration → token acquisition and duplication → command resolution → process creation. The main architectural boundary is between “finding a valid SYSTEM token” and “using that token to launch a new process,” with error handling and fallback launch logic keeping the path robust.
Main entry points: main.c Main · Makefile Makefile · process.c Process · token.c Token
Components 12
Runtime
Windows console executable and supporting modules
- Main · CLI orchestration, privilege checks, and launch flow
src/main.c - Token · SeDebugPrivilege, SYSTEM token discovery, validation, and duplication
src/token.c - Process · CreateProcessWithTokenW path and fallback parent-spoofed launch
src/process.c - Errors · Shared Win32 error formatting and reporting
src/error.c - Common · Central Windows includes and common definitions
src/common.h
Build
Makefile and source/binary rewriting pipeline
- Makefile · Top-level build targets and release profiles
Makefile - Evasive build · Rewrites imports for runtime resolution
scripts/make_evasive.py - Poly patch · Patches PE metadata for polymorphic binaries
scripts/poly_patch.py
Automation
CI and release workflows
- Release CI · Build and release automation
.github/workflows/release.yml - Static CI · Static site and docs publication
.github/workflows/static.yml
Connections 15
- Main → Common: uses · Entry point relies on shared Win32 definitions
- Main → Errors: reports · Main flow surfaces user-facing failures through shared diagnostics
- Main → Token: discovers token · Coordinates privilege enabling and SYSTEM token harvesting
- Main → Process: launches · Hands validated token and target command to process creation
- Token → Errors: reports · Token and privilege failures are formatted consistently
- Process → Errors: reports · Launch failures flow through shared error handling
- Process → Token: consumes token · Process creation uses the duplicated SYSTEM token
- Makefile → Main: builds · Compiles the runtime executable
- Makefile → Evasive build: invokes · Optional evasive profile rewrites imports
- Makefile → Poly patch: invokes · Optional polymorphic profile patches PE metadata
- Evasive build → Poly patch: can compose · Release profiles can combine both rewrite stages
- Release CI → Makefile: runs · CI drives the build and packaging flow
- Static CI → Docs site: publishes · Workflow deploys the static docs site
- Docs site → Assets: references · Docs page uses graphical resources
- Release CI → Docs site: includes · Release surface may package documentation artifacts