Skip to content

Server

Jump to bottom
katana edited this page May 15, 2026 · 2 revisions

Server

The server runs on the operator machine with root or Administrator privileges. It manages agent connections, installs kernel-level interception rules, and exposes the web dashboard, REST API, and interactive REPL.

Starting the Server

# Linux / macOS

sudo rosemary

or specified key

sudo rosemary -key <base64-key>

# Windows (Administrator)


rosemary-windows-amd64.exe

or specified key

rosemary-windows-amd64.exe -key <base64-key>

# With config file
sudo rosemary -config server.json

CLI Flags

Flag Description
-key Base64url-encoded 32-byte AES-256 key
-port HTTP dashboard port (default 1024)
-agent-port QUIC/UDP agent transport port (default 2048)
-config Path to JSON config file

Default Ports

Service Port
Web dashboard and REST API 1024
QUIC agent transport 2048/udp
TCP transparent proxy 1080
UDP TPROXY 1081
DNS proxy 5300

All ports are configurable via config file or the REPL.

Proxy Listeners

TCP Transparent Proxy (default :1080)

Handles all TCP connections redirected by iptables or WinDivert.

  • Recovers the original destination using SO_ORIGINAL_DST
  • Looks up which agent owns that subnet via longest-prefix match
  • Opens an agent transport stream and sends a connect message
  • Bridges data bidirectionally until the connection closes

UDP TPROXY (default :1081)

Handles UDP datagrams intercepted by iptables TPROXY.

  • Binds with IP_TRANSPARENT and IP_RECVORIGDSTADDR
  • Recovers original destination from ancillary socket data
  • Forwards datagrams to the owning agent
  • Spoofs UDP responses back using a raw socket bound to the original source

DNS Proxy (default :5300)

Intercepts all DNS traffic redirected from port 53.

  • Fans each query out to all connected agents in parallel
  • Returns the first successful answer
  • Falls back to saved system DNS servers and public resolvers (8.8.8.8, 1.1.1.1)
  • Handles both A and AAAA queries

ICMP Interceptor

  • Opens a raw ip4:icmp socket
  • Intercepts echo-request packets marked by iptables
  • Forwards them to the owning agent via icmp_proxy messages
  • Returns echo replies to the original sender

iptables Rules (Linux)

When an agent registers, the server adds iptables rules for each of the agent's subnets:

Protocol Rule
TCP OUTPUT -d <subnet> -j REDIRECT --to-port 1080
UDP OUTPUT -d <subnet> -j MARK + PREROUTING TPROXY --on-port 1081
ICMP OUTPUT -d <subnet> -p icmp -j MARK
DNS OUTPUT -d <subnet> -p udp --dport 53 -j REDIRECT --to-port 5300

Rules are removed automatically when the agent disconnects. A catch-all egress rule is added when a default egress agent is set.

WinDivert (Windows)

On Windows the server embeds WinDivert.dll and WinDivert64.sys directly in the binary. At startup they are extracted to a temporary directory and loaded. WinDivert intercepts packets at the network layer before they leave the machine and redirects them to the appropriate proxy listener.

Agent Connection Limits

  • Maximum 5 simultaneous connections per source IP
  • Maximum 100 total connected agents
  • Per-IP rate limiting on new connections

Interactive REPL

The server exposes a local readline REPL for full control. Type help or help <command> for details.

Agents

agents                          List all connected agents
disconnect <id|all>             Disconnect agent(s)
reconnect <id>                  Force agent to reconnect
connect <ip:port>               Connect to a bind-mode agent

Routing

routes                          Show routing table
egress <id>                     Set default egress agent
egress none                     Clear default egress

Port Forwards

forward add <lport> <id> <host> <port> [tcp|udp]
forward del <id>
forwards                        List active forwards

Reverse Forwards

rforward add <listen-port> <id> <host> <port>
rforward del <id>
rforward list

SOCKS5

socks <id> <port> [user] [pass]
socks list
socks stop <id>

Discovery

ping <id> <target> [count]
discover <id> <subnet> [timeout_ms] [workers]
portscan <id> tcp|udp <target> [ports]

Server Management

settings                        Show current config
verbose                         Toggle debug logging
rotate-key                      Regenerate encryption key
save-config <path>              Export config to JSON
load-config <path>              Import config from JSON
port <n>                        Change HTTP port
tcp-port <n>                    Change TCP proxy port
udp-port <n>                    Change UDP proxy port
dns-port <n>                    Change DNS proxy port
token list|create|view|revoke   Manage API tokens
exit                            Shutdown server

Session Management

  • Dashboard sessions use cookies (tunnel_auth)
  • Sessions expire after 30 minutes of inactivity (configurable)
  • CSRF tokens are required for all state-changing requests, expire after 5 minutes
  • Login is rate-limited with per-IP lockout on repeated failures

Real-Time Dashboard Updates

The server pushes dashboard state to all connected browser clients over a WebSocket at /api/dashboard-ws. Updates are coalesced with a 200ms window to avoid flooding clients during bursts of agent activity.

Use only on systems you own or have explicit written permission to test. Unauthorized use is prohibited.

Clone this wiki locally