docs: update README with port list; fix proxy query param passthrough; purple cached rows
This commit is contained in:
1 parent
5c3265d83d
commit
9941cb8e68
1 file changed
+134
-132
@@ -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.
|
||||
|
||||
  
|
||||
## What it does
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
- The machine running TailScan **is** the Tailscale client
|
||||
- Selecting an exit node runs `tailscale set --exit-node=<ip>` 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://<tailscale-ip>:8080`
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
`.env` file (copy from `.env.example`):
|
||||
|
||||
```env
|
||||
PASSWORD_HASH=<sha256 hex of your password>
|
||||
SECRET_KEY=<random 64-char hex string>
|
||||
```
|
||||
|
||||
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 <subnet>` 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<ports>` — 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=<sha256 of your password>
|
||||
SECRET_KEY=<random string>
|
||||
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
|
||||
Reference in new issue
Block a user