Expand capture-only NetScaler NITRO simulation and crash recovery

README.md

@@ -43,6 +43,40 @@ exploit attempts, not a real appliance and not a vulnerability scanner.
 
 ## What it does
 
+### Capture-only deployment
+
+Use `--simulation-only` to refuse execution and URL fetching. The supplied HTTP service uses
+this mode and does not depend on an execution guest or relay. The loopback viewer service
+disables external public-IP discovery. These services create no backups.
+
+The NITRO simulator supports login/logout cookies, configuration and statistics resource routes,
+named reads, fake POST/PUT/DELETE operations, enable/disable/rename acknowledgements, bindings,
+`attrs`, literal `filter`/`args`, counts and pagination. Its catalog recognizes 1,493 configuration
+names and 176 statistics names from the [official 14.1 reference](https://developer-docs.netscaler.com/en-us/adc-nitro-api/current-release/configuration/). Common appliance, network,
+Gateway, AAA, load-balancing, SSL and binding resources have populated synthetic data;
+unconfigured resources return empty collections. This is a protocol simulation, not a complete
+implementation of every resource's schema or firmware behaviour. Fake changes are bounded,
+per-source memory only and expire with sessions; NAT can merge clients. `HONEYPOT_VERSION`
+controls the invented firmware banner. Uploaded files never become operating-system files
+at submitted paths and are never served publicly.
+
+JSON `systemfile.filecontent` uploads are base64-decoded into inert artifacts while preserving
+the original JSON body too. Binary, multipart, chunked and rejected-request evidence is retained
+by the existing capture layer. Files are committed with atomic rename and directory fsync;
+an interrupted journal tail is preserved separately from subsequent records.
+
+The supplied systemd unit restarts ordinary service crashes after five seconds. Enable VM
+autostart separately when deploying on a hypervisor. Storage/capture failure
+sets an evidence-directory `STOP` latch and exits78, preventing automatic restart. Review
+storage and preserve captured evidence before explicitly clearing that latch. Capture has a
+configurable evidence quota, a 16MiB request-body limit and eight concurrent requests. Cloudflare/NPM
+may reject or normalize traffic before it reaches the collector; unread/rejected bytes beyond
+these boundaries cannot be promised as captured.
+
+Checks: `python3 test_nitro.py`, `python3 test_capture.py`, `python3 test_honeypot.py` and
+`python3 test_safety.py`. Optional execution tools described below are incompatible with
+`--simulation-only` and are not used by the supplied HTTP service.
+
 - Serves a realistic **NetScaler Gateway / Citrix ADC login** (German AAA page) at `/`,
   `/vpn/index.html`, `/vpn/tmindex.html`, `/logon/LogonPoint/*`, `/menu/neo/`, with the
   `rdx`/`CTXS` scripts and favicon fingerprint that scanners look for.
@@ -82,7 +116,7 @@ git clone <your-fork-url> citrixpot && cd citrixpot
 cp .env.example .env          # edit to taste
 python3 test_honeypot.py      # run the test suite
 set -a; . ./.env; set +a
-python3 honeypot.py &         # decoy on http://127.0.0.1:8443
+python3 honeypot.py --simulation-only & # decoy on http://127.0.0.1:8443
 python3 viewer.py             # analyst UI on http://127.0.0.1:8787
 ```
 
@@ -97,6 +131,7 @@ All settings come from the environment (or a `.env` file / systemd `EnvironmentF
 | Variable | Purpose |
 |---|---|
 | `HONEYPOT_BIND`, `HONEYPOT_PORT` | decoy listen address/port |
+| `HONEYPOT_VERSION` | synthetic NITRO firmware banner |
 | `HONEYPOT_PROXY_PROTOCOL_FROM` | transport IP allowed to send PROXY v1 (your ingress) |
 | `HONEYPOT_TRUSTED_FORWARDED_FROM` | edge/proxy hops whose client-IP headers may be trusted |
 | `HONEYPOT_LOG_DIR`, `HONEYPOT_EVIDENCE_MIB` | evidence directory and quota |