Make your first map · ShellGraph

Start a lab of three servers on your computer, scan it and read its map. The last step marks the load balancer as internet facing.

The lab is a set of Podman containers on your computer: a load balancer, an application and a database, each with an SSH server. It also has an OpenLDAP server for the login. You need approximately 15 minutes.

Before you start

Make sure that your Linux computer has Podman, and Go 1.27, Node.js 24 and pnpm 11 to build ShellGraph.

Clone the repositories in the same directory.

git clone https://git.rda.run/shellgraph/server.git
git clone https://git.rda.run/shellgraph/collector.git

Build ShellGraph

Build the server image.
```
make -C server image
```
Build the collector for your computer.
```
make -C collector build-local
```

Start the lab

Go to the lab directory.
```
cd collector/testlab
```
Start the containers.
```
./lab.sh up
```
The last line is Lab is up. UI: http://127.0.0.1:8088.

The lab has these containers:

Container	Address	Function
`sg-lb`	10.89.70.10	haproxy on port 80. It sends the requests to the application.
`sg-app`	10.89.70.11	An application on port 8080 (`socat`), and a client of the database (`psql`).
`sg-db`	10.89.70.12	PostgreSQL on port 5432.
`sg-server`	10.89.70.5	`shellgraph-server`.
`sg-collector`	10.89.70.30	The collector.

Register the lab in the server

Run the setup command:

./lab.sh setup

The command logs in as alice and adds:

The Environment “Lab”.
A credential with the SSH key of the lab.
The VLAN “lab-net” (10.89.70.0/24).
Three tag rules: lb gives “Load Balancer”, app gives “Application” and db gives “Database”.
A collector token. Then it logs in the collector with the token.

Look at the Environment

Open http://127.0.0.1:8088 in your browser.
Log in with the login alice and the password alice-lab-pass.
The Environments page shows the Environment “Lab”, with 1 VLAN and 0 hosts.
Select Lab.
The VLANs tab shows the VLAN “lab-net” and the command that scans it.

Scan the VLAN

Run the scan command:

./lab.sh scan

The collector tests the 254 addresses of the VLAN. It collects the three servers that have SSH:

Scanning Lab / lab-net (10.89.70.0/24) with user "shellgraph"...
  10.89.70.11     ok       app, 3 services
  10.89.70.10     ok       lb, 2 services
  10.89.70.12     ok       db, 2 services
Done: 3 ok, 0 partial, 0 auth_failed, 0 hostkey_changed, 0 error, 251 no_ssh.

Read the map

In the browser, open the Environment “Lab” again.
Select Open map.

The map has three colored groups, one for each tag. Each group has one host, and each host has its services:

haproxy on lb calls socat on app, port 8080.
psql on app calls postgres on db, port 5432.

The small boxes :8080 and :5432 are the ports where the services listen. Each arrow goes from the caller to the port.

Select the socat service.
The other nodes become pale. The panel on the right shows Called by: haproxy on lb.

Mark the load balancer as internet facing

Clients from the Internet connect to the load balancer. In the lab, the client is in the same network, so ShellGraph has no way to know that it is an Internet client. You tell it.

Select the haproxy service.
In the panel, select Rename or set internet facing.
In Display name, type Edge proxy.
Set Internet facing to on.
Select Save.

The map now shows the Internet node, with an arrow to Edge proxy on port 80. The Edge proxy box has a thick blue border.

Remove the lab

When you do not need the lab, remove it:

./lab.sh down

Next steps

For your own servers, continue with these pages: