If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sammwyy/MikuMikuBeam shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3mo ago
• 7 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sammwyy/MikuMikuBeam repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sammwyy/MikuMikuBeam.

What it runs against: a local clone of sammwyy/MikuMikuBeam — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sammwyy/MikuMikuBeam | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 108 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sammwyy/MikuMikuBeam. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sammwyy/MikuMikuBeam.git
#   cd MikuMikuBeam
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sammwyy/MikuMikuBeam and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sammwyy/MikuMikuBeam(\\.git)?\\b" \\
  && ok "origin remote is sammwyy/MikuMikuBeam" \\
  || miss "origin remote is not sammwyy/MikuMikuBeam (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/mmb-server/main.go" \\
  && ok "cmd/mmb-server/main.go" \\
  || miss "missing critical file: cmd/mmb-server/main.go"
test -f "internal/engine/engine.go" \\
  && ok "internal/engine/engine.go" \\
  || miss "missing critical file: internal/engine/engine.go"
test -f "internal/engine/registry.go" \\
  && ok "internal/engine/registry.go" \\
  || miss "missing critical file: internal/engine/registry.go"
test -f "pkg/api/types.go" \\
  && ok "pkg/api/types.go" \\
  || miss "missing critical file: pkg/api/types.go"
test -f "internal/config/config.go" \\
  && ok "internal/config/config.go" \\
  || miss "missing critical file: internal/config/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 108 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~78d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sammwyy/MikuMikuBeam"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MikuMikuBeam is an open-source network stress-testing tool with a Miku-themed web UI that lets you launch HTTP flood, HTTP bypass, slowloris, TCP flood, and Minecraft ping attacks against target servers. It provides real-time attack visualization via Socket.IO, a Go backend engine with multi-threaded goroutine-based attack handling, and both a React web client and CLI interface for orchestrating coordinated traffic. Monolithic Go + TypeScript hybrid: cmd/ contains two entry points (mmb-cli and mmb-server), internal/ houses the attack engine with organized subdirectories by attack type (http/, tcp/, game/), pkg/ contains shared types and node management, and web-client/ is a separate React/TypeScript SPA that communicates to the server via Socket.IO and REST endpoints.

Security researchers, penetration testers, and network engineers who want to benchmark server resilience or conduct authorized stress tests, particularly those who appreciate anime aesthetics and want a fun, visually engaging interface for orchestrating attacks.

Actively developed but pre-production: the project has a functional Docker setup (Dockerfile implied by README), CI via GitHub Actions (.github/workflows/pr-quality.yml), and structured code organization, but no visible test suite in the file list and appears to be a single-maintainer project (sammwyy). Suitable for learning and controlled testing, not for high-stakes production deployments.

Moderate risk: the codebase has a lean dependency tree (Cobra, Echo, Socket.IO, zerolog) which is positive, but there are no tests visible, and this is a security-sensitive tool (network attacks) with potential for misuse. Single maintainer increases bus-factor risk. Proxy support via h12.io/socks and custom HTTP dialers (internal/netutil/) add complexity that needs careful review.

No specific PR or milestone data visible in the file list provided. The project structure suggests recent work on proxy loading (internal/proxy/loader.go), attack registry (internal/engine/registry.go), and web client configuration management, but commit recency and open issues are not available in this snapshot.

git clone https://github.com/sammwyy/MikuMikuBeam.git
cd MikuMikuBeam
cd web-client && npm install && cd ..
make

(Verify Makefile for exact build targets; Go 1.24.5+ required per go.mod)

Daily commands:

make
./bin/mmb-server          # Starts web server on default port (check cmd/mmb-server/main.go)
./bin/mmb-cli --help      # CLI mode with --verbose, --no-proxy, --threads flags

For dev web client: cd web-client && npm run dev (inferred from package.json presence and TypeScript setup).

• cmd/mmb-server/main.go — Entry point for the server; initializes the Echo HTTP framework, WebSocket handlers, and attack engine—all contributors must understand the server bootstrap sequence.
• internal/engine/engine.go — Core attack orchestration engine that manages goroutines, marshals attack execution, and coordinates with attack implementations—critical for understanding how attacks are dispatched and monitored.
• internal/engine/registry.go — Attack type registration system that maps attack identifiers to their implementations; essential for adding new attack methods.
• pkg/api/types.go — API contract definitions (request/response structs) shared between server and web client; any protocol change requires updates here.
• internal/config/config.go — Configuration loading and validation from TOML; defines default parameters for all attack modules and proxy settings.
• web-client/src/lib/mmb-client.ts — WebSocket client library that communicates with the server; required for understanding real-time attack progress updates.
• internal/attacks/http/flood.go — HTTP flood attack implementation demonstrating the pattern all attack modules follow; reference architecture for new attack types.

Add a New Attack Type

1. Create a new attack module in internal/attacks/{protocol}/ directory (e.g., internal/attacks/udp/flood.go) (internal/attacks/udp/flood.go)
2. Implement the attack struct and Execute() method following the pattern in internal/attacks/http/flood.go; it must accept Engine context and return (packets, success, error) (internal/attacks/http/flood.go)
3. Register the attack type in the registry by adding an init() function that calls engine.Register() with the attack key and constructor (internal/engine/registry.go)
4. Add attack parameters to the config.go defaults struct under [attacks.{protocol}] if needed (internal/config/config.go)
5. Update the web client form in web-client/src/App.tsx to include the new attack option in the method dropdown (web-client/src/App.tsx)

Add a New Web Client UI Component

1. Create a new React component file in web-client/src/ (e.g., web-client/src/AttackStats.tsx) using TypeScript and Tailwind CSS (web-client/src/App.tsx)
2. Import the component in web-client/src/App.tsx and integrate it into the main render flow (web-client/src/App.tsx)
3. Use the mmb-client WebSocket connection from web-client/src/lib/mmb-client.ts to subscribe to attack events (web-client/src/lib/mmb-client.ts)
4. Style using Tailwind classes consistent with web-client/src/index.css and the existing Miku theme (web-client/src/index.css)

Add a New API Endpoint

1. Define the request/response struct in pkg/api/types.go with JSON tags matching the desired endpoint contract (pkg/api/types.go)
2. Add a handler function in cmd/mmb-server/main.go that receives Echo context, parses the request, and calls engine.ExecuteAttack() (cmd/mmb-server/main.go)
3. Register the route in cmd/mmb-server/main.go using e.POST() or e.GET() with the handler function (cmd/mmb-server/main.go)
4. Update web-client/src/lib/mmb-client.ts to add a method that invokes the new endpoint over WebSocket or HTTP (web-client/src/lib/mmb-client.ts)

Add Proxy Support to an Attack

1. Update the attack struct in the target attack file (e.g., internal/attacks/http/flood.go) to include a Proxy field (internal/attacks/http/flood.go)
2. Use internal/netutil/httpdial.go (for HTTP) or internal/netutil/tcpdial.go (for TCP) to inject proxy credentials into the dialer (internal/netutil/httpdial.go)
3. Load proxy list in cmd/mmb-server/main.go via internal/proxy/loader.go and pass to the attack instance (internal/proxy/loader.go)
4. Add proxy configuration section to internal/config/config.go under [proxy] and expose via web client form (internal/config/config.go)

• Go + Echo Framework — High-performance concurrent HTTP/WebSocket server; goroutines enable thousands of simultaneous attack packets with minimal overhead; Echo provides routing and middleware
• WebSocket (socket.io) — Persistent bidirectional connection for real-time attack progress updates; allows server to push stats to all connected clients without polling
• React + TypeScript + Vite — Modern UI framework for interactive attack dashboard; TypeScript prevents runtime errors; Vite provides fast HMR for frontend development
• TOML Configuration — Human-readable config files for default attack parameters, proxy settings, and server binding without code recompilation
• SOCKS5 Proxy Support — Allows distributed attacks via proxy rotation; integrates at the TCP/HTTP dialer level for transparent proxy injection
• Zerolog Structured Logging — Low-overhead JSON logging for attack telemetry, diagnostics, and audit trails; enables log aggregation for distributed deployments

• Single-binary server architecture (no microservices
  • Why: undefined
  • Consequence: undefined

1. Proxy configuration: The internal/proxy/loader.go expects proxy lists in a specific format (inferred from h12.io/socks SOCKS protocol); invalid proxies will silently fail unless --verbose logging is enabled. 2. Socket.IO version pinning: github.com/zishang520/socket.io v1.3.2 is a specific fork; mixing with different Socket.IO client versions in web-client may cause handshake failures. 3. No config file in repo: internal/config/config.go exists but the Makefile and README don't document where config is loaded from (likely environment variables or CLI flags); check main.go for initialization. 4. Attack concurrency limits: No visible rate-limiting or resource pooling; launching many concurrent attacks may exhaust file descriptors or memory without bounds.

• Slowloris attack — MikuMikuBeam implements this DoS technique in internal/attacks/http/slowloris.go; understanding how it exploits HTTP/1.1 connection pooling is critical to responsible use
• Socket.IO bidirectional real-time communication — The web client and server exchange attack stats and commands via Socket.IO; understanding event emission and namespacing is essential for modifying the UI or server behavior
• SOCKS proxy protocol — MikuMikuBeam routes attacks through SOCKS proxies via h12.io/socks; knowing SOCKS5 vs SOCKS4 differences helps debug proxy-related attack failures
• Goroutine-based concurrency model — The engine in internal/engine/engine.go spawns thousands of goroutines for concurrent packet sending; understanding Go's M:N threading and channel communication is needed for performance tuning
• HTTP request spoofing (User-Agent, headers, redirects) — internal/attacks/http/bypass.go mimics legitimate browser traffic to evade basic WAF rules; understanding HTTP header injection and redirect following is needed to extend bypass techniques
• Minecraft protocol ping/MOTD — MikuMikuBeam includes Minecraft-specific DoS in internal/attacks/game/minecraft_ping.go; the Minecraft handshake protocol differs from standard TCP/HTTP and requires careful packet structure
• TCP SYN flood vs. connection-based attacks — internal/attacks/tcp/flood.go likely sends complete TCP connections rather than raw SYN packets due to Go socket limitations; understanding the difference affects observed impact on target servers

• OISF/suricata — Enterprise-grade network security monitoring; complements MikuMikuBeam for detecting and analyzing attack traffic
• projectdiscovery/nuclei — Template-driven vulnerability scanner in Go; similar CLI-first architecture and multi-threaded execution model
• owasp-amass/amass — Go-based network reconnaissance tool with similar multi-threaded goroutine patterns and proxy support
• apache/ab — Classic Apache HTTP benchmark tool; direct predecessor/alternative for HTTP flood functionality
• wg/wrk — Modern HTTP load testing tool written in C; alternative stress-testing solution with Lua scripting for custom payloads

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for internal/attacks packages (HTTP, TCP, Game protocols)

The repo has three attack modules (HTTP flood/slowloris/bypass, TCP flood, Minecraft ping) but no visible test files (*_test.go). Given the security-sensitive nature of this tool and the complexity of network protocols, integration tests would validate attack accuracy, prevent regressions, and improve code reliability. This is a high-value contribution for a network tool.

• [ ] Create internal/attacks/http/flood_test.go with table-driven tests for HTTP flood logic (various payload sizes, concurrent requests)
• [ ] Create internal/attacks/tcp/flood_test.go to validate TCP packet generation and connection handling
• [ ] Create internal/attacks/game/minecraft_ping_test.go to verify protocol compliance with Minecraft ping format
• [ ] Update Makefile with 'make test' target to run all *_test.go files
• [ ] Add test coverage reporting via 'go test -cover ./...' in CI workflow

Implement Go CLI argument validation and error handling in cmd/mmb-cli/main.go

The CLI entrypoint exists but the file structure suggests minimal validation. Given that mmb-cli likely accepts attack parameters (target, duration, packet size, etc.), adding robust argument parsing with Cobra subcommands and comprehensive error messages would improve UX and prevent malformed attacks. The repo already depends on Cobra but likely underutilizes it.

• [ ] Refactor cmd/mmb-cli/main.go to define Cobra RootCmd with subcommands: 'attack', 'config', 'status'
• [ ] Add argument validators in Cobra PreRunE hooks to validate IP/domain targets, numeric parameters (duration > 0, packet size > 0)
• [ ] Implement config file loading from --config flag using internal/config/config.go
• [ ] Add --help and example usage documentation for each subcommand
• [ ] Return non-zero exit codes on validation failures for proper shell scripting integration

Add comprehensive E2E test workflow in .github/workflows for web-client + mmb-server interaction

The repo has a pr-quality.yml workflow but no visible E2E tests validating that the web-client (TypeScript/React) correctly communicates with mmb-server (Go) via the Socket.IO API (pkg/api/types.go). Given the architecture spans two languages and uses WebSockets, E2E tests prevent integration regressions and ensure the frontend-backend contract stays valid.

• [ ] Create .github/workflows/e2e-test.yml that builds mmb-server and web-client in sequence
• [ ] Start mmb-server on localhost:3000 and wait for health check endpoint (add simple GET /health if missing)
• [ ] Run Playwright/Cypress tests from web-client directory to verify: page loads, Socket.IO connects, can submit attack form
• [ ] Add simple E2E test file (e.g., web-client/tests/attack-flow.spec.ts) that validates connect → config attack → start → receive stats updates
• [ ] Ensure workflow runs on pull_request events and gates PR merging on success

• Add unit tests for internal/attacks/tcp/flood.go and internal/attacks/http/slowloris.go; currently no test files visible in the attacks subdirectories despite the engine being testable
• Document the Socket.IO event protocol between server and web client; create a file docs/socket-io-protocol.md with event names, payloads, and expected responses (inferred from web-client consuming attack stats)
• Add a --config-file flag to mmb-cli that reads attack parameters from a TOML file (leveraging existing github.com/pelletier/go-toml/v2 dependency); currently only CLI flags are supported per README

• High · Denial of Service (DoS) Tool Without Authentication — cmd/mmb-server/main.go, pkg/api/types.go, web-client/src/lib/mmb-client.ts. The application is a network stress testing tool that lacks any authentication or authorization mechanisms. The web client and server accept attack commands from any client without verifying identity or permissions. This allows unauthorized users to launch attacks against arbitrary targets. Fix: Implement JWT-based authentication, API key validation, or OAuth2. Add role-based access control (RBAC) to restrict who can configure and execute attacks. Use TLS/HTTPS for all communications.
• High · Unvalidated Target Specification — pkg/target/node.go, pkg/api/types.go. The application allows clients to specify arbitrary target hosts/IPs for attacks without validation. No checks are performed to prevent attacks against internal infrastructure, private IP ranges, or unauthorized targets. This could enable internal network reconnaissance and attacks. Fix: Implement target validation: whitelist allowed targets, block private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8), validate DNS resolution, and log all target requests.
• High · Outdated JWT Library (Vulnerable) — go.mod (indirect dependency via labstack/echo/v4). The dependency 'github.com/golang-jwt/jwt v3.2.2+incompatible' is marked as incompatible and outdated. This version may contain known security vulnerabilities in JWT signature verification. Fix: Update to golang-jwt/jwt v4.x or v5.x. Review the changelog for security fixes: https://github.com/golang-jwt/jwt/releases
• Medium · No CORS Security Configuration — cmd/mmb-server/main.go, internal/engine/engine.go. The web client makes API calls to the server, but there is no evidence of CORS (Cross-Origin Resource Sharing) security headers configured in the Echo server. This could allow cross-origin attacks or unintended access from external domains. Fix: Implement strict CORS policies: specify allowed origins explicitly, restrict HTTP methods, and set Access-Control-Allow-Credentials appropriately using Echo middleware.
• Medium · No Rate Limiting on Attack Endpoints — internal/engine/engine.go, cmd/mmb-server/main.go. The server has no visible rate limiting mechanism on attack initiation endpoints. A malicious user could rapidly spawn attack goroutines, exhausting system resources (memory, CPU, file descriptors) on the server itself. Fix: Implement rate limiting per IP/session using Echo middleware. Set maximum concurrent attacks, attack duration limits, and request throttling.
• Medium · SOCKS Proxy Support Without Validation — internal/proxy/loader.go, h12.io/socks dependency. The codebase includes SOCKS proxy support (h12.io/socks). Without proper validation, this could allow attackers to proxy attacks through the server to obscure their origin or chain attacks. Fix: Implement strict proxy validation: whitelist approved proxies, log all proxy usage, implement audit trails, and disable proxy support if not essential.
• Medium · No Input Validation on Attack Parameters — internal/attacks/http/flood.go, internal/attacks/tcp/flood.go, pkg/api/types.go. Attack parameters (duration, packet size, packet delay) are accepted from the frontend without visible validation. Malformed inputs could cause crashes, integer overflows, or resource exhaustion. Fix: Validate all input parameters: enforce minimum/maximum values, validate numeric types, implement bounds checking, and use safe type conversions.
• Medium · Cleartext Communication Possible — pkg/api/types.go, web-client/src/lib/mmb-client.ts. The application uses Socket.IO and HTTP (likely unencrypted). Real-time attack data and configuration could be transmitted in plaintext, allowing packet sniffing and man-in-the-middle attacks. Fix: Enforce TLS/HTTPS for all connections. Configure WSS (WebSocket Secure) instead of WS. Use modern T

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.