Remote Shell

Execute shell commands on remote agents with support for both streaming and interactive modes:

• Streaming mode: Simple commands and continuous output (default)
• Interactive TTY: Full terminal support for programs like vim, bash, htop

Configuration

shell:
  enabled: false              # Disabled by default (security)
  whitelist: []               # Commands allowed (empty = none, ["*"] = all)
  # whitelist:
  #   - bash
  #   - vim
  #   - whoami
  #   - hostname
  password_hash: ""           # bcrypt hash of shell password
  timeout: 0s                 # Optional command timeout (0 = no timeout)
  max_sessions: 0             # Max concurrent sessions (0 = unlimited)

Generate Password Hash

Use the built-in CLI to generate bcrypt hashes: muti-metroo hash

See CLI - hash for details.

Security Model

1. Command Whitelist: Only whitelisted commands can run

   • Empty list = no commands allowed (default)
   • ["*"] = all commands allowed (testing only!)
   • Commands must be base names only (no paths)

2. Password Authentication: bcrypt-hashed password required when configured

3. Session Limits: Maximum concurrent sessions to prevent resource exhaustion

4. Argument Validation: Dangerous shell metacharacters are blocked

Modes

Streaming Mode (Default)

Non-interactive mode without PTY allocation:

• Separate stdout and stderr streams
• Suitable for simple commands and continuous output
• No terminal control characters

# Simple commands
muti-metroo shell abc123 whoami
muti-metroo shell abc123 ls -la /tmp

# Long-running streaming commands
muti-metroo shell abc123 journalctl -u muti-metroo -f
muti-metroo shell abc123 tail -f /var/log/syslog

Interactive Mode (--tty)

Allocates a PTY (pseudo-terminal) on the remote agent:

• Full terminal emulation
• Supports terminal resize (SIGWINCH)
• Works with interactive programs (vim, less, htop)
• Single combined stdout/stderr stream

muti-metroo shell --tty abc123 bash
muti-metroo shell --tty abc123 vim /etc/config.yaml
muti-metroo shell --tty abc123 htop

CLI Usage

muti-metroo shell [flags] <agent-id> [command] [args...]

# Simple command (streaming mode, default)
muti-metroo shell abc123 whoami

# Follow logs (streaming mode)
muti-metroo shell abc123 journalctl -f

# Interactive bash (requires --tty)
muti-metroo shell --tty abc123 bash

# Interactive vim (requires --tty)
muti-metroo shell --tty abc123 vim /etc/hosts

# With password
muti-metroo shell -p secret abc123 whoami

# Via different agent
muti-metroo shell -a 192.168.1.10:8080 --tty abc123 top

Flags

• -a, --agent: Agent HTTP API address (default: localhost:8080)
• -p, --password: Shell password for authentication
• -t, --timeout: Session timeout in seconds (default: 0 = no timeout)
• --tty: Interactive mode with PTY (for vim, bash, htop, etc.)

WebSocket API

Shell sessions use WebSocket for bidirectional communication.

Endpoint: GET /agents/{agent-id}/shell?mode=tty|stream

See API - Shell for protocol details.

Platform Support

Platform	Interactive (PTY)	Streaming
Linux	Yes	Yes
macOS	Yes	Yes
Windows	Yes (ConPTY)	Yes

Windows PTY

Windows agents use ConPTY (Windows Pseudo Console) for interactive sessions. ConPTY is available on Windows 10 version 1809 and later.

Windows PowerShell Example

Interactive PowerShell session on a Windows target:

muti-metroo shell --tty abc123 powershell

Related

• CLI - Shell - CLI reference
• API - Shell - WebSocket API reference
• Security - Access Control - Whitelist configuration