mikrowizard/terminal-gateway

By mikrowizard

•Updated about 1 month ago

Zero-trust web terminal gateway with policy enforcement & session recording for MikroWizard.

Image

641

Overview Tags

mikrowizard/terminal-gateway repository overview

⁠2. Full Description (Overview / README)

Copy and paste everything below this line into the Full Description markdown editor on Docker Hub:

⁠🖥️ MikroWizard+ Terminal Gateway

MikroWizard+ Terminal Gateway is an enterprise-grade, zero-trust web terminal access gateway and policy enforcement system for MikroWizard. It connects browser sessions to network appliances, servers, and embedded devices (MikroTik RouterOS, Linux, macOS, BSD) with real-time audit logging, multi-user collaboration, and kernel-level command interception.

⁠📌 Architecture Overview

The Terminal Gateway acts as a secure intermediary between the MikroWizard Web Console and target network infrastructure:

┌─────────────────────────┐
│   MikroWizard Backend   │ (Auth, RBAC, Redis Sessions)
└────────────┬────────────┘
             │ Bearer Token REST API (/health, /agent/*)
             ▼
┌─────────────────────────────────────────────────────────────┐
│             MikroWizard+ Terminal Gateway                   │
│         [ mikrowizard/terminal-gateway:latest ]             │
│                                                             │
│  ┌──────────────────────┐      ┌─────────────────────────┐  │
│  │   WebSocket Bridge   │ ───► │  Policy & Audit Engine  │  │
│  │     (xterm.js)       │      │  (Asciinema .cast logs) │  │
│  └──────────────────────┘      └────────────┬────────────┘  │
└─────────────────────────────────────────────┼───────────────┘
                                              │ SSH / Telnet / Agent PTY
                                              ▼
                                 ┌─────────────────────────┐
                                 │   Target Infrastructure │
                                 │  - MikroTik RouterOS    │
                                 │  - Linux / BSD / macOS  │
                                 └─────────────────────────┘

⁠✨ Key Features

🌐 Zero-Client Browser Terminal: Smooth, responsive terminal experience powered by xterm.js over secure WebSockets (wss://).
🛡️ Dual-Tier Policy Enforcement:
- Kernel Tier (Linux): Low-level system-call interception blocking prohibited execve binaries before execution.
- Compatible Tier (macOS / BSD / Generic): High-speed shell hook traps backed by cryptographic tamper monitoring and heartbeat silence detection.
👥 Real-Time Multi-User Collaboration: Shared terminal rooms supporting multiple operators with granular roles (Owner, Collaborator, Observer).
📼 Tamper-Evident Session Recording: Full session keystrokes and visual output recorded in Asciinema v2 (.cast) format.
🔑 Zero-Trust Security: Three independent credential boundaries (Backend ↔ Gateway, Browser ↔ Gateway, Agent ↔ Gateway) with constant-time token validation.
🚀 Native Multi-Arch: Pre-compiled multi-arch binaries supporting linux/amd64 and linux/arm64.

⁠🚀 Quick Start

⁠1-Line Automated Installer (Recommended)

Run the installer on the host where MikroWizard is installed:

curl -fsSL https://raw.githubusercontent.com/MikroWizard/mikrowizard-terminal-gateway/main/install.sh | sudo bash

⁠Docker Run One-Liner

docker run -d --name=mikrowizard-terminal-gateway \
  --network=host \
  -e PORT=8200 \
  -e GATEWAY_TOKEN="your_secure_random_64_character_hex_token" \
  -e GATEWAY_BIND="127.0.0.1" \
  -e AGENT_BIND="127.0.0.1" \
  -e PYSRV_CONFIG_PATH="/opt/mikrowizard/server-conf.json" \
  -e PYSRV_REDIS_HOST="127.0.0.1:6379" \
  -e PYSRV_DATABASE_HOST="127.0.0.1" \
  -e PYSRV_DATABASE_PORT="5432" \
  -e PYSRV_DATABASE_NAME="MIKROMAN" \
  -e PYSRV_DATABASE_USER="mikroman" \
  -e PYSRV_DATABASE_PASSWORD="your_db_password" \
  -e PYSRV_TERMINAL_RECORDINGS_DIR="/opt/mikrowizard/terminal_recordings" \
  -v /opt/mikrowizard:/opt/mikrowizard:rw \
  -v /opt/mikrowizard/terminal_recordings:/opt/mikrowizard/terminal_recordings:rw \
  --restart=unless-stopped \
  mikrowizard/terminal-gateway:latest

⁠Docker Compose

version: '3.8'

services:
  terminal-gateway:
    image: mikrowizard/terminal-gateway:latest
    container_name: mikrowizard-terminal-gateway
    restart: unless-stopped
    network_mode: "host"
    environment:
      - PORT=8200
      - GATEWAY_BIND=127.0.0.1
      - AGENT_BIND=127.0.0.1
      - GATEWAY_TOKEN=${GATEWAY_TOKEN}
      - PYSRV_CONFIG_PATH=/opt/mikrowizard/server-conf.json
      - PYSRV_REDIS_HOST=${PYSRV_REDIS_HOST:-127.0.0.1:6379}
      - PYSRV_DATABASE_HOST=${PYSRV_DATABASE_HOST:-127.0.0.1}
      - PYSRV_DATABASE_PORT=${PYSRV_DATABASE_PORT:-5432}
      - PYSRV_DATABASE_NAME=${PYSRV_DATABASE_NAME:-MIKROMAN}
      - PYSRV_DATABASE_USER=${PYSRV_DATABASE_USER:-mikroman}
      - PYSRV_DATABASE_PASSWORD=${PYSRV_DATABASE_PASSWORD}
      - PYSRV_CRYPT_KEY=${PYSRV_CRYPT_KEY}
      - PYSRV_TERMINAL_RECORDINGS_DIR=/opt/mikrowizard/terminal_recordings
    volumes:
      - /opt/mikrowizard:/opt/mikrowizard:rw
      - /opt/mikrowizard/terminal_recordings:/opt/mikrowizard/terminal_recordings:rw

⁠🏷️ Supported Architectures & Tags

Tag	Architectures	Description
`latest`	`linux/amd64`, `linux/arm64`	Latest stable production release
`v1.0.0`	`linux/amd64`, `linux/arm64`	Version 1.0.0 release

⁠⚙️ Configuration Reference

Environment Variable	Default	Description
`PORT`	`8200`	Gateway WebSocket & HTTP control port
`GATEWAY_BIND`	`127.0.0.1`	IP bind address (`0.0.0.0` for remote deployments)
`GATEWAY_TOKEN`	Required	Shared Bearer token for Backend ↔ Gateway authentication
`AGENT_PORT`	`8201`	HTTP port used by target agents for phone-home verification
`AGENT_BIND`	`127.0.0.1`	Agent HTTP bind address
`PYSRV_CONFIG_PATH`	`/opt/mikrowizard/server-conf.json`	Path to shared configuration file
`PYSRV_TERMINAL_RECORDINGS_DIR`	`/opt/mikrowizard/terminal_recordings`	Directory where session recordings (`.cast`) are saved

⁠🔒 Security Model

Constant-Time Verification: All API tokens are verified via secrets.compare_digest to prevent timing attacks.
Short-Lived Session Tokens: Browser WebSocket connections require single-use tokens issued with a 120-second TTL.
Cryptographic Binary Signing: Ephemeral agents deployed to target devices are signed in memory using Ed25519 cryptography.
Unprivileged Runtime: The container runs under a dedicated, unprivileged service account (gateway, uid 10001).

⁠🏢 Pro & Enterprise Customers: Source Code Access under NDA

Full source code access (including the Python gateway, Go agent sources, and build toolchains) is available to MikroWizard Pro and Enterprise customers under a mutual Non-Disclosure Agreement (NDA) for internal audits, compliance certifications, or air-gapped deployments.

To request source access:

Email our enterprise team at [email protected]⁠.
Include your organization name, MikroWizard license ID, and designated security contact.

⁠🔗 Useful Links

📦 GitHub Installer Repository: https://github.com/MikroWizard/mikrowizard-terminal-gateway⁠
🌐 Official Website: https://mikrowizard.com⁠
🐛 Issue Tracker: GitHub Issues⁠
📧 Enterprise Support: [email protected]⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:b419a3359…

Size

93.4 MB

Last updated

about 1 month ago

docker pull mikrowizard/terminal-gateway