# 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 ` — 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` — 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`. ```bash 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 ```bash git clone https://github.com/PizzaCow/TailScan /opt/tailscan cd /opt/tailscan ``` ### 2. Generate the Guacamole DB init SQL (one time only) ```bash docker run --rm guacamole/guacamole:latest \ /opt/guacamole/bin/initdb.sh --postgresql > guacamole/initdb.sql ``` ### 3. Create `.env` ```bash cp .env.example .env nano .env ``` Fill in: ```env PASSWORD_HASH= # echo -n 'yourpassword' | sha256sum SECRET_KEY= POSTGRES_PASSWORD= GUAC_ADMIN_USER=guacadmin GUAC_ADMIN_PASS=guacadmin ``` ### 4. Start ```bash docker compose up -d --build ``` - TailScan: `http://:8080` - Guacamole: `http://:8085/guacamole` **Change the Guacamole admin password** after first login: Settings → Users. ### Updating ```bash git pull && docker compose up -d --build ``` ### Managing with Dockge [Dockge](https://github.com/louislam/dockge) is a nice UI for managing Docker Compose stacks. To install: ```bash 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://:5001`. Point it at `/opt/stacks` and add TailScan as a stack there. ### Manual / bare-metal (not recommended) If you can't use Docker: ```bash # 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