# nvisosecurity/cobaltwhispers architecture

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

- Interactive diagram: https://gitdiagram.com/nvisosecurity/cobaltwhispers
- Repository: https://github.com/nvisosecurity/cobaltwhispers

## Overview

##### Project type and purpose
- CobaltWhispers is an open-source Red Team tool (an Aggressor script plus Beacon Object Files) for the Cobalt Strike framework.
- It delivers inject-and-persist functionality via a collection of small C “plugins” (Beacon Object Files) that use direct syscalls to evade EDR/AV.
- The tool has three functional domains: Injection, Persistence, and Kernel-mode Drivers.

##### File structure
- Top‐level artifacts:
- CobaltWhispers.cna – the Aggressor script that loads and dispatches BOFs in Cobalt Strike.
- src/Makefile – orchestrates build of each C module into a Beacon Object File via mingw-w64, SysWhispers2, InlineWhispers2.
- src/Drivers – driver-based capabilities (DisableDSE, Intercept, UnloadDriver).
- src/Injection – user-mode injection techniques (CreateRemoteThread, MapViewOfSection, SpawnProcess, QueueUserAPC, TransactedHollowing, PhantomDLLHollowing).
- src/Persistence – registry and scheduled-task–based persistence techniques.
- Each feature folder contains:
- A .c file – logic for that technique
- beacon.h/helpers.h – Beacon API glue and shared helpers
- syscalls-asm.h, syscalls.[ch] – direct-syscalls stubs generated by SysWhispers2/InlineWhispers2.

##### README for additional insights
- Dependencies: mingw-w64, make, Python3, SysWhispers2, InlineWhispers2.
- Build flow:
1) SysWhispers2 → export minimal syscall stubs for required NT APIs.
2) InlineWhispers2 → package stubbed code for beacon usage.
3) Makefile → compiles each module into a .o/.cna for Cobalt Strike Beacon.
- Runtime flow: built BOFs are loaded by CobaltWhispers.cna into a Beacon session, invoked via Aggressor commands, invoke syscalls to perform injection/persistence/driver tasks.

##### Diagramming recommendations
- Blue for build-time tools & processes.
- Orange for module groups (Injection, Persistence, Drivers).
- Green for runtime platforms (Beacon, Windows).
- Gray for external items (EDR/AV, vulnerable driver).

##### Essential details
- Split between code generation (SysWhispers2 → stubs) and code compilation (Make → BOFs).
- How CobaltWhispers.cna orchestrates BOF dispatch.
- Direct syscall bypass mechanism as a highlighted path to the Windows kernel.
- Modules under Injection/Persistence/Drivers to illustrate modularity and extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Lane
    subgraph "Build-Time Processes"
        direction TB
        CG["SysWhispers2 & InlineWhispers2"]:::build
        MF["Make + mingw-w64 (src/Makefile)"]:::build
    end

    CG -->|"generate syscall stubs"| MF

    %% Module Compilation
    subgraph "Module Categories"
        direction TB
        subgraph "Injection Modules" 
            direction TB
            IM_DIR["src/Injection"]:::module
            CRT["CreateRemoteThread"]:::module
            MVS["MapViewOfSection"]:::module
            SPN["SpawnProcess"]:::module
            QUA["QueueUserAPC"]:::module
            THO["TransactedHollowing"]:::module
            PHL["PhantomDLLHollowing"]:::module
        end
        subgraph "Persistence Modules"
            direction TB
            PM_DIR["src/Persistence"]:::module
            PER["PersistElevatedRegKey"]:::module
            PUUR["PersistElevatedUserInitRegKey"]:::module
            PST["PersistScheduledTaskCOMHijack"]:::module
            PUM["PersistUserInitMprRegKey"]:::module
            PUR["PersistUserRegKey"]:::module
        end
        subgraph "Driver Modules"
            direction TB
            DM_DIR["src/Drivers"]:::module
            DIS["DisableDSE"]:::module
            INT["Intercept"]:::module
            ULD["UnloadDriver"]:::module
        end
    end

    MF -->|"compiles each .c to BOF"| IM_DIR
    MF --> PM_DIR
    MF --> DM_DIR

    %% Output Artifacts
    subgraph "Artifacts"
        direction TB
        BOFS["Beacon Object Files (BOFs)"]:::artifact
        AS["CobaltWhispers.cna"]:::script
    end

    IM_DIR --> BOFS
    PM_DIR --> BOFS
    DM_DIR --> BOFS
    AS --> BOFS

    %% Runtime Lane
    subgraph "Runtime Execution"
        direction TB
        CSB["Cobalt Strike Beacon"]:::runtime
        WIN["Windows Host (User & Kernel)"]:::runtime
    end

    BOFS -->|"loaded by"| CSB
    AS -->|"dispatches BOFs to"| CSB
    CSB -->|"BeaconInvoke(BOF)"| BOFS
    BOFS -->|"direct NT syscalls"| WIN

    %% DisableDSE Flow
    DIS -->|"drops signed driver"| WIN
    WIN -->|"loads malicious driver"| DIS

    %% External Dependencies
    subgraph "External"
        direction TB
        EDR["EDR/AV"]:::external
        VSD["Vulnerable Signed Driver"]:::external
    end

    BOFS -->|"bypasses"| EDR
    DIS -->|"requires"| VSD

    %% Click Events
    click AS "https://github.com/nvisosecurity/cobaltwhispers/blob/main/CobaltWhispers.cna"
    click MF "https://github.com/nvisosecurity/cobaltwhispers/tree/main/src/Makefile"
    click IM_DIR "https://github.com/nvisosecurity/cobaltwhispers/tree/main/src/Injection"
    click CRT "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/CreateRemoteThread/CreateRemoteThread.c"
    click MVS "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/MapViewOfSection/MapViewOfSection.c"
    click SPN "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/SpawnProcess/SpawnProcess.c"
    click QUA "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/QueueUserAPC/QueueUserAPC.c"
    click THO "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/TransactedHollowing/TransactedHollowing.c"
    click PHL "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Injection/PhantomDLLHollowing/PhantomDLLHollowing.c"
    click PM_DIR "https://github.com/nvisosecurity/cobaltwhispers/tree/main/src/Persistence"
    click PER "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Persistence/PersistElevatedRegKey/PersistElevatedRegKey.c"
    click PUUR "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Persistence/PersistElevatedUserInitRegKey/PersistElevatedUserInitRegKey.c"
    click PST "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Persistence/PersistScheduledTaskCOMHijack/PersistScheduledTaskCOMHijack.c"
    click PUM "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Persistence/PersistUserInitMprRegKey/PersistUserInitMprRegKey.c"
    click PUR "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Persistence/PersistUserRegKey/PersistUserRegKey.c"
    click DM_DIR "https://github.com/nvisosecurity/cobaltwhispers/tree/main/src/Drivers"
    click DIS "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Drivers/DisableDSE/DisableDSE.c"
    click INT "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Drivers/Intercept/Intercept.c"
    click ULD "https://github.com/nvisosecurity/cobaltwhispers/blob/main/src/Drivers/UnloadDriver/UnloadDriver.c"
    click README "https://github.com/nvisosecurity/cobaltwhispers/blob/main/README.md"

    %% Styles
    classDef build fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef module fill:#ffe5cc,stroke:#ff9933,color:#663300
    classDef artifact fill:#e6ffe6,stroke:#33cc33,color:#006600
    classDef script fill:#e6ffe6,stroke:#33cc33,color:#006600
    classDef runtime fill:#ccffcc,stroke:#33cc33,color:#006600
    classDef external fill:#f2f2f2,stroke:#999999,color:#666666
```
