# chainreactors/malice-network architecture

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

- Interactive diagram: https://gitdiagram.com/chainreactors/malice-network
- Repository: https://github.com/chainreactors/malice-network

## Overview

##### Main components
a. Client Application
- UI Layer
- CLI/TUI engine (uses external/console and external/readline)
- Optional GUI assets (client/assets)
- Command Layer
- 100+ sub-commands under client/command
- Core Layer
- client/core (session, plugin loaders: Lua, Yaegi)
- REPL Layer
- client/repl (console, login, plugin integration)
- gRPC/Stubs
- helper/proto/clientpb and rootpb
b. Server Application
- gRPC API Layer
- server/rpc (RPC service definitions and gRPC server)
- HTTP/Web UI Layer
- server/assets + embedded web UI
- Listener Modules (C2 channels)
- TCP, HTTP, REM, Website (server/listener)
- Core Orchestration
- server/internal/core (session, pipeline, tasks, event bus)
- Build Service
- server/internal/build (artifact generation, GitHub integration)
- Parser & Stream
- server/internal/parser (malefic, pulse)
- server/internal/stream (AES, XOR, compression)
- Cert & Security
- server/internal/certutils, helper/utils/mtls
- Configuration
- server/configs, YAML files, environment
- Data Layer
- SQLite via server/internal/db (models, SQL helper)
c. Shared Libraries
- helper/cryptography (implant signing, TLS keying)
- helper/encoders (base32/58/64, gzip, traffic encoder)
- helper/utils (fileutils, output formatting, peek)
- external/* (console, gonut, readline) as third-party dependencies

##### Relationships and data flows
- Client ⇄ Server
- gRPC calls over mTLS (helper/utils/mtls)
- Optional HTTP(S) calls for web UI assets
- Server ⇄ Database
- CRUD operations via internal/db/sqlite.go
- Server ⇄ Listeners ⇄ Implants
- C2 channel registration, inbound/outbound pipelines
- Build Service ⇄ GitHub/Goreleaser
- Artifact assembly and distribution
- Shared Libraries
- Imported by both client and server code

##### Architectural patterns & design principles
- Layered Architecture (UI → Command → Core → Data)
- Modular Listener Plugins (each C2 channel implements a common interface)
- RPC-first design (all operations exposed via gRPC services)
- Pluggable scripting (Lua, Yaegi) in client side
- Embedded assets (Go’s embed for UI, certs, plugins)
- Single binary deployments (client and server compile all modules in one)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Application"
        direction TB
        UI["CLI/TUI Engine"]:::client
        Assets["GUI Assets"]:::client
        Command["Command Layer"]:::client
        CoreCL["Core Layer"]:::client
        REPL["REPL Layer"]:::client
        Proto["gRPC/Stubs"]:::client
    end

    %% Server Layer
    subgraph "Server Application"
        direction TB
        RPC["gRPC API Layer"]:::server
        WebUI["HTTP/Web UI Layer"]:::server
        Listeners["Listener Modules"]:::server
        CoreSV["Core Orchestration"]:::server
        Build["Build Service"]:::server
        subgraph "Parser & Stream"
            direction TB
            Parser["Parser"]:::server
            Stream["Stream"]:::server
        end
        subgraph "Cert & Security"
            direction TB
            CertUtils["CertUtils"]:::server
            MTLS["mTLS Utils"]:::server
        end
        Config["Configuration"]:::server
        DB["SQLite Data Layer"]:::server
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        Crypt["Cryptography"]:::shared
        Encoders["Encoders"]:::shared
        Utils["Utilities"]:::shared
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ConsoleExt["console"]:::external
        ReadlineExt["readline"]:::external
        Gonut["gonut"]:::external
    end

    %% Cloud/Network
    subgraph "Network Boundary"
        direction TB
        Agents["Implants / Agents"]:::cloud
        GitHub["GitHub/Goreleaser"]:::cloud
    end

    %% Connections
    UI -->|uses| ConsoleExt
    UI -->|uses| ReadlineExt
    UI -->|optional assets| Assets
    UI -->|invokes| Command
    Command -->|calls| CoreCL
    REPL -->|integrates| CoreCL
    CoreCL -->|imports| Proto
    Proto -->|gRPC/mTLS| RPC
    RPC -->|orchestrates| CoreSV
    WebUI -->|HTTP/WebSocket| CoreSV
    CoreSV -->|SQL| DB
    CoreSV -->|dispatch| Listeners
    Listeners -->|C2 pipeline frames| Agents
    Agents -->|responses| Listeners
    Build -->|artifact push| GitHub
    Parser -->|parses| CoreSV
    Stream -->|streams| CoreSV
    CertUtils -->|provides| RPC
    MTLS -->|secures| RPC
    Config -->|configures| CoreSV
    CoreSV -->|queries| DB

    %% Shared imports
    Crypt -->|used by| CoreCL
    Crypt -->|used by| CoreSV
    Encoders -->|used by| CoreCL
    Encoders -->|used by| CoreSV
    Utils -->|used by| CoreCL
    Utils -->|used by| CoreSV

    %% Click Events - Client
    click ConsoleExt "https://github.com/chainreactors/malice-network/tree/dev/external/console"
    click ReadlineExt "https://github.com/chainreactors/malice-network/tree/dev/external/readline"
    click Assets "https://github.com/chainreactors/malice-network/tree/dev/client/assets"
    click Command "https://github.com/chainreactors/malice-network/tree/dev/client/command"
    click CoreCL "https://github.com/chainreactors/malice-network/tree/dev/client/core"
    click REPL "https://github.com/chainreactors/malice-network/tree/dev/client/repl"
    click Proto "https://github.com/chainreactors/malice-network/tree/dev/helper/proto/client"

    %% Click Events - Server
    click RPC "https://github.com/chainreactors/malice-network/tree/dev/server/rpc"
    click WebUI "https://github.com/chainreactors/malice-network/tree/dev/server/assets"
    click Listeners "https://github.com/chainreactors/malice-network/tree/dev/server/listener"
    click CoreSV "https://github.com/chainreactors/malice-network/tree/dev/server/internal/core"
    click Build "https://github.com/chainreactors/malice-network/tree/dev/server/internal/build"
    click Parser "https://github.com/chainreactors/malice-network/tree/dev/server/internal/parser"
    click Stream "https://github.com/chainreactors/malice-network/tree/dev/server/internal/stream"
    click CertUtils "https://github.com/chainreactors/malice-network/tree/dev/server/internal/certutils"
    click MTLS "https://github.com/chainreactors/malice-network/tree/dev/helper/utils/mtls"
    click Config "https://github.com/chainreactors/malice-network/tree/dev/server/internal/configs"
    click DB "https://github.com/chainreactors/malice-network/tree/dev/server/internal/db"

    %% Click Events - Shared
    click Crypt "https://github.com/chainreactors/malice-network/tree/dev/helper/cryptography"
    click Encoders "https://github.com/chainreactors/malice-network/tree/dev/helper/encoders"
    click Utils "https://github.com/chainreactors/malice-network/tree/dev/helper/utils"

    %% Click Events - External
    click Gonut "https://github.com/chainreactors/malice-network/tree/dev/external/gonut"

    %% Styles
    classDef client fill:#D6E5FF,stroke:#000
    classDef server fill:#D6F5D6,stroke:#000
    classDef shared fill:#FFE7B3,stroke:#000
    classDef external fill:#DDDDDD,stroke:#000
    classDef cloud fill:#EFEFEF,stroke:#000,stroke-dasharray: 5 5
```
