# Secure Admin Access

Wirebump's web interface is accessible over HTTPS (with a self-signed certificate) or through an SSH tunnel. For most home users, accepting the HTTPS certificate warning is the simplest and most practical approach.

**Key point**: Admin access is always on the LAN side of Wirebump. Wirebump sits between your ISP/modem and your devices. You connect to it at 10.0.0.1 on your local network. Even in On-the-Go mode when the Wirebump device itself connects to untrusted WiFi, your admin connection is local (localhost or 10.0.0.1). Admin traffic stays on your local network—it never goes through the internet or upstream networks.

## Decision Matrix

| Scenario | Recommended Method | Why |
|----------|-------------------|-----|
| **Home LAN (typical use)** | HTTPS - click through warning | Simplest. Low risk on your own trusted network (where you control WiFi passwords and know all connected devices). |
| **Want to eliminate warnings** | Install cert in OS trust store | Proper long-term solution. Enables browser MitM detection. |
| **Shared/guest network** | SSH tunnel | Protects against other untrusted devices on the same LAN. |
| **Remote over internet** | SSH tunnel via VPN | Never expose web UI directly. Use Tailscale/WireGuard + SSH. |
| **High-security requirement** | SSH tunnel always | Strongest authentication. Defense in depth. |

## HTTPS with Self-Signed Certificate (Recommended for Home Use)

When you connect to `https://10.0.0.1`, your browser shows a security warning. This is expected and normal for local network devices like routers, switches, and IPMI interfaces.

### Why the Warning Appears

Wirebump generates a unique ECDSA P-256 self-signed certificate during bootstrap. Your browser does not recognize the certificate authority because Wirebump is the authority. The browser cannot verify the issuer, so it warns you.

**What the warning actually means**: "I cannot verify who signed this certificate." It does not mean the connection is insecure or that someone is attacking you. The TLS 1.3 encryption works identically to a CA-signed certificate—the only difference is trust establishment.

### Is Accepting the Warning Safe?

**On your home network**: Yes, for most users. The actual risk is if someone on your LAN (someone who cracked your WiFi password, a rogue device on your network, or ARP poisoning attack) intercepts the connection. If you trust your LAN, the self-signed cert is fine.

Click 'Advanced' or 'Proceed anyway' (exact wording varies by browser). Your connection is encrypted from that point forward.

**For initial setup**: If you want maximum security on first connection, verify the certificate fingerprint matches before accepting. Compare what your browser shows against the output of this command on the Wirebump machine:
```bash
openssl x509 -in /etc/wirebump/secrets/tls-cert.pem -noout -fingerprint -sha256
```

This prevents MitM attacks during trust establishment.

### The "Bad Habit" Concern

Some security guidance warns that accepting certificate warnings trains you to bypass security protections. **Context matters**:

- **Random websites**: Accepting certificate warnings on unknown internet sites is dangerous. Don't do it.
- **Your local device**: This is your Wirebump appliance on your own LAN. You know what it is and trust your network.

**For the most cautious**: If you want to avoid this entirely, install the certificate in your OS trust store (see below) or use SSH tunneling. But for typical home use, accepting the warning is a reasonable tradeoff between security and convenience.
**Tip:** **For beginners:** If you are sitting at home managing your own network appliance, accepting the certificate warning is perfectly reasonable. This is standard practice for network gear.

### What Data is Exposed

The web interface displays:
- VPN connection status
- Circuit topology configuration
- Performance metrics

**NOT exposed**: VPN provider credentials, WireGuard private keys, or other secrets. These are stored encrypted on disk and never transmitted through the UI.

### Access Control Model

The web interface has no password authentication. Access control relies on network-level security: LAN isolation (you must be on the downstream LAN to reach 10.0.0.1) or SSH tunnel authentication.

**Do not expose the web UI directly to the public internet.** It is designed for LAN-only access or SSH tunnel use.

### Technical Details
**For the security-minded:** **Certificate generation:** Wirebump creates an ECDSA P-256 self-signed certificate during bootstrap. ECDSA provides strong security with smaller key sizes and better performance than RSA. The cert is unique to your installation and includes SANs for `localhost`, `127.0.0.1`, and `10.0.0.1`.

**Why not Let's Encrypt:** Wirebump runs on private LAN addresses (10.0.0.1, 192.168.x.x). Let's Encrypt requires publicly routable domains with HTTP challenges. You could set up a domain, dynamic DNS, and obtain a proper cert, but that introduces attack surface and complexity most users do not need.

**Using your own certificate:** If you have an internal CA, you can replace the self-signed cert. The private key is stored at `/etc/wirebump/secrets/tls-key.pem` (file permissions 0600) and the certificate at `/etc/wirebump/secrets/tls-cert.pem`.

## Installing Certificate in Trust Store (Advanced)

If you want to eliminate browser warnings while maintaining protection against MitM attacks, install Wirebump's certificate in your operating system's trust store.

**Why this is better than clicking through**: Once the certificate is trusted by your OS, your browser can detect if someone tries to substitute a different certificate (MitM attack). The warning goes away, but the security check remains active.

### Export the Certificate

First, export Wirebump's certificate to a file:

```bash
openssl s_client -connect 10.0.0.1:443 -showcerts < /dev/null 2>/dev/null | \
  openssl x509 -outform PEM > wirebump.crt
```

This creates `wirebump.crt` in your current directory.

### Install on Windows

1. Press `Win + R`, type `certmgr.msc`, press Enter
2. Expand **Trusted Root Certification Authorities**
3. Right-click **Certificates** → **All Tasks** → **Import**
4. Follow the wizard, select `wirebump.crt`
5. Restart your browser
### Install on macOS

1. Open **Keychain Access** (search in Spotlight)
2. Drag `wirebump.crt` into the **System** or **login** keychain
3. Double-click the imported certificate
4. Expand **Trust** section
5. Set **When using this certificate** to **Always Trust**
6. Close and enter your password when prompted
7. Restart your browser
### Install on Linux

```bash
sudo cp wirebump.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

For Firefox specifically (uses its own cert store):
1. Settings → Privacy & Security → Certificates → View Certificates
2. Authorities tab → Import
3. Select `wirebump.crt`, check "Trust this CA to identify websites"

### Benefits

- No browser warnings ever
- Browser can detect MitM attempts (certificate validation still works)
- Proper long-term solution
- Can be deployed via group policy in enterprise environments

## SSH Tunneling (Advanced)

SSH tunneling routes the web interface through an encrypted SSH connection. This adds a host-based authentication layer that protects against insider LAN threats (rogue devices, ARP poisoning, compromised WiFi).

Most home users won't need this—it's for advanced scenarios where you don't trust your local network or need remote access.

### When to Use SSH Tunneling

- **Shared/guest networks**: You don't trust other devices on the LAN (office guest WiFi, hotel network shared by other rooms)
- **Remote internet access**: Managing Wirebump from outside your home (requires VPN to home first)
- **High-security requirements**: Defense in depth—SSH host key verification prevents MitM even if LAN is compromised
- **Multiple admins**: SSH key-based auth provides auditability

### How It Works

You establish an SSH connection to Wirebump and forward a local port to the web interface. Your browser connects to `localhost`, which tunnels through SSH to 10.0.0.1.

**Network path**: Your browser → localhost:8080 → SSH tunnel → Wirebump:80 → web interface

The entire connection is encrypted with SSH. SSH verifies Wirebump's identity via its host key fingerprint, preventing MitM attacks. No certificate warnings, no trust issues.

### Basic Command

```bash
ssh -L 8080:10.0.0.1:80 ubuntu@10.0.0.1
```

Then open `http://localhost:8080` in your browser.

**What this does:**
- `-L 8080:10.0.0.1:80` forwards your local port 8080 to Wirebump's port 80
- `ubuntu@10.0.0.1` connects to the Wirebump machine (adjust username and IP as needed)
- The SSH session stays open while you access the UI
- Close the SSH session (Ctrl+C or exit) when done
**Tip:** You can tunnel HTTPS instead: `ssh -L 8080:10.0.0.1:443 ubuntu@10.0.0.1`. The result is the same (encrypted via SSH), but HTTPS adds a second encryption layer if you want defense in depth.

### Persistent Configuration

If you access Wirebump frequently via SSH tunnel, add this to `~/.ssh/config` on your local machine:

```ssh-config
Host wirebump
    HostName 10.0.0.1
    User ubuntu
    LocalForward 8080 10.0.0.1:80
    ServerAliveInterval 60
```

Now you can connect with just:

```bash
ssh wirebump
```

The tunnel establishes automatically. Open `http://localhost:8080` in your browser.

**ServerAliveInterval** keeps the connection alive if you leave the tunnel idle. Adjust or remove if it causes issues with your network.

### SSH Key Setup

SSH tunneling works best with key-based authentication. If you are not familiar with SSH keys, here is the basic flow:

1. Generate a key pair on your local machine (if you do not have one already):
   ```bash
   ssh-keygen -t ed25519 -C "your-email@example.com"
   ```

   You'll be prompted for a passphrase. Using one is strongly recommended—it protects your private key if your laptop is lost or stolen.

2. Copy the public key to Wirebump:
   ```bash
   ssh-copy-id ubuntu@10.0.0.1
   ```

3. Test the connection:
   ```bash
   ssh ubuntu@10.0.0.1
   ```

4. If it works without asking for a password, you are set.
**Need more detail?** The [Arch Wiki SSH keys page](https://wiki.archlinux.org/title/SSH_keys) is comprehensive and distribution-agnostic. GitHub also provides [good SSH setup documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
**Caution:** If you are setting up SSH for the first time, save your private key securely. Losing it means losing SSH access. Back it up, or be prepared to use console access (physical keyboard, VM console, or IPMI).

## Remote Access Over the Internet

If you need to manage Wirebump from outside your home network, **never expose the web UI directly to the internet**. The web interface has no authentication layer beyond network access.

### Recommended Approach

Use Tailscale or WireGuard to create a VPN back to your home network, then SSH tunnel to Wirebump:

1. Set up Tailscale or WireGuard VPN to your home network
2. Connect to the VPN from your remote location
3. SSH tunnel to Wirebump at its LAN address:
   ```bash
   ssh -L 8080:10.0.0.1:80 ubuntu@10.0.0.1
   ```
4. Access `http://localhost:8080` in your browser
This is the cleanest approach. No port forwarding, no public exposure. Your home network remains isolated.

### Alternative: Port Forwarding

If you cannot use a VPN, port forward SSH through your router:

1. Forward port 2222 (or your preferred SSH port) on your router to port 22 on the Wirebump machine
2. From remote location:
   ```bash
   ssh -L 8080:10.0.0.1:80 your-home-router.example.com -p 2222
   ```
3. Access `http://localhost:8080` in your browser

**Note**: This exposes SSH to the public internet. Use strong SSH keys, disable password authentication, and consider fail2ban or similar brute-force protection.

### Management Interface (Optional 3rd NIC)

Wirebump supports an optional management interface (3rd NIC, typically WiFi) that bypasses the VPN firewall. This allows SSH access even when VPN tunnels are down. Most users skip this—it's mentioned for completeness.

## Troubleshooting

### Browser Shows "Connection Refused" on localhost:8080

Your SSH tunnel is not running or the port forward failed.

**Check:**
- Is the SSH session still active? The tunnel dies when the SSH session closes.
- Did you use the correct local port? The command specifies which port to use.
- Is something else using port 8080? Try a different port: `ssh -L 8081:10.0.0.1:80 ubuntu@10.0.0.1`

**Fix**: Re-run the SSH command. Verify the tunnel is active before opening the browser.

### SSH Connection Times Out

The Wirebump machine is unreachable or SSH is not listening.

**Check:**
- Can you ping 10.0.0.1 from your machine?
- Is SSH running on Wirebump? Try `sudo systemctl status ssh` on the Wirebump machine.
- Are you using the correct IP address? Single-NIC mode uses `localhost`, standard mode uses the LAN IP (10.0.0.1).

### Certificate Warning Appears Every Time

Browsers do not persist self-signed certificate exceptions reliably across sessions.

**Solutions:**
- Install the certificate in your OS trust store (see above) - proper long-term solution
- Use SSH tunneling instead (no warnings, ever)
- Accept that you will click through occasionally (normal for network gear)

Most network professionals accept this as normal behavior for local network devices.

### Certificate Installation Not Working

**Windows**: Ensure you imported into "Trusted Root Certification Authorities", not "Personal" or another store. Restart your browser after import.

**macOS**: Make sure you set the trust to "Always Trust" in Keychain Access. System keychain may require admin password.

**Linux**: After `update-ca-certificates`, check `/etc/ssl/certs/ca-certificates.crt` contains your cert. Firefox uses its own store—import separately.

### SSH Key Authentication Not Working

Your public key is not installed on the Wirebump machine or permissions are wrong.

**Check:**
- Does `~/.ssh/authorized_keys` exist on Wirebump?
- Are the permissions correct? `chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys`
- Are you connecting as the right user? The user on Wirebump must have your public key in their authorized_keys file.

## Related

- [On-the-Go Mode](https://wirebump.net/docs/deployment-modes/on-the-go) - Portable VPN for travel
- [Single-NIC Mode](https://wirebump.net/docs/deployment-modes/single-nic) - Access considerations for single-interface deployments
- [Troubleshooting](https://wirebump.net/docs/guides/troubleshooting) - General recovery options and common issues

---

Mullvad and Mullvad VPN are trademarks of Mullvad VPN AB. Proton VPN is a registered trademark of Proton AG.