From 9941cb8e68a3dd0fd0206038de6c2dd51491c736 Mon Sep 17 00:00:00 2001 From: Pizza <33816021+PizzaCow@users.noreply.github.com> Date: Wed, 1 Apr 2026 21:35:34 -0600 Subject: [PATCH] docs: update README with port list; fix proxy query param passthrough; purple cached rows --- README.md | 266 +++++++++++++++++++++++++++--------------------------- 1 file changed, 134 insertions(+), 132 deletions(-) diff --git a/README.md b/README.md index db2e697..f011155 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,141 @@ # TailScan -Self-hosted web app to manage Tailscale exit nodes and scan remote LANs — all from a browser. +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. -![Python](https://img.shields.io/badge/python-3.11+-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-green) ![License](https://img.shields.io/badge/license-MIT-lightgrey) +## What it does ---- - -## How it works - -- The machine running TailScan **is** the Tailscale client -- Selecting an exit node runs `tailscale set --exit-node=` on the server -- LAN discovery, port scanning, and WAN geolocation all run through the active exit node -- Access the UI via the server's **Tailscale IP** — so exit node switches can never lock you out - ---- - -## Features - -- **Exit node selector** — lists all tailnet peers, one click to switch or disconnect -- **Live LAN discovery** — fping sweep streams devices as they respond (~9s for /24) -- **Auto port scan** — after discovery, scans common ports on every device automatically -- **Port chips** — open ports shown as compact inline chips; hover for service name -- **WAN + geo** — WAN IP, city, region, ISP, timezone via ip-api.com (no key needed) -- **Diff refresh** — auto-refreshes every 30s without wiping the device list; port results persist -- **Password auth** — SHA256 hashed password, 7-day session cookie -- **Dark UI** — zero JS frameworks, plain HTML/CSS/JS - ---- - -## Requirements - -- Linux machine with [Tailscale](https://tailscale.com/download) installed and connected -- Python 3.11+ -- `fping` and `nmap` (installed automatically by `start.sh`) -- Git - ---- - -## Quick Start - -```bash -git clone https://github.com/PizzaCow/TailScan /opt/tailscan -cd /opt/tailscan -chmod +x start.sh update.sh -./start.sh -``` - -On first run, `start.sh` creates `.env` from `.env.example` and exits. Edit it: - -```bash -nano /opt/tailscan/.env -``` - -Then run again: - -```bash -./start.sh -``` - -Access at `http://:8080` - ---- - -## Configuration - -`.env` file (copy from `.env.example`): - -```env -PASSWORD_HASH= -SECRET_KEY= -``` - -Generate values: - -```bash -# Password hash -python3 -c "import hashlib; print(hashlib.sha256(b'yourpassword').hexdigest())" - -# Secret key -python3 -c "import secrets; print(secrets.token_hex(32))" -``` - ---- - -## Run as a systemd service - -```bash -sudo cp tailscan.service /etc/systemd/system/ -# Edit WorkingDirectory if you installed somewhere other than /opt/tailscan -sudo systemctl daemon-reload -sudo systemctl enable --now tailscan -``` - -Check status: - -```bash -sudo systemctl status tailscan -journalctl -u tailscan -f -``` - ---- - -## Update - -```bash -cd /opt/tailscan -./update.sh -``` - -Pulls latest from GitHub and restarts the server (or restarts the systemd service if active). - ---- - -## How exit node scanning works - -TailScan detects the active exit node's advertised subnet from the Tailscale status JSON (`AllowedIPs`). The exit node must have **subnet routing enabled and approved** in the Tailscale admin console. - -If no advertised subnet is found, TailScan falls back to the server's local routing table. - ---- - -## Security notes - -- Run on a **dedicated machine** — switching exit nodes affects all server traffic -- Keep port 8080 on Tailscale only; do **not** expose to the public internet -- `.env` contains your password hash and secret key — keep it out of git (already in `.gitignore`) - ---- +- Connects to any Tailscale exit node +- Discovers all live hosts on the LAN using **fping** (fast, ~10s for a /24) +- Scans open ports on every device using **nmap** (~1s per host) +- Proxies web UIs directly from your browser through the exit node +- Caches last scan results per network so the page loads instantly ## Stack -| Component | Purpose | -|---|---| -| Python + FastAPI | Backend + SSE streaming | -| fping | Fast LAN host discovery | -| nmap | On-demand port scanning (TCP connect, no probes) | -| ip-api.com | WAN geolocation (free, no key required) | -| Plain HTML/CSS/JS | Frontend — no frameworks | +- **Python 3** / **FastAPI** / **uvicorn** +- **fping** — host discovery via ICMP (much faster than nmap ping sweep) +- **nmap** — TCP connect port scan, no root required (`-sT`) +- **httpx** — async HTTP for WAN geo lookup and the reverse proxy +- **Tailscale** — peer list and exit node control via `tailscale status --json` + +## Scanned Ports (116 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 | +| `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 | `32400` | Plex | +| `32469` | Plex DLNA | `51413` | Transmission torrent | | | + +Browsable ports (clickable chips that open through the proxy): `80`, `443`, `1880`, `3000`, `3001`, `4000`, `4200`, `5000`, `5001`, `5055`, `7000`, `7001`, `7878`, `8001`, `8006`, `8007`, `8080`–`8082`, `8090`, `8096`, `8097`, `8123`, `8200`, `8443`, `8686`, `8787`, `8888`, `8920`, `8989`, `9000`, `9090`, `9091`, `9117`, `9393`, `9443`, `9696`, `9999`, `10000`, `32400`. + +## How it works + +### Host discovery +Uses `fping -a -g ` which sends ICMP pings to the whole subnet in parallel and streams responding IPs. Typical time: ~9s for 79 hosts on a /24. No ARP (traffic goes over the Tailscale tunnel, not direct LAN). + +### Subnet detection +Reads the exit node's `AllowedIPs` from `tailscale status --json` and filters for private RFC-1918 ranges. Falls back to `ip route` if no AllowedIPs are found. + +### Port scanning +`nmap -sT --open -T5 -p` — TCP connect scan, no raw sockets, no root required. ~1s per host. 116 ports covering common services, databases, homelab UIs, and IoT. + +### Reverse proxy +`/proxy?t=http://ip:port/path` — fetches from the LAN via the exit node, rewrites HTML links and injects a JS interceptor so SPA routing (Sonarr, Radarr, Proxmox, etc.) works end-to-end. + +### Device cache +Results are cached on disk per exit node / subnet. On next page load, cached devices appear instantly in **purple** while the live scan runs in the background. Port results are written back to the cache after each scan. + +## Auth + +Simple password auth with a session cookie. Set `PASSWORD_HASH` (SHA-256 of your password) and `SECRET_KEY` in `.env`. + +```bash +echo -n 'yourpassword' | sha256sum +``` + +## Setup + +### Requirements + +```bash +apt install fping nmap +pip install -r requirements.txt +``` + +### .env + +``` +PASSWORD_HASH= +SECRET_KEY= +CACHE_DIR=/tmp/tailscan-cache # optional +``` + +### Run + +```bash +uvicorn main:app --host 0.0.0.0 --port 8080 +``` + +### systemd service + +```ini +[Unit] +Description=TailScan +After=network.target tailscaled.service + +[Service] +WorkingDirectory=/opt/tailscan +ExecStart=/usr/local/bin/uvicorn main:app --host 0.0.0.0 --port 8080 +Restart=always +EnvironmentFile=/opt/tailscan/.env + +[Install] +WantedBy=multi-user.target +``` + +```bash +cp tailscan.service /etc/systemd/system/ +systemctl enable --now tailscan +``` + +## Notes + +- TailScan needs to be on a Tailscale node that can use exit nodes (i.e. `--exit-node` routing works) +- No MAC addresses or vendor lookup — traffic goes over the tunnel, not direct Ethernet +- The exit node must be advertising subnet routes for LAN discovery to work