# 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.