How s3cur3th1ssh1t/caro-kann works
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