# lontivero/vinchuca architecture

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

- Interactive diagram: https://gitdiagram.com/lontivero/vinchuca
- Repository: https://github.com/lontivero/vinchuca

## Overview

##### Project type and purpose
- Vinchuca is a .NET-based, peer-to-peer botnet “agent” (no GUI/C&C interface) built for educational purposes.
- Its core responsibilities: join a P2P overlay, establish encrypted/signed channels, execute payloads (DDoS, backdoor, proxy, USB spread, etc.), evade analysis, and maintain persistence.

##### File structure
- Top-level:
- Agent/… : the main bot agent
- REPL/…  : a command-line front end (for testing/debugging)
- Agent/ submodules:
- Actions/…    : payload implementations (Backdoor, DDoS, Socks5, WebInject)
- Crypto/…     : cipher implementations + key-exchange + signing
- Network/…    : communication layer (listeners, sockets, comm manager), protocol (message types, handlers, peer management), connectivity tests
- System/…     : OS-level helpers (anti-debug, sandbox detect, firewall, command exec)
- Upnp/…       : NAT traversal
- Spread/…     : USB, privilege escalation
- Utils/…      : common queues, pools, PoW, logging
- Workers/…    : scheduling and background tasks
- REPL/ submodules: CLI parser, command classes, virtual console for local control of an Agent instance.

##### README for additional insights
- Emphasizes: P2P protocol, Diffie-Hellman handshake, message signing, single instance, anti-debug/sandbox, integrated proxies, web injection hooks, DDoS flavors, USB spreading, UPnP port mapping.
- No database or external control panel – it’s a pure peer agent.

a. Main components
- Agent Process
- P2P Overlay Network (Peers)
- Crypto Layer (DH handshake, AES/RC4, RSA signature)
- Protocol Layer (Message Manager, Handlers)
- Communication Layer
– Listeners (TCP/UDP)
– CommunicationManager (IMessageSender, ReplyWaitManager)
- Actions Modules
– DDoS, Backdoor, Socks5, WebInject, USB Spread, Firewall
- System/Evasion
– Anti-Debug, SandboxDetection, SingleInstance, CommandExecutor
- Workers Scheduler
- UPnP Module
- Utilities & Logging
- REPL CLI (local control interface)
b. Relationships and interactions
1. On startup, System/Evasion performs checks → if passed, instantiate Crypto Layer.
2. Crypto Layer performs DH handshake over Communication Layer.
3. Communication Layer uses Protocol Layer to wrap/unwrap messages, dispatch to Handlers.
4. Handlers invoke Actions Modules or System tasks.
5. Actions may spawn Workers to run asynchronously.
6. UPnP Module (optional) requests port mappings before listening.
7. REPL connects locally (loopback) to Communication Manager to inject commands.
8. Utilities (logging, queues) support all layers.
c. Architectural patterns/design principles
- Layered Architecture: separation of concerns (Crypto → Protocol → Comm → Actions → System)
- Event-driven: listeners raise events for incoming messages
- Plugin-style Actions: new features live in Actions/ and are invoked via handlers
- Single Responsibility: each module focuses on one aspect (e.g., Spread, Upnp, Utils)
d. Technologies, frameworks, libraries
- .NET Framework / Mono
- C# (<file>.cs)
- Diffie-Hellman, RSA, AES, RC4
- TCP/UDP sockets, UPnP SOAP
- App.config for settings
- MSBuild / csproj files

##### Details to capture
- All major subdirectories in Agent/ as distinct components.
- Flow of data: from network to handlers to execution and back.
- Integration points: UPnP for NAT, REPL for control, Utils for cross-cutting concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    AgentProcess["Agent Process"]:::agent
    AgentProcess -->|Startup| Evasion["System/Evasion Modules"]:::system
    Evasion -->|Checks Passed| Crypto["Crypto Layer"]:::crypto
    Crypto -->|DH Handshake| P2P["P2P Overlay Network (Peers)"]:::network
    P2P -->|Connect| CommLayer["Communication Layer"]:::network
    subgraph "Protocol Layer"
        Protocol["Message Manager & Handlers"]:::network
    end
    CommLayer -->|Wrap/Unwrap Messages| Protocol
    subgraph "Actions Modules"
        Backdoor["Backdoor"]:::actions
        DDoS["DDoS"]:::actions
        Socks5["Socks5"]:::actions
        WebInject["WebInject"]:::actions
    end
    Protocol -->|Invoke| Backdoor
    Protocol -->|Invoke| DDoS
    Protocol -->|Invoke| Socks5
    Protocol -->|Invoke| WebInject
    subgraph "Worker Scheduler"
        Workers["Workers Scheduler"]:::utils
    end
    Backdoor -->|Async| Workers
    DDoS -->|Async| Workers
    Socks5 -->|Async| Workers
    WebInject -->|Async| Workers
    UPnP["UPnP Module"]:::network
    UPnP -->|Port Mapping| CommLayer
    Utils["Utilities & Logging"]:::utils
    Utils -.-> AgentProcess
    Utils -.-> Evasion
    Utils -.-> Crypto
    Utils -.-> CommLayer
    Utils -.-> Protocol
    Utils -.-> Backdoor
    Utils -.-> Workers
    subgraph "REPL CLI"
        REPL["Local REPL Interface"]:::utils
    end
    REPL -->|Loopback| CommLayer

    class AgentProcess,AgentMain agent
    class Evasion system
    class Crypto crypto
    class P2P,Protocol,CommLayer,UPnP network
    class Backdoor,DDoS,Socks5,WebInject actions
    class Workers,Utils,REPL utils

    %% Click Events
    click AgentProcess "https://github.com/lontivero/vinchuca/blob/master/Agent/Agent.cs"
    click AgentProcess "https://github.com/lontivero/vinchuca/blob/master/Agent/Main.cs"
    click P2P "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Protocol/Peers/PeerManager.cs"
    click P2P "https://github.com/lontivero/vinchuca/tree/master/Agent/Network/Protocol/Peers"
    click Crypto "https://github.com/lontivero/vinchuca/tree/master/Agent/Crypto"
    click Protocol "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Protocol/Messages/MessageManager.cs"
    click Protocol "https://github.com/lontivero/vinchuca/tree/master/Agent/Network/Protocol/Handlers"
    click CommLayer "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Comunication/CommunicationManager.cs"
    click CommLayer "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Comunication/Listeners/ListenerBase.cs"
    click CommLayer "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Comunication/Listeners/TcpListener.cs"
    click CommLayer "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Comunication/Listeners/UdpListener.cs"
    click CommLayer "https://github.com/lontivero/vinchuca/blob/master/Agent/Network/Comunication/ReplyWaitManager.cs"
    click Backdoor "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/Backdoor/Backdoor.cs"
    click DDoS "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/DDoS/Attack.cs"
    click Socks5 "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/Socks5/Socks5Server.cs"
    click WebInject "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/WebInject/HttpsProxyServer.cs"
    click WebInject "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/WebInject/CertificateProvider.cs"
    click WebInject "https://github.com/lontivero/vinchuca/blob/master/Agent/Actions/WebInject/HttpClient.cs"
    click Evasion "https://github.com/lontivero/vinchuca/blob/master/Agent/System/Evation/AntiDebugging.cs"
    click Evasion "https://github.com/lontivero/vinchuca/blob/master/Agent/System/Evation/SandboxDetection.cs"
    click Evasion "https://github.com/lontivero/vinchuca/blob/master/Agent/System/CommandExecutor.cs"
    click Evasion "https://github.com/lontivero/vinchuca/blob/master/Agent/System/Firewall.cs"
    click Workers "https://github.com/lontivero/vinchuca/blob/master/Agent/Workers/ScheduledAction.cs"
    click Workers "https://github.com/lontivero/vinchuca/blob/master/Agent/Workers/BackgroundWorker.cs"
    click Workers "https://github.com/lontivero/vinchuca/blob/master/Agent/Workers/TimedWorker.cs"
    click UPnP "https://github.com/lontivero/vinchuca/blob/master/Agent/Upnp/UpnpNatDevice.cs"
    click UPnP "https://github.com/lontivero/vinchuca/blob/master/Agent/Upnp/SoapClient.cs"
    click UPnP "https://github.com/lontivero/vinchuca/blob/master/Agent/Upnp/CreatePortMappingMessage.cs"
    click Utils "https://github.com/lontivero/vinchuca/tree/master/Agent/Utils"
    click Utils "https://github.com/lontivero/vinchuca/blob/master/Agent/Logger.cs"
    click Utils "https://github.com/lontivero/vinchuca/blob/master/Agent/ColorConsoleTraceListener.cs"
    click REPL "https://github.com/lontivero/vinchuca/blob/master/REPL/Program.cs"
    click REPL "https://github.com/lontivero/vinchuca/blob/master/REPL/CommandLine.cs"
    click REPL "https://github.com/lontivero/vinchuca/tree/master/REPL/Commands"

    classDef network fill:#87CEFA,stroke:#4682B4,color:#000
    classDef crypto fill:#98FB98,stroke:#2E8B57,color:#000
    classDef actions fill:#FFA500,stroke:#FF8C00,color:#000
    classDef system fill:#FF726F,stroke:#8B0000,color:#000
    classDef utils fill:#D3D3D3,stroke:#696969,color:#000
    classDef agent fill:#E6E6FA,stroke:#9370DB,color:#000
```
