DEV Community

Cover image for Rosemary: Multi-Hop Pivoting Tutorial
blue0x1
blue0x1

Posted on • Originally published at Medium

Rosemary: Multi-Hop Pivoting Tutorial

#networking

Learn how to chain multiple Rosemary agents to reach deeply nested networks.

Overview

Multi-hop pivoting allows you to reach networks that are several layers deep. Each agent connects through the previous one, forming a chain that extends your reach hop by hop.

Because the agent transport now runs over QUIC/UDP on port 2048, every link in the chain is a UDP forward to the previous hop's agent port (2048), not a TCP forward to the dashboard.

In this tutorial, you will chain 5 agents across different operating systems:

  • FreeBSD (Server)
  • Windows (Agent)
  • macOS (Agent)
  • Linux (Agent)
  • Linux (Agent)
  • HTB Machine (Agent)

Network Topology

[Server]         [Agent 2]        [Agent 4→6]      [Agent 8]         [Agent 12]        [Agent 14]
FreeBSD           Windows          macOS             Linux             Linux             HTB Machine
172.16.54.186     172.16.54.0/24   172.16.126.0/24  172.14.1.0/24     172.16.19.0/24    172.20.1.0/24
                  1025/udp ──────► 1026/udp ──────► 1027/udp ──────► 1028/udp ──────► 192.168.3.0/24
                                                                                        10.10.10.0/24
Enter fullscreen mode Exit fullscreen mode

Step-by-Step

Step 1: Start Server (FreeBSD)

sudo ./rosemary-freebsd-amd64
Enter fullscreen mode Exit fullscreen mode

Output:

Server login key: 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Server IPs: [172.16.54.186]
Dashboard: http://0.0.0.0:1024
Agent transport (QUIC): 0.0.0.0:2048/udp
Enter fullscreen mode Exit fullscreen mode

Step 2: Agent 2 - Windows (Direct to Server)

./agent-windows-amd64.exe -s 172.16.54.186:2048 -k 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Enter fullscreen mode Exit fullscreen mode

Server output:

[+] Agent agent-2 connected with subnets: [172.16.126.0/24 172.16.54.0/24]
Enter fullscreen mode Exit fullscreen mode

Step 3: Create Forward for Hop 1 (Server → Windows → macOS)

rosemary> forward add 1025 agent-2 172.16.54.186 2048 udp
Enter fullscreen mode Exit fullscreen mode

This makes the Windows agent listen on UDP port 1025 and forward QUIC datagrams to the server's agent transport on 2048/udp.

Step 4: Agent 4 → 6 - macOS (Through Windows)

./agent-darwin-amd64 -s 172.16.126.135:1025 -k 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Enter fullscreen mode Exit fullscreen mode

Server output:

[+] Agent agent-4 connected with subnets: [172.16.126.0/24]
Enter fullscreen mode Exit fullscreen mode

Step 5: Reconnect Agent to Discover More Subnets

rosemary> reconnect agent-4
Enter fullscreen mode Exit fullscreen mode

Output:

[-] Agent agent-4 disconnected and removed.
[+] Agent agent-6 connected with subnets: [172.16.126.0/24 172.14.1.0/24]
Enter fullscreen mode Exit fullscreen mode

Step 6: Create Forward for Hop 2 (Server → Windows → macOS → Linux)

rosemary> forward add 1026 agent-6 172.16.126.135 1025 udp
Enter fullscreen mode Exit fullscreen mode

Step 7: Agent 8 - Linux (Through macOS)

./agent-linux-amd64 -s 172.14.1.132:1026 -k 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Enter fullscreen mode Exit fullscreen mode

Server output:

[+] Agent agent-8 connected with subnets: [172.14.1.0/24 172.16.19.0/24]
Enter fullscreen mode Exit fullscreen mode

Step 8: Create Forward for Hop 3 (Server → Windows → macOS → Linux → Linux)

rosemary> forward add 1027 agent-8 172.14.1.132 1026 udp
Enter fullscreen mode Exit fullscreen mode

Step 9: Agent 12 - Second Linux (Through First Linux)

./agent-linux-amd64 -s 172.16.19.136:1027 -k 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Enter fullscreen mode Exit fullscreen mode

Server output:

[+] Agent agent-12 connected with subnets: [192.168.1.0/24 172.17.0.0/16 172.16.54.0/24 ...]
Enter fullscreen mode Exit fullscreen mode

Step 10: Create Forward for Hop 4 (Server → ... → HTB Machine)

rosemary> forward add 1028 agent-12 172.16.19.136 1027 udp
Enter fullscreen mode Exit fullscreen mode

Step 11: Agent 14 - HTB Machine (Final Hop)

./agent-linux-amd64 -s 10.10.14.72:1028 -k 1RzWoufxJG86g9qWi9tQtyjV4IbwTmoptojWykBCyFs=
Enter fullscreen mode Exit fullscreen mode

Server output:

[+] Agent agent-14 connected with subnets: [172.20.1.0/24 192.168.3.0/24 10.10.10.0/24]
Enter fullscreen mode Exit fullscreen mode

Step 12: Access Deepest Network

From the server (FreeBSD), you can now directly access the HTB machine's internal networks:

curl http://192.168.3.1/login.php
Enter fullscreen mode Exit fullscreen mode

Success! The router login page from 5 hops away loads directly on the server.

Accessing through web browser

accessing browser

The Rosemary dashboard graph view automatically lays out all connected agents and their subnet relationships. After completing the 5-hop chain, the graph shows all hops.

rosemary graph

Complete Forward Chain

Hop Agent OS Listen Port Target Proto
1 agent-2 Windows 1025 Server:2048 udp
2 agent-6 macOS 1026 172.16.126.135:1025 udp
3 agent-8 Linux 1027 172.14.1.132:1026 udp
4 agent-12 Linux 1028 172.16.19.136:1027 udp
5 agent-14 Linux (HTB) - Direct to server chain -

Verification

rosemary> agents
Enter fullscreen mode Exit fullscreen mode

All 5 agents connected:

ID         OS       Subnets
agent-2    windows  172.16.126.0/24, 172.16.54.0/24
agent-6    darwin   172.16.126.0/24, 172.14.1.0/24
agent-8    linux    172.14.1.0/24, 172.16.19.0/24
agent-12   linux    192.168.1.0/24, 172.17.0.0/16, ...
agent-14   linux    172.20.1.0/24, 192.168.3.0/24, 10.10.10.0/24
Enter fullscreen mode Exit fullscreen mode

Key Points

  • Each hop uses forward add ... udp to chain QUIC traffic to the next agent's transport port.
  • The first hop targets the server's agent transport on 2048/udp; every subsequent hop targets the previous hop's listen port.
  • reconnect forces subnet re-discovery when an agent has multiple interfaces.
  • Traffic flows transparently through all hops over QUIC.
  • The final agent (HTB machine) provides access to 192.168.3.0/24 and 10.10.10.0/24.

Rosemary is open-source under GPL-3.0. Use only on systems you own or have explicit permission to test.

Top comments (0)