Project Structure - Miku Miku Beam

Overview

Miku Miku Beam is organized into four main components that work together to provide both CLI and web-based stress testing capabilities.

Directory Layout

mikumikubeam/
├── cmd/                    # Main applications
│   ├── mmb-cli/           # CLI application
│   └── mmb-server/        # Web server application
├── internal/              # Core engine and implementations
│   ├── attacks/          # Attack method implementations
│   ├── config/           # Configuration management
│   ├── engine/           # Attack coordination engine
│   ├── netutil/          # Network utilities
│   └── proxy/            # Proxy loading and management
├── pkg/                   # Shared packages
│   ├── api/              # API types and interfaces
│   └── target/           # Target parsing utilities
├── web-client/           # React-based frontend
│   ├── public/          # Static assets
│   └── src/             # React source code
├── data/                # Runtime data (not in repo)
│   ├── proxies.txt     # Proxy list
│   └── uas.txt         # User agent list
├── bin/                 # Compiled binaries (generated)
├── docs/               # Documentation assets
├── go.mod              # Go dependencies
├── go.sum              # Go dependency checksums
├── Makefile           # Build automation
└── README.md          # Project documentation

Component Breakdown

CLI (`cmd/mmb-cli/`)

The command-line interface for running attacks directly from the terminal.

// Entry point for CLI application
package main

// Provides:
// - Command parsing and validation
// - Real-time colored output
// - Attack statistics display
// - Verbose logging support

Key Features:

Colored terminal output with real-time statistics
--verbose flag for detailed attack logs
--no-proxy flag to run without proxies
--threads flag to control concurrency
--duration, --delay, --packet-size for attack configuration

Example Usage:

./bin/mmb-cli attack http_flood http://example.com --verbose --threads 8

Server (`cmd/mmb-server/`)

Web server with Socket.IO support for the browser-based interface.

// Entry point for web server
package main

// Provides:
// - REST API endpoints
// - Socket.IO real-time communication
// - Static file serving
// - Multi-client attack management

Key Features:

REST API endpoints (/attacks, /configuration)
Real-time WebSocket communication via Socket.IO
Serves static web client files
Per-client attack instance management
Runs on http://localhost:3000 by default

API Endpoints:

POST /api/attacks - Start an attack
DELETE /api/attacks - Stop an attack
GET /api/configuration - Get configuration
WebSocket events for real-time stats

Core Engine (`internal/`)

The heart of the application containing attack implementations and coordination logic.

Engine (`internal/engine/`)

Attack coordination and management system.

engine.go (255 lines)

Core engine implementation:

Engine struct - Manages multiple concurrent attacks
AttackInstance - Represents a single running attack
Start() - Launches attacks with multiple threads
Stop() - Cancels specific attacks
StopAll() - Terminates all running attacks
Multi-threaded worker dispatch
Real-time statistics aggregation

registry.go (28 lines)

Attack worker registry:

Registry struct - Maps attack kinds to workers
Register() - Adds new attack methods
Get() - Retrieves worker by attack kind
ListKinds() - Returns all registered attacks

logging.go

Logging utilities:

SendAttackLogIfVerbose() - Conditional log sending
Prevents channel blocking
Formats attack statistics

Key Types:

type AttackKind string

const (
    AttackHTTPFlood     AttackKind = "http_flood"
    AttackHTTPBypass    AttackKind = "http_bypass"
    AttackHTTPSlowloris AttackKind = "http_slowloris"
    AttackTCPFlood      AttackKind = "tcp_flood"
    AttackMinecraftPing AttackKind = "minecraft_ping"
)

type AttackParams struct {
    Target      string
    TargetNode  targetpkg.Node
    Duration    time.Duration
    PacketDelay time.Duration
    PacketSize  int
    Method      AttackKind
    Threads     int
    Verbose     bool
}

type AttackWorker interface {
    Fire(ctx context.Context, params AttackParams, proxy Proxy, 
         userAgent string, logCh chan<- AttackStats) error
}

Attacks (`internal/attacks/`)

Individual attack method implementations organized by protocol.

HTTP Attacks (internal/attacks/http/)

flood.go - HTTP Flood Attack

Sends random GET/POST requests
Configurable payload sizes
Random method selection based on packet size
User agent rotation

bypass.go - HTTP Bypass Attack

Mimics real browser behavior
Handles redirects automatically
Manages cookies and sessions
Realistic headers and resources

slowloris.go - HTTP Slowloris Attack

Sends slow HTTP requests
Keeps connections open
Exhausts server resources
Partial header sending

TCP Attacks (internal/attacks/tcp/)

flood.go - TCP Flood Attack

Raw TCP packet flooding
Random payload generation
Direct connection establishment
Proxy support via netutil.DialTCP()

Game Attacks (internal/attacks/game/)

minecraft_ping.go - Minecraft Server Ping

Minecraft protocol implementation
Server status requests
MOTD (Message of the Day) queries
Player count polling

Attack Implementation Pattern: All attacks follow this structure:

package attacktype

import (
    "context"
    core "github.com/sammwyy/mikumikubeam/internal/engine"
)

type workerName struct{}

func NewWorkerName() *workerName { 
    return &workerName{} 
}

func (w *workerName) Fire(ctx context.Context, params core.AttackParams,
    p core.Proxy, ua string, logCh chan<- core.AttackStats) error {
    // Implementation
    return nil
}

Configuration (`internal/config/`)

Configuration management for runtime settings.

config.go

Server port configuration
Data file paths (proxies, user agents)
Default attack parameters
Environment variable support

Network Utilities (`internal/netutil/`)

Network helpers with proxy support.

httpdial.go

HTTP client creation with proxy support:

DialedHTTPClient() - Creates HTTP client with proxy
Custom transport configuration
Timeout and retry logic
TLS configuration

tcpdial.go

TCP connection helpers:

DialTCP() - Establishes TCP connection via proxy
SOCKS5 proxy support
HTTP CONNECT tunneling
Connection timeout handling

Proxy Management (`internal/proxy/`)

Proxy loading and filtering system.

loader.go

Loads proxies from data/proxies.txt
Parses proxy formats:
- protocol://user:pass@host:port
- protocol://host:port
- host:port (defaults to http)
- host (defaults to port 8080)
Validates proxy configurations
Filters out invalid entries

Shared Packages (`pkg/`)

Reusable packages that can be imported by external projects.

API Types (`pkg/api/`)

types.go

Shared API types and interfaces:

Request/response structures
Attack configuration types
Statistics data models
Error definitions

Target Utilities (`pkg/target/`)

node.go

Target parsing and validation:

Node struct - Represents parsed target
ParseTarget() - Parses URLs and addresses
ToURL() - Converts back to URL format
Protocol/host/port extraction

Web Client (`web-client/`)

React-based frontend with Miku theme and real-time updates.

web-client/
├── public/              # Static assets
│   ├── index.html      # HTML template
│   ├── music/          # Background music
│   └── images/         # Miku-themed graphics
├── src/                # React source
│   ├── lib/           # Utilities and helpers
│   ├── components/    # React components
│   ├── App.tsx       # Main application
│   └── main.tsx      # Entry point
├── package.json       # Node dependencies
├── tsconfig.json     # TypeScript config
└── vite.config.ts    # Vite build config

Key Features:

Modern UI with Miku theme
Real-time attack visualization
Socket.IO integration for live updates
Attack configuration interface
Proxy/UA editor built-in
Multi-attack support (multiple tabs)

Build Output:

Built files go to bin/web-client/
Server serves from this location
Production builds are optimized and minified

Build System

The Makefile provides convenient build commands:

make prepare      # Install all dependencies
make all          # Build everything
make webclient    # Build React frontend only
make cli          # Build CLI binary only  
make server       # Build server binary only
make run-cli      # Run CLI with args
make run-server   # Run web server
make clean        # Clean build artifacts

Build Flow

Install Dependencies

make prepare

Runs go mod tidy and npm install

Build Web Client

make webclient

Installs npm dependencies
Runs npm run build (Vite)
Copies to bin/web-client/

Build Binaries

make cli server

Compiles Go code
Outputs to bin/mmb-cli and bin/mmb-server

Data Files

Runtime data stored in the data/ directory:

Proxies (`data/proxies.txt`)

One proxy per line in various formats:

http://proxy1.example.com:8080
socks5://user:[email protected]:1080
proxy3.example.com:3128
proxy4.example.com

User Agents (`data/uas.txt`)

One user agent string per line:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36

These files can be edited through the web interface or manually.

Workflow Diagrams

Attack Execution Flow

Multi-Client Architecture

Each client maintains its own isolated attack instance.

Development Tips

Adding New Features

New Attack Method

Create worker in internal/attacks/
Register in cmd/mmb-cli/ and cmd/mmb-server/
Add to web client dropdown

New Protocol Support

Create package in internal/attacks/protocol/
Implement AttackWorker interface
Add network helpers to internal/netutil/ if needed

Engine Enhancement

Modify internal/engine/engine.go

Update AttackParams struct
Add new stats fields
Enhance worker dispatch logic

UI Changes

Edit files in web-client/src/

Update components
Rebuild with make webclient
Server automatically serves new build

Common File Locations

Where do I add a new attack type?

Create file in internal/attacks/[protocol]/[name].go
Add constant to internal/engine/engine.go
Register in both cmd/mmb-cli/main.go and cmd/mmb-server/main.go

Where are attack parameters defined?

internal/engine/engine.go - See AttackParams struct

Where is the proxy logic?

Loading: internal/proxy/loader.go
HTTP usage: internal/netutil/httpdial.go
TCP usage: internal/netutil/tcpdial.go

Where are API endpoints defined?

cmd/mmb-server/main.go - HTTP handlers and Socket.IO events

Next Steps

Add Attack Methods

Learn how to implement custom attack methods

Contributing

Submit your enhancements to the project

Get Started

Core Concepts

Usage

Attack Methods

Deployment

Development

Help

​Overview

​Directory Layout

​Component Breakdown

​CLI (cmd/mmb-cli/)

​Server (cmd/mmb-server/)

​Core Engine (internal/)

​Engine (internal/engine/)

​Attacks (internal/attacks/)

​Configuration (internal/config/)

​Network Utilities (internal/netutil/)

​Proxy Management (internal/proxy/)

​Shared Packages (pkg/)

​API Types (pkg/api/)

​Target Utilities (pkg/target/)

​Web Client (web-client/)

​Build System

​Build Flow

​Data Files

​Proxies (data/proxies.txt)

​User Agents (data/uas.txt)

​Workflow Diagrams

​Attack Execution Flow

​Multi-Client Architecture

​Development Tips

​Adding New Features

New Attack Method

New Protocol Support

Engine Enhancement

UI Changes

​Common File Locations

​Next Steps

Add Attack Methods

Contributing

Build docs developers (and LLMs) love

Overview

Directory Layout

Component Breakdown

CLI (`cmd/mmb-cli/`)

Server (`cmd/mmb-server/`)

Core Engine (`internal/`)

Engine (`internal/engine/`)

Attacks (`internal/attacks/`)

Configuration (`internal/config/`)

Network Utilities (`internal/netutil/`)

Proxy Management (`internal/proxy/`)

Shared Packages (`pkg/`)

API Types (`pkg/api/`)

Target Utilities (`pkg/target/`)

Web Client (`web-client/`)

Build System

Build Flow

Data Files

Proxies (`data/proxies.txt`)

User Agents (`data/uas.txt`)

Workflow Diagrams

Attack Execution Flow

Multi-Client Architecture

Development Tips

Adding New Features

Common File Locations

Next Steps