When navigating into a subfolder elFinder removes tree nodes for any directory not present in the files array. Include all ancestor path entries so the sidebar tree stays populated.
TailScan
A fast LAN scanner that runs on your Tailscale network. Connect to an exit node and scan what's on its local network — from anywhere.
Docker project. The recommended way to run TailScan is via Docker Compose. Manual/bare-metal setup is possible but not the primary path.
What it does
- Connects to any Tailscale exit node
- Discovers all live hosts using fping (~10s for a /24)
- Scans 118 common ports per host using nmap (~1s per host)
- Proxies web UIs directly through the exit node — SPA-aware
- Caches scan results per network for instant page loads
- Guacamole integration — SSH, RDP, and VNC sessions direct from the browser (green chips)
- Copyparty file server support (orange chips, browsable)
- File transfer protocol detection (SMB, FTP, NFS, rsync, AFP — orange chips)
- Theme switcher — Dark Slate and Rosé Pine (persists via localStorage)
Stack
- Python 3 / FastAPI / uvicorn
- fping — host discovery via ICMP
- nmap — TCP connect port scan, no root required (
-sT) - httpx — async HTTP for reverse proxy and WAN geo lookup
- Apache Guacamole — browser-based SSH/RDP/VNC client
- Tailscale — peer list and exit node control via
tailscale status --json
Port chip colors
| Color | Meaning |
|---|---|
| 🔵 Blue | Web UI — click to open via proxy |
| 🟢 Green | SSH / RDP / VNC — click to open in Guacamole |
| 🟠 Orange | File transfer (Copyparty, SMB, FTP, NFS, rsync, AFP) |
| ⚫ Grey | Open port, no web UI |
Scanned Ports (118 total)
| Port | Service | Port | Service | Port | Service |
|---|---|---|---|---|---|
21 |
FTP | 22 |
SSH | 23 |
Telnet |
25 |
SMTP | 53 |
DNS | 67 |
DHCP |
69 |
TFTP | 80 |
HTTP | 110 |
POP3 |
111 |
RPC/NFS | 123 |
NTP | 137 |
NetBIOS-NS |
139 |
NetBIOS-SSN | 143 |
IMAP | 161 |
SNMP |
179 |
BGP | 389 |
LDAP | 443 |
HTTPS |
445 |
SMB | 465 |
SMTPS | 514 |
Syslog |
515 |
LPD (Print) | 548 |
AFP | 554 |
RTSP |
587 |
SMTP submission | 623 |
IPMI/iDRAC | 631 |
IPP (Print) |
636 |
LDAPS | 873 |
rsync | 902 |
VMware |
993 |
IMAPS | 995 |
POP3S | 1194 |
OpenVPN |
1400 |
Sonos | 1433 |
MSSQL | 1521 |
Oracle DB |
1880 |
Node-RED | 1883 |
MQTT | 2049 |
NFS |
2375 |
Docker ⚠️ | 2376 |
Docker TLS | 2379 |
etcd |
2380 |
etcd peer | 3000 |
Grafana/Node | 3001 |
Grafana-alt |
3306 |
MySQL/MariaDB | 3389 |
RDP | 3478 |
STUN/TURN |
3923 |
Copyparty | 4000 |
HTTP-alt | 4040 |
ngrok |
4200 |
Angular dev | 4500 |
IPSec NAT-T | 4848 |
GlassFish |
5000 |
Synology DSM | 5001 |
Synology HTTPS | 5055 |
Overseerr |
5222 |
XMPP | 5269 |
XMPP S2S | 5280 |
XMPP HTTP |
5299 |
Ombi | 5349 |
STUN/TURN TLS | 5432 |
PostgreSQL |
5433 |
PostgreSQL-alt | 5900 |
VNC | 5901 |
VNC :1 |
5902 |
VNC :2 | 5903 |
VNC :3 | 6379 |
Redis |
6380 |
Redis-alt | 6443 |
k8s API | 6881 |
BitTorrent |
7000 |
HTTP-alt | 7001 |
HTTP-alt | 7474 |
Neo4j |
7878 |
Radarr | 8006 |
Proxmox | 8007 |
Proxmox SPICE |
8080 |
HTTP-alt | 8081 |
HTTP-alt 2 | 8082 |
HTTP-alt 3 |
8086 |
InfluxDB | 8087 |
InfluxDB-alt | 8090 |
HTTP-alt 4 |
8096 |
Jellyfin | 8097 |
Jellyfin HTTPS | 8112 |
Deluge |
8123 |
Home Assistant | 8200 |
Synology Video | 8443 |
HTTPS-alt |
8448 |
Matrix federation | 8686 |
Lidarr | 8787 |
Readarr |
8883 |
MQTT TLS | 8888 |
Jupyter | 8920 |
Jellyfin-alt |
8989 |
Sonarr | 9000 |
Portainer | 9042 |
Cassandra |
9090 |
Prometheus/Cockpit | 9091 |
Transmission | 9100 |
Node Exporter |
9117 |
Jackett | 9200 |
Elasticsearch | 9300 |
ES cluster |
9393 |
Scrutiny | 9443 |
Portainer HTTPS | 9696 |
Prowlarr |
9999 |
HTTP-alt | 10000 |
Webmin | 10250 |
kubelet |
10255 |
kubelet read-only | 27017 |
MongoDB | 27018 |
MongoDB-alt |
30266 |
Copyparty-alt | 32400 |
Plex | 32469 |
Plex DLNA |
51413 |
Transmission torrent |
How it works
Host discovery
fping -a -g <subnet> — parallel ICMP pings, streams responding IPs as they reply. ~9s for a /24. No ARP (traffic goes over the Tailscale tunnel).
Subnet detection
Reads the active exit node's AllowedIPs from tailscale status --json, filters for private RFC-1918 ranges. Falls back to ip route if no AllowedIPs found. Supports multiple subnets.
Port scanning
nmap -sT --open -T5 -p<ports> — TCP connect scan, ~1s per host. TailScan's own PORT_NAMES table always wins over nmap's service guesses for accurate labelling.
Reverse proxy
/proxy?t=http://ip:port/path — fetches from the LAN via the exit node. Rewrites HTML href/src/action/srcset, rewrites Location redirect headers, and injects a JS interceptor for SPA routing (fetch, XHR, history, link clicks, form submit). Known limitation: complex SPAs (TrueNAS, some *arr post-login pages) may still break.
Guacamole integration
Green chips (SSH port 22, RDP port 3389, VNC ports 5900–5903) call /api/guac-connect which creates (or reuses) a connection in Guacamole's database via its REST API, then opens the Guacamole client in a new tab. Connections are auto-named tailscan-{proto}-{ip}-{port} — no manual setup needed.
Device cache
Results cached on disk keyed by exit node IP + subnet. Cached devices load instantly on page open (shown in purple), live scan runs in background and updates the view. Port results written back to cache after each scan. 5-minute background port-only rescan after full scan completes.
Auth
Simple password + session cookie. Set PASSWORD_HASH (SHA-256 of your password) and SECRET_KEY in .env.
echo -n 'yourpassword' | sha256sum
Setup
Requirements
- Docker + Docker Compose
- Tailscale installed and running on the host
- The host must be able to use Tailscale exit nodes
1. Clone the repo
git clone https://github.com/PizzaCow/TailScan /opt/tailscan
cd /opt/tailscan
2. Generate the Guacamole DB init SQL (one time only)
docker run --rm guacamole/guacamole:latest \
/opt/guacamole/bin/initdb.sh --postgresql > guacamole/initdb.sql
3. Create .env
cp .env.example .env
nano .env
Fill in:
PASSWORD_HASH=<sha256 of your password> # echo -n 'yourpassword' | sha256sum
SECRET_KEY=<random string>
POSTGRES_PASSWORD=<pick anything>
GUAC_ADMIN_USER=guacadmin
GUAC_ADMIN_PASS=guacadmin
4. Start
docker compose up -d --build
- TailScan:
http://<host-ip>:8080 - Guacamole:
http://<host-ip>:8085/guacamole
Change the Guacamole admin password after first login: Settings → Users.
Updating
git pull && docker compose up -d --build
Managing with Dockge
Dockge is a nice UI for managing Docker Compose stacks. To install:
mkdir -p /opt/dockge /opt/stacks
curl -o /opt/dockge/compose.yaml https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml
docker compose -f /opt/dockge/compose.yaml up -d
Dockge will be at http://<host-ip>:5001. Point it at /opt/stacks and add TailScan as a stack there.
Manual / bare-metal (not recommended)
If you can't use Docker:
# Debian/Ubuntu
apt install fping nmap
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8080
# Rocky/RHEL (fping must be built from source — not in repos)
dnf install -y gcc make nmap
curl -L https://fping.org/dist/fping-5.2.tar.gz | tar xz
cd fping-5.2 && ./configure && make && make install
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8080
You'll need to set up Guacamole separately and point GUAC_URL at it.
Notes
- TailScan must run on a Tailscale node that can use exit nodes
- guacd must be able to reach the LAN directly — run it on the same machine as TailScan (not a remote VPS)
- No MAC addresses or vendor lookup — traffic goes over the Tailscale tunnel, not direct Ethernet
- The exit node must be advertising subnet routes for LAN discovery to work