docs: correct honeypot detection docs for operators

- CLAUDE.md: HONEYPOT_SIGNATURES ships empty in this release; no active
  generic signatures, the Heralding VNC tell is the only named-product match
  the code can produce, and the generic mechanism is retained solely as an
  extensibility point for future entries verified against real -sV output.
- CLAUDE.md + config.json.sample + the __honeypot_active_confirm_note__
  constant in spoonmap.py: the active probe runs on hosts flagged by the
  TTL-spread or port-profile signals, not on "any flagged host" — a host
  flagged only by the older tarpit open-port-ratio heuristic feeds the finding
  but is never probed.
- CLAUDE.md: document three limitations plainly, none of them fixed in code.
  (1) On a Full 1-65535 scan essentially every ephemeral port is already
  scanned, so _select_confirm_probe_ports() finds few or no candidates and the
  probe silently does nothing. (2) All honeypot detection lives in mass_scan();
  the direct-nmap port-discovery path used below nmap_threshold performs none
  of it. (3) Every signal only becomes a FINDING when script_scan is true,
  since generate_findings() returns immediately without nse_results/ — the
  Stage 1 stdout warnings and discovery/*.txt files are written either way,
  because those come from mass_scan().
- CLAUDE.md: record the unconditional truncation of the two new discovery
  files, the pre-loop `enabled` check, and the new scope filter.
- README.md: add the missing `honeypot_active_confirm` config-key row, and
  add "Likely Honeypot / Decoy Host" to the findings-severity catalog at all
  three tiers it can now emit, following the table's existing one-row-per-
  severity convention for multi-severity findings (cf. the SNMP and LLM-API
  entries).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: bandrel

CLAUDE.md

@@ -452,9 +452,20 @@ behind one address, though NAT/load-balancing can produce the same pattern,
 which is why this signal alone is capped at LOW and can never alone reach
 HIGH); known port-profile matching against `HONEYPOT_PORT_PROFILES`
 (Thinkst Canary, Artillery — placeholders pending verification against
-current upstream defaults); named-product signature matching against
-`HONEYPOT_SIGNATURES` (Cowrie/Kippo, Dionaea default banners — same
-verification caveat) via the -sV service data already captured; a
+current upstream defaults — the finding's own reason text carries that
+caveat verbatim, since it lands in an engagement deliverable); generic
+named-product signature matching against `HONEYPOT_SIGNATURES` via the -sV
+service data already captured, **which ships EMPTY in this release** — the
+two development-era entries (Cowrie/Kippo, Dionaea) were both verified
+incorrect against nmap's real output in final review and removed rather than
+patched, so there are no active generic signatures and the mechanism
+(`_honeypot_signature_match()`, `_named_honeypot_matches()`) is retained
+purely as an extensibility point for future entries verified against real
+`-sV` output rather than a synthetic fixture (the reasons are recorded at
+the tuple itself; the short version is that the Cowrie needle's hyphen can
+never match nmap's space-rendered template, and "fixing" it would
+false-positive HIGH on every ordinary Debian OpenSSH host, while the Dionaea
+needle only ever appears in `servicefp`, a field the matcher never reads); a
 source-verified Heralding VNC honeypot tell (`_vnc_heralding_match()`,
 Task 3 Step 7 — vnc-info reporting RFB protocol 3.7 with no security-type
 list, since Heralding's VNC capability hardcodes that exact version and
@@ -467,16 +478,20 @@ data came back and failed to match, so a LaBrea-style silent host previously
 scored zero on that check alone. `_iter_open_tcp_ports()` is the shared,
 per-element-defensive XML walk both nmap-side counters and the signature
 matcher use, factored out of what was originally
-`_count_unmatched_service_ports()`'s own walk. Severity is HIGH for a named
+`_count_unmatched_service_ports()`'s own walk. With `HONEYPOT_SIGNATURES`
+empty, the Heralding VNC tell is the only named-product match this release
+can produce. Severity is HIGH for a named
 signature match or an active-probe confirmation, MEDIUM for two or more
 heuristic signals together, LOW for exactly one — a behavior change from the
 single flat MEDIUM this finding used to emit unconditionally. An optional
 active confirmation probe (`_active_confirm_probe()`) attempts a raw TCP
 connect against a handful of high, never-scanned ports
 (`_select_confirm_probe_ports()`, deterministic per-IP via a seeded
 `random.Random(ip)` rather than global randomness, so it is reproducible and
-testable) on any flagged host; a real host has no reason to answer on an
-ephemeral port outside the scan, so an answer is treated as confirmation.
+testable) on any host flagged by the TTL-spread or port-profile signals —
+**not** on a host flagged only by the older tarpit-ratio heuristic, which
+feeds the finding but never the probe; a real host has no reason to answer on
+an ephemeral port outside the scan, so an answer is treated as confirmation.
 This is the one signal that sends new traffic, so it is gated behind
 `honeypot_active_confirm` in config.json — default false, absent means
 false, no interactive prompt of its own — mirroring `check_for_updates`'s
@@ -491,4 +506,37 @@ that pattern.) `discovery/suspected_honeypots.txt` (Stage 1: TTL spread and
 port-profile hits, one line per `(ip, signal)` pair) and
 `discovery/confirmed_honeypots.txt` (Stage 2: active-probe confirmations)
 are new sibling files to the existing `discovery/suspected_tarpits.txt`,
-read back the same defensively-parsed way in `generate_findings()`.
+read back the same defensively-parsed way in `generate_findings()`. Unlike
+`suspected_tarpits.txt`, both of those are written **unconditionally** — an
+empty result truncates the file rather than leaving the previous run's
+content in place. That divergence is deliberate: severity is now computed by
+*counting* signals, so a stale line from an earlier, broader run silently
+inflates a later, narrower run's severity, and a stale
+`confirmed_honeypots.txt` line additionally makes the deliverable assert
+"host answered on a port never scanned open" for a probe that did not run
+this time at all (exactly what happens when the operator turns
+`honeypot_active_confirm` back off). The `enabled` check happens in
+`_confirm_flagged_honeypots()` itself, ahead of the per-host loop, so the
+common disabled case skips `_select_confirm_probe_ports()`'s candidate-set
+work entirely — but that path still truncates the file rather than returning
+outright, for the reason just given. Every host handed to the probe is first
+run through `_scope_filtered_flags()` against the current `target_file`,
+since the probe is the only honeypot signal that *sends packets* and the
+flag dict is built from cached `live_hosts/` and `masscan_results/` data
+that a narrowed `ranges.txt` deliberately never prunes; an empty/unparseable
+scope is permissive, matching `_report_out_of_scope_retained()`.
+
+**Three limitations an operator enabling `honeypot_active_confirm` needs to
+know.** (1) On a **Full** scan (`dest_ports == ['1-65535']`) essentially every
+ephemeral port has already been scanned, so `_select_confirm_probe_ports()`
+finds few or zero unscanned candidates and the probe effectively does
+nothing — silently, with no message either way. (2) **All** honeypot
+detection, Stage 1 signals and the active probe alike, lives inside
+`mass_scan()`; the alternate direct-nmap port-discovery path (taken for
+small/medium scans below the configured `nmap_threshold` work-unit ceiling)
+performs none of it. (3) Every signal in this feature only ever becomes a
+*finding* when `script_scan: true`, because `generate_findings()` returns
+immediately when `nse_results/` does not exist and the default is off — the
+Stage 1 stdout warnings and the `discovery/*.txt` files are still written
+either way, since those come from `mass_scan()`, not `generate_findings()`.
+None of the three is fixed in code; they are documented as-is.

README.md

@@ -308,6 +308,7 @@ git update-index --no-skip-worktree ranges.txt
 | `resume` | `"True"` / `"False"` | Skip completed port discovery on restart (default: False) |
 | `check_for_updates` | `"True"` / `"False"` | Contact api.github.com at startup to check for a newer release. Off unless set; see `--check-update` for a one-off check (default: False) |
 | `scanner_profile` | `false`, `"random"`, or an object | Substitutes strings that identify nmap/SpooNMAP in probe traffic (e.g. the RDP probe's `mstshash=nmap` cookie). Off unless set — see below |
+| `honeypot_active_confirm` | `"True"` / `"False"` | Actively confirm suspected decoy hosts with a few raw TCP connects to unscanned high ports. Off unless set; only probes in-scope hosts flagged by the TTL-spread or port-profile signals, and only on the masscan scan path (default: False) |
 | `__generated_by_prompts__` | String | Present only in a config the prompts wrote. While it is present, **[d]elete**/**[a]ppend** re-ask the options using this file's values as defaults; remove it to keep them fixed |
 
 Keys beginning and ending with `__` are documentation and are ignored by the loader, so you can annotate the file freely — a re-prompted run preserves them.
@@ -554,6 +555,7 @@ After scanning, `generate_findings()` parses all nmap XML results and produces s
 | HIGH | IKE Aggressive Mode with Pre-Shared Key (U:500, confirmed by `ike-version`) |
 | HIGH | RealVNC Authentication Bypass (CVE-2006-2369) (5900/5901, confirmed by `realvnc-auth-bypass`) |
 | HIGH | Service Exposed Externally (databases, RDP, SMB, SNMP, WebLogic, VNC, WSUS 8530/8531, etc. — external scan only) |
+| HIGH | Likely Honeypot / Decoy Host — named product match (Heralding VNC) or an active confirmation-probe answer |
 | MEDIUM | SMBv1 protocol enabled |
 | MEDIUM | Weak SSH algorithms (deprecated ciphers/MACs/KEX) |
 | MEDIUM | Java RMI registry exposed |
@@ -563,6 +565,8 @@ After scanning, `generate_findings()` parses all nmap XML results and produces s
 | MEDIUM | OpenAI-Compatible LLM API Unauthenticated (1234/1337/3000/8000, custom NSE — internal scan) |
 | MEDIUM | Gradio LLM Web UI Accessible (7860, custom NSE — internal scan) |
 | MEDIUM | KoboldCpp LLM API Unauthenticated (5001, custom NSE — internal scan) |
+| MEDIUM | Likely Honeypot / Decoy Host — two or more heuristic signals on one host |
+| LOW | Likely Honeypot / Decoy Host — exactly one heuristic signal (tarpit open-port ratio, TTL spread, port profile, unmatched fingerprints, or silent open ports) |
 | LOW | Anonymous FTP login (default LOW — review the share; escalate if it exposes sensitive data or is writable) |
 | LOW | FTP exposed externally (plaintext protocol — credentials/data in cleartext; use FTPS/SFTP) |
 | LOW | Telnet exposed externally (plaintext protocol — credentials/data in cleartext; use SSH) |

config.json.sample

@@ -18,7 +18,7 @@
     "resume" : false,
     "__check_for_updates_note__": "Optional. When true, SpooNMAP contacts api.github.com at startup to see whether a newer release exists. Default false, and absent means false: the tool makes no network connection other than the scan itself unless you turn this on. Use --check-update for a one-off check without enabling it here.",
     "check_for_updates": false,
-    "__honeypot_active_confirm_note__": "Optional. When true, SpooNMAP attempts a small number of raw TCP connects against unscanned high ports on any host flagged as a suspected honeypot, to confirm it. Default false, and absent means false: the tool sends no traffic beyond the scan itself unless you turn this on. A confirmed host answered a port that was never part of this scan, which is a strong tell that it accepts every connection rather than running a real service.",
+    "__honeypot_active_confirm_note__": "Optional. When true, SpooNMAP attempts a small number of raw TCP connects against unscanned high ports on any host flagged by the TTL-spread or port-profile signals, to confirm it. Hosts flagged only by the tarpit open-port-ratio heuristic are not probed. Default false, and absent means false: the tool sends no traffic beyond the scan itself unless you turn this on. A confirmed host answered a port that was never part of this scan, which is a strong tell that it accepts every connection rather than running a real service. Limitations: hosts outside target_file are never probed; on a Full (1-65535) scan there are almost no unscanned ports left to probe, so it does little or nothing; and honeypot detection as a whole only runs on the masscan path, not the direct-nmap path used for scans below nmap_threshold.",
     "honeypot_active_confirm": false,
     "__target_scan_choices__" : "External, Internal (case-insensitive; any other value stops the run rather than scanning with the Internal-only checks silently skipped)",
     "target_scan" : "Internal",

spoonmap.py

@@ -6195,11 +6195,17 @@ def _filter_udp_live_hosts(output_path):
     'honeypot_active_confirm': [
         ('__honeypot_active_confirm_note__',
          'Optional. When true, SpooNMAP attempts a small number of raw TCP connects '
-         'against unscanned high ports on any host flagged as a suspected honeypot, '
-         'to confirm it. Default false, and absent means false: the tool sends no '
-         'traffic beyond the scan itself unless you turn this on. A confirmed host '
-         'answered a port that was never part of this scan, which is a strong tell '
-         'that it accepts every connection rather than running a real service.'),
+         'against unscanned high ports on any host flagged by the TTL-spread or '
+         'port-profile signals, to confirm it. Hosts flagged only by the tarpit '
+         'open-port-ratio heuristic are not probed. Default false, and absent means '
+         'false: the tool sends no traffic beyond the scan itself unless you turn '
+         'this on. A confirmed host answered a port that was never part of this '
+         'scan, which is a strong tell that it accepts every connection rather than '
+         'running a real service. Limitations: hosts outside target_file are never '
+         'probed; on a Full (1-65535) scan there are almost no unscanned ports left '
+         'to probe, so it does little or nothing; and honeypot detection as a whole '
+         'only runs on the masscan path, not the direct-nmap path used for scans '
+         'below nmap_threshold.'),
     ],
     'target_scan': [
         ('__target_scan_choices__',