# s3cur3th1ssh1t/caro-kann architecture

> Architecture diagram of the GitHub repository s3cur3th1ssh1t/caro-kann, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s3cur3th1ssh1t/caro-kann
- Repository: https://github.com/s3cur3th1ssh1t/caro-kann

## Overview

##### Project type and purpose
- This is a security PoC (“Caro Kann”) for encrypted shellcode injection on Windows.
- It demonstrates how to inject a known-malicious payload in encrypted form into an RW section of a remote process, deploy a small custom loader in an RX section, and then at runtime decrypt and execute the real payload while evading both user-land and kernel-land memory scans.

##### File structure
Top-level files and dirs:
- adjuststack.asm / adjuststack_as.asm: assembly stubs to fix the stack before jumping into payload.
- APIResolve.h / ApiResolve.c: dynamic Windows API resolution routines.
- DecryptProtect.c: C code that changes section protection (RW→RX) and runs decryption.
- Encrypt.cpp: simple XOR encrypter for any payload.
- extract.c / extract.sh: utilities to extract the .text section bytes from compiled stubs.
- CaroKann.nim: the main Nim PoC, ties everything together and calls the injection logic.
- makefile: orchestrates mingw build (assemble, compile, link, extract).

##### README for insights
- Built with mingw-w64 + Nim + nasm + gcc.
- Workflow: compile stubs → extract shellcode → encrypt a payload → embed in Nim → compile CaroKann.exe → run against a target process.
- Runtime steps: allocate RW in target, write encrypted payload, allocate RX in target for loader, create remote thread into loader → loader sleeps, decrypts payload, changes RW→RX, jumps to payload.

##### Main components
a. Development / Build Environment
- Tools: nasm/`as`, gcc/ld, mingw, Nim compiler (`nim c`), extract tool, encrypt.exe
- Inputs: known malicious payload (payload.bin) → encrypt.exe → encrypted.bin
- Outputs: custom loader shellcode (.bin), encrypted payload (.bin), CaroKann.exe

b. CaroKann PoC (Runtime)
- Injector process (CaroKann.exe)
- Modules:
- API Resolver
- Memory operations (VirtualAllocEx, WriteProcessMemory, VirtualProtectEx)
- Remote Thread Creation (NtCreateThreadEx wrapper)

c. Target Process
- Allocated sections:
- RW section (encrypted payload)
- RX section (custom loader stub)

d. Loader Stub (assembly + DecryptProtect) inside target
- Sleep (delay)
- Decrypt payload in-place
- Change RW→RX
- JMP to decrypted payload

e. Known-malicious payload (final execution)

f. Optional Kernel / EDR scanner interaction (showing evasion)

##### Architectural patterns & design principles
- Single-executable PoC mixing C, Nim, and ASM – modular separation of concerns
- Dynamic API resolution (no static imports)
- Split-section approach: RW for stealth payload, RX for safe loader
- Delay + in-memory decryption for EDR evasion

##### Technologies/Frameworks
- Nim (winim, ptr_math)
- mingw-w64 toolchain (gcc, ld, as)
- NASM (assembly)
- Standard Windows API syscalls

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Development Host (Build-Time)"
        EncryptTool["Encryptor (Encrypt.cpp)"]:::build
        Extractor["Extractor (extract.c, extract.sh)"]:::build
        ASMStubs["Assembly Stubs (adjuststack.asm, adjuststack_as.asm)"]:::build
        APIModule["API Resolver (APIResolve.h, ApiResolve.c)"]:::build
        DecryptProtect["Section Protect & Decrypt (DecryptProtect.c)"]:::build
        messageenc["Encrypted Payload (messageenc.bin)"]:::artifact
        loaderbin["Loader Shellcode (loader.bin)"]:::artifact
        Compiler["Nim Compiler (CaroKann.nim)"]:::build
        Makefile["Makefile"]:::build

        EncryptTool -->|"encrypt payload.bin"| messageenc
        Extractor -->|"extract .text"| loaderbin
        ASMStubs --> loaderbin
        Makefile --> Compiler
        APIModule --> Compiler
        DecryptProtect --> Compiler
        messageenc --> Compiler
        loaderbin --> Compiler
        Compiler -->|"compile & link"| injector["Injector (CaroKann.exe)"]:::runtime
    end

    subgraph "Runtime (Injector)"
        injector -->|"VirtualAllocEx(RW)\nWriteProcessMemory"| TargetRW["Target Process RW Section"]:::target
        injector -->|"VirtualAllocEx(RX)\nWriteProcessMemory"| TargetRX["Target Process RX Section"]:::target
        injector -->|"CreateRemoteThread"| LoaderStart["Loader Stub Entry"]:::loader
    end

    subgraph "Inside Target Process"
        subgraph "Loader Stub"
            Sleep["Sleep(delay)"]:::loader
            Decrypt["Decrypt payload in-place"]:::loader
            Protect["VirtualProtectEx(RW→RX)"]:::loader
            JMP["JMP to payload"]:::loader
        end
        Payload["Malicious Payload Execution"]:::payload

        LoaderStart --> Sleep --> Decrypt --> Protect --> JMP --> Payload
    end

    %% Click Events
    click EncryptTool "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/Encrypt.cpp"
    click Extractor "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/extract.c"
    click Extractor "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/extract.sh"
    click ASMStubs "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/adjuststack.asm"
    click ASMStubs "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/adjuststack_as.asm"
    click APIModule "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/APIResolve.h"
    click APIModule "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/ApiResolve.c"
    click DecryptProtect "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/DecryptProtect.c"
    click Compiler "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/CaroKann.nim"
    click Makefile "https://github.com/s3cur3th1ssh1t/caro-kann/tree/main/makefile"
    click messageenc "https://github.com/s3cur3th1ssh1t/caro-kann/blob/main/messageenc.bin"
    click images "https://github.com/s3cur3th1ssh1t/caro-kann/tree/main/images/"

    %% Styles
    classDef build fill:#cfe2f3,stroke:#000,stroke-width:1px;
    classDef artifact fill:#9fc5e8,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
    classDef runtime fill:#d9ead3,stroke:#000,stroke-width:1px;
    classDef target fill:#fce5cd,stroke:#000,stroke-width:1px;
    classDef loader fill:#fff2cc,stroke:#000,stroke-width:1px;
    classDef payload fill:#f4cccc,stroke:#000,stroke-width:1px;
```
