# hackerhouse-opensource/offensivelua architecture

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

- Interactive diagram: https://gitdiagram.com/hackerhouse-opensource/offensivelua
- Repository: https://github.com/hackerhouse-opensource/offensivelua

## Overview

##### Main Components
- Offensive Lua Scripts: These are standalone Lua scripts (e.g., bin2hex.lua, bindshell.lua, downloadexec.lua, etc.) that perform various post-exploitation activities like UAC bypass, registry manipulation, networking tasks, etc.
- LuaJIT Execution Environment: The scripts are intended to be run with LuaJIT. Highlight that LuaJIT acts as the primary interpreter and runtime environment interfacing with Windows libraries.
- OffensiveLuaEmbedded Module: A Visual Studio solution that embeds LuaJIT into a native binary. This demonstrates how the scripts can be run from an embedded context.
- External Lua Modules: The “lunarmodules” directory incorporates important libraries (luafilesystem, luasec, and luasocket) used by several scripts for extended functionality (file operations, secure communications, networking).
- Operating System & External Dependencies: Represent Microsoft Windows as the host OS and emphasize how Windows APIs are accessed via FFI, with tasks like process management, registry access, or memory searches.

##### Relationships and Interactions
- The Offensive Lua scripts (executed by LuaJIT) interact directly with Windows libraries via FFI.
- The embedded project (OffensiveLuaEmbedded) illustrates integrating LuaJIT into a compiled binary, so show a relationship between the Visual Studio project, LuaJIT, and the scripts.
- External modules (lunarmodules) are dependencies loaded by the Lua scripts for tasks like socket communication or secure operations.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize how each script is an independent module focused on a specific red teaming task.
- Embedding & Reusability: Stress the integration of LuaJIT within a standalone application (via the OffensiveLuaEmbedded project) and the reusability of external Lua modules.
- Separation of Concerns: Outline deploying scripts independently vs. embedding them into Windows executables, which shows a clear separation between script logic and the underlying host execution mechanism.
- Interfacing with the OS: Identify the pattern where Lua scripts and LuaJIT leverage the Windows API to achieve tasks that would normally require native code.

##### Relevant Technologies, Frameworks, and Libraries
- Lua & LuaJIT – core interpreter and JIT compiler.
- Microsoft Windows APIs – used via FFI for operations like registry access, process creation, memory scanning, and UAC bypass.
- Visual Studio – for the OffensiveLuaEmbedded project which demonstrates embedding LuaJIT.
- External modules from lunarmodules, such as luasocket (networking), luasec (secure communications), and luafilesystem (file operations).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Offensive Lua Scripts Subgraph
    subgraph "Offensive Lua Scripts"
        bin2hex["\"bin2hex.lua\""]:::script
        bindshell["\"bindshell.lua\""]:::script
        binrun["\"binrun.lua\""]:::script
        console["\"console.lua\""]:::script
        downloadexec["\"downloadexec.lua\""]:::script
        downloadexec_uac["\"downloadexec_UACbypass.lua\""]:::script
        efspotato["\"efspotato.lua\""]:::script
        eventcode["\"eventcode.lua\""]:::script
        filewrite["\"filewrite.lua\""]:::script
        howami["\"howami.lua\""]:::script
        listprocess["\"listprocess.lua\""]:::script
        memorysearch["\"memorysearch.lua\""]:::script
        messagebox["\"messagebox.lua\""]:::script
        regread["\"regread.lua\""]:::script
        regwrite["\"regwrite.lua\""]:::script
        regwritedel["\"regwritedel.lua\""]:::script
        rickroll["\"rickroll.lua\""]:::script
        runcmd["\"runcmd.lua\""]:::script
        runcmd2["\"runcmd2.lua\""]:::script
        runswhide["\"runswhide.lua\""]:::script
        uac_bypass_bt["\"uac_bypass_bluetooth_win10.lua\""]:::script
    end

    %% LuaJIT Runtime Environment
    LuaJIT["\"LuaJIT Runtime Environment\""]:::runtime

    %% OffensiveLuaEmbedded Module Subgraph
    subgraph "OffensiveLuaEmbedded Module"
        VS_Sln["\"OffensiveLuaEmbedded.sln\""]:::embedded
        OffensiveCpp["\"OffensiveLuaEmbedded.cpp\""]:::embedded
        VCXProj["\"OffensiveLuaEmbedded.vcxproj\""]:::embedded
        VCXProjFilters["\"OffensiveLuaEmbedded.vcxproj.filters\""]:::embedded
    end

    %% External Lua Modules Subgraph
    subgraph "External Lua Modules (lunarmodules)"
        LuaFS["\"luafilesystem\""]:::external
        LuaSec["\"luasec\""]:::external
        LuaSocket["\"luasocket\""]:::external
    end

    %% Windows OS & External APIs
    WindowsOS["\"Windows OS & External APIs\""]:::os

    %% Connections
    %% Representative connection from one script to LuaJIT to denote all scripts execute via FFI
    bindshell -->|"executes_via_FFI"| LuaJIT

    %% Connection showing dependency on external modules (applies to all scripts)
    bindshell ---|"uses_modules"| LuaFS
    bindshell ---|"uses_modules"| LuaSec
    bindshell ---|"uses_modules"| LuaSocket

    %% OffensiveLuaEmbedded Module embeds LuaJIT
    VS_Sln -->|"embeds_LuaJIT"| LuaJIT

    %% LuaJIT uses Windows APIs via FFI
    LuaJIT -->|"calls_Windows_APIs"| WindowsOS

    %% OffensiveLuaEmbedded Module also integrates with Windows OS
    OffensiveCpp -->|"compiled_with_VS"| WindowsOS
    VCXProj -->|"configured_for_OS"| WindowsOS
    VCXProjFilters -->|"config_filters"| WindowsOS

    %% Click Events for Offensive Lua Scripts
    click bin2hex "https://github.com/hackerhouse-opensource/offensivelua/blob/main/bin2hex.lua"
    click bindshell "https://github.com/hackerhouse-opensource/offensivelua/blob/main/bindshell.lua"
    click binrun "https://github.com/hackerhouse-opensource/offensivelua/blob/main/binrun.lua"
    click console "https://github.com/hackerhouse-opensource/offensivelua/blob/main/console.lua"
    click downloadexec "https://github.com/hackerhouse-opensource/offensivelua/blob/main/downloadexec.lua"
    click downloadexec_uac "https://github.com/hackerhouse-opensource/offensivelua/blob/main/downloadexec_UACbypass.lua"
    click efspotato "https://github.com/hackerhouse-opensource/offensivelua/blob/main/efspotato.lua"
    click eventcode "https://github.com/hackerhouse-opensource/offensivelua/blob/main/eventcode.lua"
    click filewrite "https://github.com/hackerhouse-opensource/offensivelua/blob/main/filewrite.lua"
    click howami "https://github.com/hackerhouse-opensource/offensivelua/blob/main/howami.lua"
    click listprocess "https://github.com/hackerhouse-opensource/offensivelua/blob/main/listprocess.lua"
    click memorysearch "https://github.com/hackerhouse-opensource/offensivelua/blob/main/memorysearch.lua"
    click messagebox "https://github.com/hackerhouse-opensource/offensivelua/blob/main/messagebox.lua"
    click regread "https://github.com/hackerhouse-opensource/offensivelua/blob/main/regread.lua"
    click regwrite "https://github.com/hackerhouse-opensource/offensivelua/blob/main/regwrite.lua"
    click regwritedel "https://github.com/hackerhouse-opensource/offensivelua/blob/main/regwritedel.lua"
    click rickroll "https://github.com/hackerhouse-opensource/offensivelua/blob/main/rickroll.lua"
    click runcmd "https://github.com/hackerhouse-opensource/offensivelua/blob/main/runcmd.lua"
    click runcmd2 "https://github.com/hackerhouse-opensource/offensivelua/blob/main/runcmd2.lua"
    click runswhide "https://github.com/hackerhouse-opensource/offensivelua/blob/main/runswhide.lua"
    click uac_bypass_bt "https://github.com/hackerhouse-opensource/offensivelua/blob/main/uac_bypass_bluetooth_win10.lua"

    %% Click Event for LuaJIT Runtime Environment (points to the luajit folder in OffensiveLuaEmbedded)
    click LuaJIT "https://github.com/hackerhouse-opensource/offensivelua/tree/main/OffensiveLuaEmbedded/luajit"

    %% Click Events for OffensiveLuaEmbedded Module components
    click VS_Sln "https://github.com/hackerhouse-opensource/offensivelua/blob/main/OffensiveLuaEmbedded/OffensiveLuaEmbedded.sln"
    click OffensiveCpp "https://github.com/hackerhouse-opensource/offensivelua/blob/main/OffensiveLuaEmbedded/OffensiveLuaEmbedded/OffensiveLuaEmbedded.cpp"
    click VCXProj "https://github.com/hackerhouse-opensource/offensivelua/blob/main/OffensiveLuaEmbedded/OffensiveLuaEmbedded/OffensiveLuaEmbedded.vcxproj"
    click VCXProjFilters "https://github.com/hackerhouse-opensource/offensivelua/blob/main/OffensiveLuaEmbedded/OffensiveLuaEmbedded/OffensiveLuaEmbedded.vcxproj.filters"

    %% Click Events for External Lua Modules
    click LuaFS "https://github.com/hackerhouse-opensource/offensivelua/tree/main/lunarmodules/luafilesystem"
    click LuaSec "https://github.com/hackerhouse-opensource/offensivelua/tree/main/lunarmodules/luasec"
    click LuaSocket "https://github.com/hackerhouse-opensource/offensivelua/tree/main/lunarmodules/luasocket"

    %% Styles
    classDef script fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef runtime fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef embedded fill:#abebc6,stroke:#239b56,stroke-width:2px;
    classDef external fill:#fcf3cf,stroke:#d4ac0d,stroke-width:2px;
    classDef os fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
