# Security

Guest Nest is a viewer. It reads the guest list either from the Proxmox API (`GET /api2/json/cluster/resources?type=vm`) or through the parent VM's QEMU guest agent (`pvesh get /cluster/resources`), or both.

## Guest agent or API token?

- **Guest agent** (preferred when the Proxmox VM runs on this Unraid server): no secret is stored anywhere and no network path or certificate is involved. Unraid already controls that VM, and guest-exec runs one fixed read-only command as root inside it. Commands: `virsh qemu-agent-command` with `guest-ping`, `guest-exec` of `/usr/bin/pvesh get /cluster/resources --type vm --output-format json` or `/usr/bin/pveversion`, and `guest-exec-status`. No user input is placed in the guest command; the VM name is its own `virsh` argument (no shell). Output is capped at 2 MiB, parsed as JSON with a depth limit, reduced to known fields, and shown as text.
- **API token**: use it when the agent cannot be installed or guest-exec is blocked by policy, or for a Proxmox cluster where other nodes should be listed through one API. The token sits in plain text on the flash drive (below), so keep it to `VM.Audit` on `/vms`.
- Detection (guest-ping + pveversion) runs only on the Settings page or Refresh, and its result is cached in RAM (`/var/run/guestnest-detect.json`, 10 minutes).

Stock Unraid files are not edited. The script and stylesheet are added from the plugin's own header page.

- The API token secret is written only to `/boot/config/plugins/GuestNest/hosts.json`, in plain text. The flash drive is FAT: the 0700/0600 modes Guest Nest sets do not restrict anything, the mount options do. Anyone who can read the flash can read the token, including the `flash` SMB share when it is exported, and flash backups (for example Unraid Connect flash backup). Use a privilege-separated token limited to `VM.Audit` on `/vms` (see DOCS.md), never a `root@pam` token.
- Settings never send the saved secret back to the browser. A blank secret on Apply keeps the saved one only while the API URL and token id are unchanged, so a stored secret is never sent to a new address. Nest set to No removes that VM's saved token.
- The status request used by the VMs page returns guest names and states, not the token.
- Save accepts POST only; Unraid's `local_prepend.php` checks the WebUI `csrf_token` on every POST.
- API URLs must be `https://host[:port]`: no user info, path, query, or fragment. Redirects are not followed, only HTTPS is allowed, and replies over 2 MiB are dropped.
- Certificates are verified by default. "Pin on Apply" (for Proxmox's own certificate) saves the server's public-key SHA-256 on Apply (trust on first use) and refuses any other key afterwards. There is no option that turns checks off. Hosts saved by 2026.10.01 with "Own certificate" are verified until pinned on Apply.
- Errors returned to the page are short and generic; they never include the token or the HTTP body.
- Uninstall removes the package but leaves the token file on the flash drive so a reinstall keeps the settings. To remove the tokens: set every VM to Nest No and Apply before uninstalling, or delete `/boot/config/plugins/GuestNest` afterwards (`rm -rf /boot/config/plugins/GuestNest`). Revoke the token in Proxmox (Datacenter → Permissions → API Tokens) if it may have been exposed.