CitrixPot: NetScaler / Citrix ADC Gateway honeypot (initial public release)

deploy/VM-ACCESS.md

@@ -0,0 +1,58 @@
+# 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.