3.0.0

Knock-Knock 3.0.0

3.0 turns Knock-Knock from a fixed multi-protocol honeypot into an extensible platform.
Every protocol is now a self-contained, declarative module, and ships a batch of intel and
deployment upgrades on top of it.

✨ Highlights

• 🧩 Protocol extensibility framework — add a honeypot protocol as a single self-contained
  module (protocols/*.py), no more hand-editing the monitor, web app, DB layer, and dashboard.
• 📡 8 → 13 protocols — all originals back-ported onto the framework, plus 5 new protocols
  spanning IoT messaging, industrial control, and infrastructure (MQTT, Node-RED, Modbus, S7, SNMP),
  proof the framework reaches well beyond the classic login-service honeypots.
• 🐳 One-line Docker on Linux — host networking is the new default: no port list to keep in
  sync with ENABLED_PROTOCOLS, and self-redaction configures itself. Setup is one .env line.
• 🛡️ IP blocklist as a first-class threat feed — a /blocklist consumer guide, hourly feeds,
  and download analytics.
• 📧 SMTP body capture + self-redaction — full message bodies, deduplicated and scrubbed of
  your server's own identity (even inside base64/MIME).

🧩 The extensibility framework (the heart of 3.0)

Adding a protocol used to mean touching the monitor, the web app, the storage layer, and the
dashboard. Now a protocol declares everything about itself — ports, capture, storage, and display —
through one ProtocolDefinition, and the framework wires up the rest (protocol_api.py,
protocols/registry.py). See docs/HOW_TO_ADD_A_PROTOCOL.md.

• All 8 built-in protocols (SSH, Telnet, FTP, RDP, SMB, SIP, HTTP, SMTP) run on the framework —
  proof it carries the originals, not just new work.
• 5 new industrial/IoT/OT protocols — MQTT, Node-RED, Modbus, S7, SNMP — built on the
  framework, showing it extends cleanly to new domains. Enable any of them via ENABLED_PROTOCOLS.
• User-overridable per-protocol display — choose which feed/detail fields show and which layout
  a protocol uses, for built-ins and anything you add.

🐳 Drop-dead-simple Docker on Linux

Bridge mode used to require editing docker-compose.override.yml to publish every honeypot port
(kept in sync with ENABLED_PROTOCOLS) and hand-setting REDACT_SELF_IPS/DEFAULT_HOSTNAME.
The new docker-compose.host.yml — active by default via a single COMPOSE_FILE= line in .env —
removes all of it: honeypots bind host ports directly (no port list to maintain) and
self-redaction discovers the host's own identity automatically. Setup is one line. It's also the
reliable choice for UDP/SIP, where bridge NAT can mask the real attacker source IP. Bridge
networking stays as the portable fallback for Docker Desktop / macOS / Windows.

🛡️ IP blocklist, promoted to a first-class feed

The public blocklist has existed since v1; 3.0 surfaces it properly, via a dedicated /blocklist
consumer guide (CSF / CrowdSec / ipset / nftables / pfSense recipes), hourly regeneration, 365-day
and 30-day feeds, and download analytics.

📧 SMTP intelligence

• Body capture, dedup & self-redaction — bodies captured in full (up to 64 KB), stored
  deduplicated (smtp_body_intel, one row per distinct body), with your own IP/host/domain removed
  even when hidden inside base64 / quoted-printable / MIME parts. The live feed shows a decoded preview.
• Opt-in header capture (SMTP_SAVE_HEADERS=true) — a DB-only analysis corpus for future
  campaign/header intel; off by default.

🔧 Also in 3.0

• HTTP exploit classifier grown to ~250 named signatures with a regression suite.
• Per-knock detail view — right-click / long-press any live-feed entry for the full record.
• "Internet Background Radiation" explainer
• Shared per-IP throttling across all protocols; hardened, CI-tested Docker image.

⬆️ Upgrading

3.0 has a one-time database migration (SMTP body storage). Run updatedb.py before restarting —
it backs up the DB first and is idempotent. Full steps in INSTALL.md → Upgrading from 1.x or 2.x.

• Systemd: git pull → pip install -r requirements.txt →
  python extras/db-migrations/updatedb.py → ./restart.sh.
• Docker: git pull → docker compose pull → run updatedb.py in the new image
  (docker compose run --rm --no-deps honeypot-monitor python extras/db-migrations/updatedb.py) →
  docker compose up -d. ⚠️ A git pull alone won't update a Docker install — the app is baked
  into the image, so you must pull the new image.
• New Docker default is host networking (Linux). Existing bridge installs keep working unchanged
  (their .env has no COMPOSE_FILE line); to switch, add COMPOSE_FILE=docker-compose.host.yml
  and ensure real sshd is off port 22.

Full changelog: CHANGELOG.md · Compare: v2.0.1...v3.0.0