# Networking

Attack Range puts lab machines on a private network and exposes access only through a **WireGuard VPN**. You connect to a VPN gateway (router) in the cloud; from there you reach Splunk, Windows, Linux, and other hosts by their private IPs.

## Overview

- **Public:** Only the VPN router has a public IP. Terraform creates the VPC/subnet and the router instance.
- **Private:** Lab servers (Splunk, Windows, Kali, etc.) get private IPs (e.g. in `10.0.2.x`). They are **not** on the public internet.
- **Access:** You run a WireGuard client with a config generated by Attack Range. Once connected, your traffic goes to the router and is forwarded into the private subnet.

## Two-phase build and VPN

Build is intentionally two-phase:

1. **Phase 1 — VPN:** Terraform brings up the network and the router. Ansible installs and configures WireGuard on the router and generates a **client** config. Status becomes **wait_for_vpn**.
2. **You:** Download the WireGuard config, import it into the WireGuard app, and turn the tunnel on.
3. **Phase 2 — Lab:** You continue the build (app, API, or CLI). Ansible runs over SSH to the router (and from there to the lab) and provisions all servers. Status becomes **running**.

So the lab is never created until the VPN path exists, and you must be on the VPN to use the range (Splunk, RDP, SSH, etc.).

## WireGuard VPN

Attack Range uses **WireGuard** as the VPN so only users with a valid client config can reach the lab. WireGuard is a simple, fast layer‑3 VPN with built‑in support on many platforms.

### Why WireGuard

- **Secure:** Modern cryptography (Curve25519, ChaCha20, Poly1305); no legacy protocols.
- **Simple:** Small config (key pair + endpoint); no PKI or certificates to manage.
- **Cross‑platform:** Official clients for Windows, macOS, Linux, iOS, and Android.
- **Lightweight:** Runs in‑kernel on Linux; low overhead on the router.

### Server (router)

- WireGuard runs on the **router** instance in the cloud (Linux).
- One WireGuard interface; the router’s public IP and a single UDP port are the VPN endpoint.
- Each user has a **peer** entry (public key + allowed VPN subnet). The first peer is `client1`; more are added when you use [Sharing](sharing.md).

### Client config

A **client config** is a short text file that defines your tunnel. It is generated once per client (you or a shared user).

- **[Interface]** — Your private key and VPN address (e.g. `10.0.1.11/32` in a small subnet like `10.0.1.0/24`).
- **[Peer]** — The router’s public key, endpoint (router public IP + port), and allowed IPs (typically the lab subnet, e.g. `10.0.2.0/24`, so only that traffic goes over the VPN).

You must keep this file (and the private key inside it) **confidential**. Anyone with it can connect to the Attack Range until the range is destroyed or the peer is removed.

### Where the config is stored

- **API / App:** When status is **wait_for_vpn**, the build status includes `wireguard_config` (and often a download). The API also writes it to `wireguard_config/<attack_range_id>.conf` on the server.
- **Range config file:** The content is saved in the range’s YAML under `general.wireguard_config` so it can be fetched again from `GET /attack-range/status/<id>` or `GET /configs/<id>`.

### WireGuard clients (install and use)

Install the official WireGuard app for your OS:

- **Windows / macOS / Linux:** [https://www.wireguard.com/install/](https://www.wireguard.com/install/)
- **iOS:** App Store — “WireGuard”
- **Android:** Play Store — “WireGuard”

To connect:

1. Get the client config (download from the app or copy from the API response).
2. In WireGuard: **Add tunnel** → **Import from file** (or paste the config).
3. Turn the tunnel **On**. Your traffic to the lab subnet (e.g. `10.0.2.0/24`) will go through the VPN.
4. Use Splunk, RDP, SSH, etc. via the **private** IPs (e.g. `10.0.2.10`, `10.0.2.11`).

To disconnect, turn the tunnel **Off** in the WireGuard app.

### Multiple users (sharing)

Each shared user gets their own client config (a new peer). Several people can be connected at the same time. See [Sharing](sharing.md).

## Connecting

1. Build until status is **wait_for_vpn**.
2. Get the WireGuard config:
   - **App:** Download from the status / build page.
   - **API:** `GET /attack-range/status/<attack_range_id>` → use the `wireguard_config` field.
3. Import into WireGuard (Desktop or mobile) and activate the tunnel.
4. Continue the build (phase 2). When status is **running**, use the range over the same VPN connection.

## Using the range over VPN

- **Splunk:** Use the Splunk server’s **private** IP and port (e.g. `10.0.2.10:8000`) in the browser. Credentials come from the config (e.g. `admin` / password from template or role vars).
- **RDP (Windows):** Connect to the Windows server’s private IP (e.g. `10.0.2.11:3389`) with the user/password from the config.
- **SSH (Linux):** `ssh user@10.0.2.x` with the key or password from the config.
- **Guacamole:** If the template includes the Guacamole role, the app/API may show a Guacamole URL (via the router or a lab host) and credentials.

All of these are only reachable when your machine is connected to the Attack Range WireGuard VPN.

## Sharing access (multiple users)

To give another person access, you add a **new WireGuard client** (e.g. “alice”). That generates a second config so both you and alice can be connected at once. See [Sharing](sharing.md).

## Firewall and IP whitelist

- **general.ip_whitelist** in the config can limit which source IPs are allowed (e.g. for the router’s SSH or WireGuard). `0.0.0.0/0` allows any.
- Lab hosts are not directly exposed; access is only via the VPN after WireGuard authentication.

## Troubleshooting

- **Cannot reach Splunk/Windows:** Ensure the WireGuard tunnel is up and you’re using the **private** IPs from the config/architecture, not the router’s public IP for those services.
- **Build phase 2 fails:** Often SSH from the runner to the router or from router to lab. Ensure you are on the VPN if the runner (e.g. your laptop) is the one executing Ansible; in Docker, the API/CLI container uses the host’s network or the same VPN depending on setup.
- **Router public IP:** Shown in the status (e.g. `router_public_ip`). That’s the WireGuard server endpoint; the client config already references it.

For adding more users and managing client configs, see [Sharing](sharing.md).