# franckferman/systematic architecture

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

- Interactive diagram: https://gitdiagram.com/franckferman/systematic
- Repository: https://github.com/franckferman/systematic

## Overview

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: [`src/main.c`](https://github.com/franckferman/systematic/blob/stable/src/main.c) (Main), [`Makefile`](https://github.com/franckferman/systematic/tree/stable/Makefile) (Makefile), [`src/process.c`](https://github.com/franckferman/systematic/blob/stable/src/process.c) (Process), [`src/token.c`](https://github.com/franckferman/systematic/blob/stable/src/token.c) (Token)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_main["Main<br/>entrypoint<br/>[main.c]"]
  node_src_token["Token<br/>security<br/>[token.c]"]
  node_src_process["Process<br/>spawn<br/>[process.c]"]
  node_src_error["Errors<br/>diagnostics<br/>[error.c]"]
  node_src_common["Common<br/>shared headers<br/>[common.h]"]
end

subgraph group_build["Build"]
  node_makefile["Makefile<br/>build orchestration"]
  node_make_evasive["Evasive build<br/>rewrite script<br/>[make_evasive.py]"]
  node_poly_patch["Poly patch<br/>rewrite script<br/>[poly_patch.py]"]
end

subgraph group_automation["Automation"]
  node_release_wf["Release CI<br/>workflow<br/>[release.yml]"]
  node_static_wf["Static CI<br/>workflow<br/>[static.yml]"]
end

subgraph group_docs["Docs"]
  node_docs_index["Docs site<br/>documentation<br/>[index.html]"]
  node_docs_assets["Assets<br/>graphics"]
end

node_src_main -->|"uses"| node_src_common
node_src_main -->|"reports"| node_src_error
node_src_main -->|"discovers token"| node_src_token
node_src_main -->|"launches"| node_src_process
node_src_token -->|"reports"| node_src_error
node_src_process -->|"reports"| node_src_error
node_src_process -->|"consumes token"| node_src_token
node_makefile -->|"builds"| node_src_main
node_makefile -->|"invokes"| node_make_evasive
node_makefile -->|"invokes"| node_poly_patch
node_make_evasive -.->|"can compose"| node_poly_patch
node_release_wf -->|"runs"| node_makefile
node_static_wf -->|"publishes"| node_docs_index
node_docs_index -->|"references"| node_docs_assets
node_release_wf -.->|"includes"| node_docs_index

click node_src_main "https://github.com/franckferman/systematic/blob/stable/src/main.c"
click node_src_token "https://github.com/franckferman/systematic/blob/stable/src/token.c"
click node_src_process "https://github.com/franckferman/systematic/blob/stable/src/process.c"
click node_src_error "https://github.com/franckferman/systematic/blob/stable/src/error.c"
click node_src_common "https://github.com/franckferman/systematic/blob/stable/src/common.h"
click node_makefile "https://github.com/franckferman/systematic/tree/stable/Makefile"
click node_make_evasive "https://github.com/franckferman/systematic/blob/stable/scripts/make_evasive.py"
click node_poly_patch "https://github.com/franckferman/systematic/blob/stable/scripts/poly_patch.py"
click node_release_wf "https://github.com/franckferman/systematic/blob/stable/.github/workflows/release.yml"
click node_static_wf "https://github.com/franckferman/systematic/blob/stable/.github/workflows/static.yml"
click node_docs_index "https://github.com/franckferman/systematic/blob/stable/docs/index.html"
click node_docs_assets "https://github.com/franckferman/systematic/tree/stable/docs/github/graphical_resources"

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_src_main,node_src_token,node_src_process,node_src_error,node_src_common toneBlue
class node_makefile,node_make_evasive,node_poly_patch toneAmber
class node_release_wf,node_static_wf toneMint
class node_docs_index,node_docs_assets toneRose
```

## Components

### Runtime

Windows console executable and supporting modules

- [Main](https://github.com/franckferman/systematic/blob/stable/src/main.c): entrypoint · CLI orchestration, privilege checks, and launch flow · `src/main.c`
- [Token](https://github.com/franckferman/systematic/blob/stable/src/token.c): security · SeDebugPrivilege, SYSTEM token discovery, validation, and duplication · `src/token.c`
- [Process](https://github.com/franckferman/systematic/blob/stable/src/process.c): spawn · CreateProcessWithTokenW path and fallback parent-spoofed launch · `src/process.c`
- [Errors](https://github.com/franckferman/systematic/blob/stable/src/error.c): diagnostics · Shared Win32 error formatting and reporting · `src/error.c`
- [Common](https://github.com/franckferman/systematic/blob/stable/src/common.h): shared headers · Central Windows includes and common definitions · `src/common.h`

### Build

Makefile and source/binary rewriting pipeline

- [Makefile](https://github.com/franckferman/systematic/tree/stable/Makefile): build orchestration · Top-level build targets and release profiles · `Makefile`
- [Evasive build](https://github.com/franckferman/systematic/blob/stable/scripts/make_evasive.py): rewrite script · Rewrites imports for runtime resolution · `scripts/make_evasive.py`
- [Poly patch](https://github.com/franckferman/systematic/blob/stable/scripts/poly_patch.py): rewrite script · Patches PE metadata for polymorphic binaries · `scripts/poly_patch.py`

### Automation

CI and release workflows

- [Release CI](https://github.com/franckferman/systematic/blob/stable/.github/workflows/release.yml): workflow · Build and release automation · `.github/workflows/release.yml`
- [Static CI](https://github.com/franckferman/systematic/blob/stable/.github/workflows/static.yml): workflow · Static site and docs publication · `.github/workflows/static.yml`

### Docs

Static documentation and assets

- [Docs site](https://github.com/franckferman/systematic/blob/stable/docs/index.html): documentation · Project landing page and published content · `docs/index.html`
- [Assets](https://github.com/franckferman/systematic/tree/stable/docs/github/graphical_resources): graphics · Static graphical resources for the docs site · `docs/github/graphical_resources`

## Connections

- 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
