1,000,000 stateful TCP flows in 577 MiB (605 B/flow) · Stateful HTTP/2 & QUIC/H3 (io_uring/kTLS) · Consumer GeForce BAR1 P2P CUDA · 5G CUPS Telecom · Native C++17 MCP Server (samurai_mcp)
Samurai (v3.3.1) bridges the gap between scripting load tools (k6, Locust) and raw stateless packet generators (pktgen, TRex) in a single compiled C++17 runtime with zero Python dataplane overhead — strictly scoped for authorized lab and infrastructure validation.
One package (samurai-net) pulls the entire Samurai runtime (CLI, MCP server, samurai_master/samurai_slave, all 10 dataplane workers, and benchmark binaries):
# Option A: Run 1M stateful TCP flows (605 B/flow) via npx (Linux native cache or Docker fallback)
npx -y samurai-net bench 1m-tcp
# Or install all binaries globally into your PATH:
npm install -g samurai-net
# Option B: Direct GHCR container (zero Node.js, zero build)
docker run --rm ghcr.io/mehmet8-dev/samurai:latest samurai_bench_1m_tcp
# Option C: Build natively from source (Linux C++17)
cmake -B build -S samurai -DCMAKE_BUILD_TYPE=Release && cmake --build build -j"$(nproc)"Automatically diagnose binaries and register Samurai MCP across Claude Code, Cursor, Codex, Antigravity, Gemini CLI, Windsurf, VS Code, OpenCode, or Copilot CLI:
# Check binaries, workers, and MCP client registration status
npx -y samurai-net mcp doctor
# Preview (dry-run) and apply MCP registration (creates a .bak backup automatically)
npx -y samurai-net mcp setup --client claude_code --dry-run
npx -y samurai-net mcp setup --client claude_code --yes
# Register via npx or Docker transport (zero local compile; works on macOS / Windows / Linux):
npx -y samurai-net mcp setup --client cursor --npx --yes
npx -y samurai-net mcp setup --client cursor --docker --yes# Stateful HTTP/2 load test against a local lab target (private/loopback only by default)
npx -y samurai-net --worker l7 --target 127.0.0.1 --port 8080 --l7-protocol http2 --concurrency 4 --count 10000 --confirmWhich engine should I pick? Start with
--worker l7(HTTP/1.1, HTTP/2, QUIC/H3) or--worker scenariofor web/API SLA testing; move to--worker afxdp/dpdk/gpufor 10G–100G kernel-bypass or GeForce BAR1 P2P labs; use--worker telcofor 4G/5G core (GTP-U,PFCP,SCTP,Diameter,SIP/SRTP).
- Benchmarks Summary & Tool Comparison —
605 B/flowacross 1M stateful TCP flows (-63.3%RAM),2.71M CPSin-memory /133.5k CPSkernelveth,189.9k RPSstateful HTTP/2, and129.3M masks/sCUDA QUIC offload. - L4 1M Flows Report · L7 Stateful Userspace Report · Reproduce Script (
reproduce-benchmarks.sh)
Samurai includes a modular, zero-Python Model Context Protocol (MCP) stdio server (samurai/mcp/, protocolVersion: 2024-11-05) built directly against samurai_core, samurai_control, and samurai_scenario. It includes built-in doctor and setup subcommands for automatic client diagnostics and registration across 10 AI clients (claude_code, claude_desktop, cursor, codex, gemini_cli, antigravity, windsurf, vscode, opencode, copilot_cli):
# Diagnose local binaries, workers, and MCP client registration status
samurai_mcp doctor --json
# Preview (dry-run) or apply MCP registration (creates a .bak backup automatically)
samurai_mcp setup --client cursor --dry-run
samurai_mcp setup --client cursor --yes # native binary
samurai_mcp setup --client claude_code --docker --yes # or zero-build GHCR container
# Or register directly via Claude Code CLI:
claude mcp add samurai -- /path/to/Samurai/build/mcp/samurai_mcpExposes 22 native tools, 5 MCP Skill Resources (samurai://skills/...), and 5 Workflow Prompts covering:
- Live Target Testing, Benchmarks & RFC Compliance:
samurai_list_workers,samurai_list_profiles,samurai_run_benchmark(all 10 workers, L7/TLS/H2/QUIC, 4G/5G Telco CUPS, GPU BAR1 P2P, live IPFIX, KPI gates),samurai_run_rfc_suite,samurai_bench_tcp_flows,samurai_bench_l7_userspace. - Distributed Cluster & Multi-Worker Orchestration:
samurai_cluster_discover,samurai_cluster_provision_node,samurai_cluster_run_job(distributedsamurai_mastermulti-worker & closed-loop RL job execution),samurai_cluster_plan_shards,samurai_cluster_reconfigure,samurai_cluster_abort, andsamurai_cluster_local_mesh. - Scenario Engine (
samurai_scenario):samurai_scenario_compile,samurai_scenario_run,samurai_scenario_evaluate_sla. - Closed-Loop Autopilot & Mahoraga RL (
samurai_control):samurai_autopilot_create,samurai_autopilot_step,samurai_autopilot_run_window,samurai_autopilot_status,samurai_autopilot_reset— supportingAIMD,BinSearch, in-process SRLP MLP & RL² GRURlPolicyinference,LeverShieldWAF path-block reflex, andRlExploreConfig.
All MCP tools enforce fail-closed target validation (samurai::core::ValidateTargetSafety(..., allow_public=false)) and never expose --allow-public-target. See mcp/README.md for Cursor/Codex configuration and skills/ for all 5 portable agent skills.
Modern infrastructure teams face a gap between low-level stateless packet blasters and high-level application load tools:
- The Problem: Traditional Python/scripting load testers hit GIL, memory-allocation, and syscall bottlenecks long before saturating 10G–100G links; conversely, raw packet generators lack stateful TCP loss recovery, HTTP/2–QUIC/H3 state machines, multi-step persona modeling, carrier-telecom signaling (PFCP/GTP-U/SCTP/Diameter/SIP), or adaptive feedback loops. Many GPU/DPU-accelerated dataplanes also lock developers behind expensive datacenter-only licenses.
- How Samurai Differs:
- Zero Python Dataplane Overhead: Pure C++17 native daemons, MCP server, and worker binaries (
samurai,samurai_mcp,samurai_master,samurai_slave,samurai_*_worker), keeping Python strictly for offline test harnesses and RL training scripts. - Full-Stack L2–L7 + Carrier Telecom in One Runtime: Combines RFC 6675 SACK userspace TCP,
io_uring/kTLS HTTP/2 & QUIC/H3, stateful persona scenarios, and 4G/5G telecom protocols (GTP-U,PFCP,SCTP,Diameter,SIP/RTP/SRTP) with live IPFIX/NetFlow v9/v10 telemetry. - Commodity & Enterprise Hardware Acceleration: Supports consumer GeForce BAR1 P2P DMA + autonomous GPU-initiated doorbells alongside enterprise
AF_XDP,DPDK, and BlueFieldDOCA GPUNetIO+aarch64DPU CUPS Seqlock shared memory. - Closed-Loop Resilience & Safety Gates: Built-in RL (
Mahoraga) / AIMD autopilot, VAE anomaly defense verification, and fail-closedValidateTargetSafetygates (private/loopback by default, explicit allowlist/denylist enforcement).
- Zero Python Dataplane Overhead: Pure C++17 native daemons, MCP server, and worker binaries (
- Pure Native C++17 Runtime: Zero Python runtime overhead; compiled microservice architecture with direct OS and hardware integration.
- Native CLI (
samurai) & MCP Server (samurai_mcp): Argument validation, strict KPI performance gates, RFC 2544/3511/8219 compliance suites, profile management, automatic worker binary discovery, and native MCP2024-11-05agent integration. - Distributed Control Plane (
samurai_master&samurai_slave):- Asynchronous ZMQ ROUTER/DEALER RPC message broker with optional CURVE encryption.
- Dynamic workload sharding (even, capacity-based, and geo-locality aware).
- High Availability (HA) leader election (Static, File-Lease, and Redis).
- Multi-Master and inter-region cluster federation.
- Native POSIX-socket HTTP REST Management API (
:8089). - Cryptographic HMAC-SHA256 JWT authentication and Role-Based Access Control (RBAC).
- Tamper-evident SHA-256 audit logging.
- High-Throughput Dataplane Engines:
- L4 Userspace TCP Stack (
tcp_dataplane_core): 64-shard lock-striped connection flow table, out-of-order reassembly, timer-wheel fast retransmission, and RFC 6675 SACK recovery. - AF_XDP (Kernel-Bypass): Linux XSK / UMEM zero-copy ring buffers delivering wire-rate Mpps throughput.
- DPDK: Poll Mode Driver (PMD) hardware ring acceleration with hugepages.
- GPU CUDA & DOCA GPUNetIO: Warp-parallel packet generation, GeForce BAR1 P2P DMA, and DPU offloaded memory streaming.
- L7 Stateful Emulation (
l7_emu_native): Native HTTP/1.1, HTTP/2 (nghttp2+io_uring/kTLS), QUIC / HTTP/3 (ngtcp2/nghttp3), and DNS engines. - Scenario Engine (
scenario_engine_native): Multi-step persona user emulation, stateful session workflows, and microsecond SLA compliance tracking. - CPU Native Packet Engine (
cpu_native): Raw socket / packet ring optimization with dynamic spoofing and amplification generators.
- L4 Userspace TCP Stack (
System Dataflow Overview
[CLI (`samurai`) / HTTP REST API (`:8089`) / Native MCP (`samurai_mcp`)]
│ (ZMQ / POSIX HTTP / stdio JSON-RPC)
▼
[Master / Slave Control Plane (`samurai_master` / `samurai_slave`)]
│ (ZMQ RPC Wire Protocol)
▼
[Native Worker Orchestrator & Supervisor]
├──> AF_XDP Worker ──────> [Zero-Copy UMEM] ──> [NIC Ring]
├──> DPDK PMD Worker ─────> [Hugepages Ring] ───> [Physical Wire]
├──> GPU / DOCA Worker ───> [VRAM / GPUNetIO] ──> [PCIe Gen4/5 DPU]
├──> L7 Stateful Worker ──> [nghttp2/ngtcp2] ───> [Target App]
├──> Scenario Worker ─────> [Stateful Persona] ─> [Target Service]
└──> Telco Worker ────────> [GTP-U/PFCP/SCTP] ──> [BNG / 5G UPF]
- Operating System: Linux (Ubuntu 22.04+, Debian 12+, RHEL 8+)
- Compiler: GCC 9+ or Clang 10+ (C++17 compliant)
- Build System: CMake 3.16+ and Make / Ninja
- Core Libraries:
libzmq3-dev,libssl-dev,pkg-config,build-essential - Optional Acceleration Drivers:
- AF_XDP:
libbpf-dev,libelf-dev - HTTP/2, QUIC &
io_uring:libnghttp2-dev,libngtcp2-dev,libngtcp2-crypto-gnutls-dev,libnghttp3-dev,libgnutls28-dev,liburing-dev - DPDK:
libdpdk-dev - CUDA: NVIDIA CUDA Toolkit (12.x+)
- AF_XDP:
# Install dependencies (Ubuntu/Debian)
sudo apt update && sudo apt install -y \
build-essential cmake pkg-config libzmq3-dev libssl-dev \
libhiredis-dev libpcap-dev libnghttp2-dev libngtcp2-dev \
libngtcp2-crypto-gnutls-dev libnghttp3-dev libgnutls28-dev liburing-dev
# Configure and build all native targets from repository root
cmake -B build -S samurai -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"The build produces the following native binaries under build/:
build/cli/samurai(Primary CLI tool — auto-discovers worker binaries)build/mcp/samurai_mcp(Native C++17 MCP stdio server)build/control/daemon/samurai_master(Distributed Master daemon)build/control/daemon/samurai_slave(Distributed Worker node daemon)build/zmq/samurai_*_worker(All native dataplane worker engines)build/l4/test_1m_tcp_flows,build/zmq/bench_l7_stateful_userspace(Reproducible L4/L7 benchmark harnesses)build/control/samurai_control_selftest,build/mcp/test_samurai_mcp,build/l7_emu_native/test_*,build/l4/test_*(Native unit and self-test verification suites)
# List built-in corporate L4, L7, and carrier-telecom profiles
./build/cli/samurai --list-profiles
# High-speed UDP packet test via CPU engine (requires CAP_NET_RAW / sudo)
sudo ./build/cli/samurai \
--worker cpu \
--target 127.0.0.1 \
--port 9999 \
--protocol udp \
--count 100000 \
--rps 50000 \
--confirm
# Stateful HTTP/2 load test with KPI pass/fail gate and JSON report
./build/cli/samurai \
--worker l7 \
--target 127.0.0.1 \
--port 8080 \
--l7-protocol http2 \
--concurrency 4 \
--keepalive \
--count 10000 \
--kpi-max-errors 0 \
--report-json reports/h2_run.json \
--confirm
# Carrier 5G telecom simulation (SCTP / Diameter / SIP-SRTP / GTP-U)
./build/cli/samurai \
--worker telco \
--profile telco-sctp-flood \
--target 10.0.0.10 \
--telco-subscribers 500 \
--telco-cps 200 \
--telco-duration-ms 5000 \
--confirm
# RFC 2544 / 3511 / 8219 compliance suite
./build/cli/samurai \
--run-rfc-suite all \
--rfc-report-out reports/rfc_report.htmlScale workloads horizontally across multiple baremetal servers:
./build/control/daemon/samurai_master \
--control-listen tcp://0.0.0.0:5099 \
--management-listen 0.0.0.0:8089 \
--insecure-control \
--target 10.0.0.50 \
--port 443 \
--worker cpu \
--count 500000 \
--expect-workers 2Run on each agent/generator machine:
./build/control/daemon/samurai_slave \
--control-endpoints <MASTER_IP>:5099 \
--dispatch-mode reverse \
--worker bundlePull and run the pre-built multi-stage native runtime image from GitHub Container Registry without compiling locally:
# Pull the latest release image (or pin a version tag such as :v3.3.1)
docker pull ghcr.io/mehmet8-dev/samurai:latest
# Inspect CLI and distributed daemon options
docker run --rm ghcr.io/mehmet8-dev/samurai:latest samurai --help
docker run --rm ghcr.io/mehmet8-dev/samurai:latest samurai_master --help
# Linux: run against a local service on 127.0.0.1 via --network host
docker run --rm --network host ghcr.io/mehmet8-dev/samurai:latest \
samurai --worker l7 --target 127.0.0.1 --port 8080 --l7-protocol http2 --count 1000 --confirm
# macOS / Windows (Docker Desktop): --network host runs inside the Docker VM;
# target services on your host laptop via host.docker.internal instead of 127.0.0.1:
docker run --rm --add-host host.docker.internal:host-gateway ghcr.io/mehmet8-dev/samurai:latest \
samurai --worker l7 --target "$(python3 -c 'import socket; print(socket.gethostbyname("host.docker.internal"))')" --port 8080 --l7-protocol http2 --count 1000 --confirmNote: The container image ships
samurai,samurai_mcp,samurai_master,samurai_slave, reproducible benchmark harnesses (samurai_bench_1m_tcp,samurai_bench_100k_tcp,samurai_bench_l7), and commodity/telco workers (cpu,afpacket,afxdp,l7,scenario,defense,telco) under/usr/local/bin. For CUDA, DOCA GPUNetIO, or hardware DPDK PMD backends, compile natively from source on a Linux host. Seedocs/11-docker.mdfor Docker Desktop networking details.
# Run the 1M active TCP flow benchmark via Docker Compose
docker compose --profile bench run --rm bench
# Launch a distributed Master + 2 Slaves + Redis HA cluster
docker compose -f docker-compose.distributed.yml up -d
curl -s http://127.0.0.1:8089/healthzWorker Name (--worker) |
Native Binary | Capabilities & Acceleration Path |
|---|---|---|
cpu |
samurai_cpu_worker |
Raw sockets, memory ring buffer, dynamic header spoofing |
afpacket |
samurai_afpacket_worker |
Linux AF_PACKET TPACKET_V3 memory-mapped TX rings |
afxdp |
samurai_afxdp_worker |
Linux XSK / UMEM zero-copy kernel bypass |
dpdk |
samurai_dpdk_worker |
DPDK PMD hardware ring buffers and hugepages |
gpu |
samurai_gpu_worker |
NVIDIA CUDA warp-parallel packet synthesis & GeForce BAR1 P2P |
doca |
samurai_doca_worker |
NVIDIA BlueField DPU & GPUNetIO direct VRAM streaming |
l7 |
samurai_l7_worker |
Stateful HTTP/1.1, HTTP/2 (nghttp2), QUIC / HTTP/3 (ngtcp2) |
scenario |
samurai_scenario_worker |
Persona-based multi-step user workflows and SLA tracking |
telco |
samurai_telco_worker |
4G/5G CUPS, PFCP N4, GTP-U, SCTP, Diameter, SIP/RTP/SRTP |
defense |
samurai_defense_worker |
Variational Autoencoder (VAE) resilience evaluation |
Run the built-in C++ validation binaries to verify subsystems in isolated environments:
# Verify Distributed Control Plane, RPC wire protocol, and Native MCP server
./build/control/samurai_control_selftest
./build/mcp/test_samurai_mcp
# Verify L2/L3/ASTF and Stateful L7 Engines
./build/l7_emu_native/test_l2l3_astf
./build/l7_emu_native/test_kernel_threaded_l7
# Verify L4 Userspace TCP Sliding Window, SACK Recovery, and 100k Shard Scaling
./build/l4/test_tcp_sliding_window
./build/l4/test_100k_tcp_flows| Area | Key Guides |
|---|---|
| Architecture | System Overview · Core Runtime Modules · ZMQ Worker & ABI · DPU-GPU CUPS Telecom · GeForce P2P & Doorbell |
| AI Agents & MCP | Native C++17 MCP Server Guide · Portable Agent Skill (SKILL.md) |
| Installation & Setup | Prerequisites & Compilation · DPDK Environment Setup · NUMA & DMA Tuning · Environment & CLI Reference |
| Deployment | Docker & Containers · Distributed Control Plane · Production Operations Runbook · Monitoring & Dashboards · Helm Chart |
| Benchmarking | Benchmarks & Comparison Index · Benchmark Profiles · Benchmark Acceptance Handbook · RFC Baseline Runbook · L4 1M Flows Report · L7 Stateful Report · Reproduce Script |
| Developer Guides | CMake Build & Native Testing · Native Worker API · CLI Deep Map · Target Safety Policy · Open-Source Launch Playbook · Full Docs Index |
This software is strictly intended for network administrators, security researchers, and systems engineers conducting authorized resilience, scalability, and stress assessments on infrastructure they own or hold explicit written permission to test. Unauthorized generation of hostile traffic is illegal under international computer misuse statutes. The end user assumes all legal liability.
For coordinated vulnerability disclosure, supported versions, and secure-by-default controls (target allowlists/denylists, ZMQ CURVE, HMAC-SHA256 JWT RBAC, SHA-256 audit log chains), see SECURITY.md.
- GitHub Discussions: Join architecture discussions, Q&A, RFC reviews, and benchmark sharing at GitHub Discussions.
- Issues & Benchmarks: Use the structured templates in
.github/ISSUE_TEMPLATE/for bug reports, feature requests, new PR proposals, and independent hardware Benchmark Reports.
Contributions are welcome under our CODE_OF_CONDUCT.md. See CONTRIBUTING.md for build instructions, open PR proposals for incoming developers, and .github/PULL_REQUEST_TEMPLATE.md for the PR checklist.
- Mehmet Okur (@Mehmet8-Dev ·
mehmetokur756@gmail.com) — Creator & Lead Architect - 0x4nyroot (@0x4nyroot ·
sefakocyigit10@gmail.com) — Contributor
Samurai is 100% open-source software licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE for the full text.
- Internal Lab, WAF & CI/CD Testing: Running unmodified Samurai against your own servers, staging environments, WAFs, or CI/CD pipelines does not require disclosing your application's source code.
- Custom Plugins, Forks & Managed SaaS: If you modify Samurai and either distribute binaries or operate the modified version over a network as a hosted/managed service or SaaS platform, you must disclose the complete corresponding source code of your Samurai derivative under AGPL-3.0.
- Commercial Licensing & Support: Organizations needing proprietary integration without AGPL-3.0 obligations, dedicated SLA/SLO agreements, or custom engineering can contact the author directly via GitHub (@Mehmet8-Dev) or
mehmetokur756@gmail.com.