# arty3/stack-obfuscator architecture

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

- Interactive diagram: https://gitdiagram.com/arty3/stack-obfuscator
- Repository: https://github.com/arty3/stack-obfuscator

## Overview

Stack Obfuscator is a header-only C++ library for protecting function return addresses and proxying external calls across Windows and Linux, including Windows kernel mode. The principal workflow is application code invoking a protection macro, which applies return-address obfuscation or dispatches a call through a calling-convention-aware proxy. The header also contains thread-state and key-generation logic. The README documents broader platform and security capabilities; because only excerpts of the header were provided, some internal links are omitted rather than inferred.

Main entry points: [`include/Stack-Obfuscator.hpp`](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp) (Protection macros)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_macros["Protection macros"]
end

subgraph group_protection["Protection Runtime"]
  node_ra_guard["Return address guard"]
  node_call_proxy["Safe call proxy"]
  node_thread_state["Thread state"]
  node_key_generation["Key generation"]
end

subgraph group_platform["Platform Support"]
  node_abi_dispatch["ABI dispatch"]
end

node_app(("Application code"))
node_external_target(("External function"))

node_app -->|"invokes"| node_macros
node_macros -->|"protects return address"| node_ra_guard
node_macros -->|"creates SafeCall"| node_call_proxy
node_call_proxy -->|"selects convention"| node_abi_dispatch
node_call_proxy -->|"invokes target"| node_external_target
node_ra_guard -->|"sets status"| node_thread_state

click node_macros "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"
click node_ra_guard "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"
click node_call_proxy "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"
click node_thread_state "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"
click node_key_generation "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"
click node_abi_dispatch "https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp"

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_macros toneBlue
class node_ra_guard,node_call_proxy,node_thread_state,node_key_generation toneAmber
class node_abi_dispatch toneMint
class node_app,node_external_target toneIndigo
```

## Components

### Public API

- [Protection macros](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`

### Protection Runtime

- [Return address guard](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`
- [Safe call proxy](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`
- [Thread state](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`
- [Key generation](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`

### Platform Support

- [ABI dispatch](https://github.com/arty3/stack-obfuscator/blob/main/include/Stack-Obfuscator.hpp): `include/Stack-Obfuscator.hpp`

### Other components

- **Application code**
- **External function**

## Connections

- Application code → Protection macros: invokes (evidence: `README.md`)
- Protection macros → Return address guard: protects return address (evidence: `README.md`)
- Protection macros → Safe call proxy: creates SafeCall (evidence: `include/Stack-Obfuscator.hpp`)
- Safe call proxy → ABI dispatch: selects convention (evidence: `include/Stack-Obfuscator.hpp`)
- Safe call proxy → External function: invokes target (evidence: `README.md`)
- Return address guard → Thread state: sets status (evidence: `include/Stack-Obfuscator.hpp`)
