citrixpot/deploy/VM-ACCESS.md

Deployment notes (template)

Replace every <...> placeholder with your own values. Keep real addresses and keys out of the repository; put them in /etc/decoy.env (see .env.example) or your own secret store.

Topology

• Proxmox host: <PROXMOX_HOST> (management network, not public).
• Collector VM: stores evidence and serves the decoy. QEMU user networking only, no bridge NIC.
• Execution VM (optional): disposable, isolated guest for real payload behaviour. Requires restrict=on, no bridge NIC, no host mounts, and must never be enabled on a public listener.
• Edge proxy (e.g. Nginx Proxy Manager on <EDGE_PROXY_IP>): terminates TLS and forwards to a source-preserving ingress on the Proxmox host.

Source-preserving ingress

ingress_proxy.py accepts a TCP connection and prepends a PROXY-v1 header (the real client address) before the decoy reads any bytes. Restrict who may reach it:

INGRESS_BIND=<PROXMOX_HOST>
INGRESS_PORT=18443
INGRESS_TARGET=127.0.0.1
INGRESS_TARGET_PORT=19443
INGRESS_ALLOW_FROM=<EDGE_PROXY_IP>,127.0.0.1,<PROXMOX_HOST>

At the decoy, trust only the edge hop for client-IP headers:

HONEYPOT_PROXY_PROTOCOL_FROM=<QEMU_GATEWAY>        # e.g. 10.0.2.2 for QEMU user networking
HONEYPOT_TRUSTED_FORWARDED_FROM=<EDGE_PROXY_IP>,127.0.0.1

Add a host firewall rule so only the edge proxy and the host itself can reach the origin port. Example (adapt to your firewall tooling):

iptables -N DECOY-ORIGIN
iptables -A DECOY-ORIGIN -i lo -j RETURN
iptables -A DECOY-ORIGIN -s <EDGE_PROXY_IP> -j RETURN
iptables -A DECOY-ORIGIN -s <PROXMOX_HOST> -j RETURN
iptables -A DECOY-ORIGIN -j DROP
iptables -I INPUT 1 -p tcp --dport 18443 -j DECOY-ORIGIN

Management access

Use your own SSH keys and a jump host. Do not enable agent/X11/port forwarding on the management key (no-agent-forwarding,no-port-forwarding,no-X11-forwarding).

Operational notes

• QEMU filter-dump truncates its pcap on guest start; archive it before restarting the execution VM.
• The decoy is fail-closed: when the evidence quota or disk fails it stops rather than overwriting. Archive evidence before restarting.
• Never enable real command execution on an internet-facing listener.