# fortra/nanodump architecture

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

- Interactive diagram: https://gitdiagram.com/fortra/nanodump
- Repository: https://github.com/fortra/nanodump

## Overview

The NanoDump project is a low-level utility designed to create a minidump of the LSASS process using a variety of techniques intended to evade detection. Given its specialized nature as a security and forensic tool, the architecture is centered around the manipulation of process handles, assorted dumping techniques, and a modular setup that organizes different methods (like handle duplication, seclogon-based leakage, and exploiting PPL/SSP mechanisms).

##### Main Components
- Command-Line Interface (CLI) & Input Parsing:
- Represents the entry point. All flag options (e.g., --duplicate, --fork, --seclogon, etc.) and parameters are parsed here.
- Dump Engine:
- The core logic that creates a minidump of LSASS. It includes different dumping methods such as forking, snapshot, direct handle duplication, and signature restoration.
- LSASS Handle Acquisition Modules:
- Subcomponents to obtain a handle to LSASS safely:
▪ Duplicate Handle Module
▪ Elevated Handle Module
▪ Seclogon Leak (local, remote, duplicate) Modules
▪ Spoof Callstack module that simulates a legitimate context
- Exploit/Bypass Techniques:
- These include PPL Dump and PPL Medic modules for dumping LSASS even as a protected process.
- SSP module, which uploads a DLL into LSASS and uses a named pipe for parameter passing.
- OS Interaction Layer:
- Low-level functions and assemblies (e.g., syscalls, token privilege adjustments, hardware breakpoints) which interact directly with Windows internals.
- Auxiliary Scripts & Resources:
- The scripts directory (e.g., restore_signature, randomize_sw2_seed.py) and resource files for demo images and additional configuration.
- Integration with External Tools:
- Export components to work with Cobalt Strike via NanoDump.cna and support for further post-dump analysis (e.g., with mimikatz/pypykatz).

##### Relationships and Data Flow
- User Input (CLI arguments) flows directly into the Command Parser, which then selects one or more relevant LSASS handle acquisition techniques.
- The chosen technique module communicates with the OS Interaction Layer to obtain the necessary permissions and handles.
- Once a valid handle is secured, control passes to the Dump Engine. This module either creates a direct dump or coordinates with methods like process forking or snapshot creation.
- If needed, additional verification or post-processing occurs (for instance, restoring a valid signature through the restore signature script).
- The final dump is produced and can be passed to external tools for secret extraction.

##### Highlighting Architectural Patterns
- Modular Design – each technique (duplicate handle, seclogon leak, spoofed callstack, forking/snapshot) is encapsulated in its own module.
- Layered Architecture – separation between the front-end CLI logic, core dumping logic, and the low-level OS interfacing code (often housed in the include and asm source files).
- Strategy Pattern – the dump engine dynamically selects a dumping strategy based on the command-line flags provided.
- Integration/Plugin Support – the support for Cobalt Strike (via NanoDump.cna) and the potential for external post-processing (e.g., mimikatz integration).

##### Final Remarks to the Principal Software Engineer
- That any external dependencies (script resources, integration modules) are annotated so that one can understand the overall system without needing to dive into the source.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    subgraph "Command-Line Interface & Input Parsing"
        CLI["Command-Line Interface"]:::CLI
    end

    subgraph "LSASS Handle Acquisition Modules"
        DUP["Duplicate/Elevated Handle Module"]:::Acquisition
        SEC["Seclogon Leak Module"]:::Acquisition
        SPOOF["Spoof Callstack Module"]:::Acquisition
    end

    subgraph "Core Dumping"
        DUMP["Dump Engine"]:::Dump
    end

    subgraph "Exploit/Bypass Techniques"
        PPL["PPL Exploits"]:::Exploit
        SSP["SSP Module"]:::Exploit
    end

    subgraph "OS Interaction Layer"
        OS["OS Interaction"]:::OS
    end

    subgraph "Auxiliary Scripts & Resources"
        AUX["Auxiliary Scripts & Resources"]:::Aux
    end

    subgraph "External Tools Integration"
        EXT["External Tools Integration"]:::External
    end

    %% Data Flow Connections
    CLI -->|"selects"| DUP
    CLI -->|"selects"| SEC
    CLI -->|"selects"| SPOOF

    DUP -->|"hand-over handle"| DUMP
    SEC -->|"hand-over handle"| DUMP
    SPOOF -->|"hand-over handle"| DUMP

    OS -->|"OS-level calls"| DUP
    OS -->|"OS-level calls"| SEC
    OS -->|"OS-level calls"| SPOOF
    OS -->|"supports"| DUMP

    DUMP -->|"triggers exploits"| PPL
    DUMP -->|"triggers exploits"| SSP
    DUMP -->|"post-process"| AUX
    DUMP -->|"integrates with"| EXT

    %% Click Events
    click CLI "https://github.com/fortra/nanodump/blob/main/source/entry.c"
    click DUMP "https://github.com/fortra/nanodump/blob/main/source/nanodump.c"
    click DUP "https://github.com/fortra/nanodump/blob/main/source/handle.c"
    click SEC "https://github.com/fortra/nanodump/blob/main/source/malseclogon.c"
    click SPOOF "https://github.com/fortra/nanodump/blob/main/source/spoof_callstack.c"
    click PPL "https://github.com/fortra/nanodump/blob/main/source/ppl/ppl.c"
    click SSP "https://github.com/fortra/nanodump/blob/main/source/ssp/ssp.c"
    click OS "https://github.com/fortra/nanodump/blob/main/source/syscalls.c"
    click AUX "https://github.com/fortra/nanodump/blob/main/scripts/randomize_sw2_seed.py"
    click EXT "https://github.com/fortra/nanodump/blob/main/NanoDump.cna"

    %% Styles
    classDef CLI fill:#FFD2D2,stroke:#B22222,stroke-width:2px;
    classDef Dump fill:#D2FFD2,stroke:#228B22,stroke-width:2px;
    classDef Acquisition fill:#D2D2FF,stroke:#00008B,stroke-width:2px;
    classDef Exploit fill:#FFF5BA,stroke:#B8860B,stroke-width:2px;
    classDef OS fill:#FFE0D2,stroke:#CD5C5C,stroke-width:2px;
    classDef Aux fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px;
    classDef External fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
```
