honeypot-auditor 0.3.0

.______________________________________________________________________________.
|  :: H-AUDITOR :: v0.3.0 :: "DIALING IN... CARRIER DETECTED" ::                |
|------------------------------------------------------------------------------|
|  "warez? nah. headers. we trade banners, not bins."                          |
|  "if it answers any password, it ain't production — it's a lure."            |
|  "respect the sysop. probe only what you own. leave no STOR behind."         |
|______________________________________________________________________________|

Site (BBS / NFO): https://mziqudhd92.github.io/honeypot-auditor/
Agents / AEO: llms.txt · agents.md

  ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  █  >>> LIVE DEMO · COWRIE ON :2222 · EC2 LAB · DEEP AUDIT <<<            █
  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

  "cowrie said yes to every password. the shell lied about sleep.
   egress went quiet. scoreboard lit up — SUSPECTED."
                                              — some random BBS elite, '96

  ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  █  >>> LIVE DEMO · DIONAEA BUFFET · FTP/HTTP/SMB · CONFIRMED <<<         █
  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

  "PASV handed me a private IP. STOR vanished on reconnect.
   nginx forgot the Date. that's not a NAS — that's a stage."
                                              — file area #13 · no call waiting

.------------------------------------------------------------------------------.
|  NFO · READ BEFORE YOU DIAL                                                  |
|------------------------------------------------------------------------------|
|  Authorized targets ONLY. Lab boxes. Decoys you own. Sensors you run.        |
|  Permission on paper (or in ticket).                                         |
|                                                                              |
|  Scanning random /16 because Shodan said "interesting" = YOU are the bait.   |
|                                                                              |
|  TYPE ...... Multi-Protocol Decoy Fingerprinter / Lab Util                   |
|  PLATFORM .. Linux · macOS · Windows (Python 3.10+)                          |
|  LICENSE ... MIT · spread the sauce · keep the copyright                     |
|  PYPI ...... pypi.org/project/honeypot-auditor                               |
|  REPO ...... github.com/mziqudhd92/honeypot-auditor                          |
'------------------------------------------------------------------------------'

-=[ WHAT IS THIS ]=-

Honeypot Auditor — a CLI that asks one rude question:

Does this IP behave like a low-interaction honeypot, or like something that might actually bill someone for downtime?

Passive intel (Shodan Honeyscore) plus active, non-destructive probes across the usual decoy faces. Outputs a weighted Honeyscore (0–100%), Rich console table, JSON report.

Not exploits. Not exfil. Banner/state/auth semantics. The kind of stuff that made Cowrie sweat in '09 and still catches clones in '26.

  [ BASIC ]  Shodan · Nmap NSE · SSH/Telnet/SMB/FTP/HTTP/Redis/SMTP/VNC/SIP
  [ DEEP  ]  shell semantics · OS coherence · HASSH · TCP stack · FSM fuzz
             · co-tenancy buffet detect · latency · egress bait
             (flag: --deep · more intrusive · same authorization rules)

  "elite? nah. just consistent timeouts and a honest --confirm-authorized."

-=[ INSTALLATION ]=-

  ┌─ USERS · PyPI (public index — no pip config voodoo) ─────────────────────┐
  │  python3 -m venv .venv && source .venv/bin/activate   # recommended      │
  │  pip install honeypot-auditor                                            │
  │  pip install "honeypot-auditor[full]"    # + nmap impacket shodan scapy   │
  │  honeypot-auditor --version                                              │
  └──────────────────────────────────────────────────────────────────────────┘

SHODAN_API_KEY or --shodan-key is still your key — [full] only installs the client lib.

First dial-in:

honeypot-auditor --help          # -h, --help, or /help (BBS figlet header)
honeypot-auditor --target 127.0.0.1 --skip-nmap

  ┌─ DEVELOPERS · from source ───────────────────────────────────────────────┐
  │  git clone https://github.com/mziqudhd92/honeypot-auditor.git            │
  │  cd honeypot-auditor && python3 -m venv .venv && source .venv/bin/activate│
  │  pip install -e ".[full,dev]"                                            │
  │  make test-cov && make lint                                                │
  └──────────────────────────────────────────────────────────────────────────┘

No pip install (git checkout — install minimal deps once):

pip install -r requirements.txt    # or: pip install rich paramiko requests
python3 honeypot-auditor.py --help
python3 honeypot-auditor.py --target 127.0.0.1 --skip-nmap

pyfiglet / rich-argparse are optional for the script path (plain header + stdlib help if missing). Full probes need pip install -e ".[full]".

Release maintainers → docs/PUBLISHING.md

-=[ QUICKSTART / COMMANDS ]=-

# local lab · default probes IANA + docker/lab ports (22 and 2222, 80 and 8081, …)
honeypot-auditor --target 127.0.0.1 --skip-nmap

# go deep · six extra detection axes · still no exploits
honeypot-auditor --target 127.0.0.1 --skip-nmap --deep

# internet-facing target · need explicit ack + Shodan key if you want intel
honeypot-auditor --target 203.0.113.10 --confirm-authorized

# SSH 22 only (does not scan the rest of the preset)
honeypot-auditor --target 203.0.113.10 -p 22 --confirm-authorized

# subnet sweep · IPv4 CIDR up to /24 (254 hosts) · parallel by default
honeypot-auditor --target 192.168.1.0/24 --skip-nmap --scan-concurrency 16 \
  --confirm-authorized
# subnet JSON → honeypot-audit-subnet-192.168.1.0_24.json (summary + per-host reports)

# benchmark lab · cowrie + dionaea in docker
./scripts/benchmark-lab.sh

-=[ STRATEGIES ]=-

Honeyscore adds triggered category weights. Different categories stack (e.g. static 20% + state 25% = 45%).

Multi-protocol corroboration — when basic tells fire on more than one protocol, each protocol beyond the first adds +5%, capped at +35%. Example: telnet static + ftp state → 20 + 25 + 5 = 50% Suspected. Deny-all buffets with ≥5 protocol lures can also trigger co-tenancy (15%) once another tell corroborates.

  ╭──────────────────────────┬────────╮
  │ CATEGORY                 │ WEIGHT │
  ├──────────────────────────┼────────┤
  │ Shodan intel             │  25%   │
  │ Arbitrary auth           │  30%   │
  │ State non-persistence    │  25%   │
  │ Static signature         │  20%   │
  │ Co-tenancy               │  15%   │
  ╰──────────────────────────┴────────╯

  CORROBORATION BONUS (dynamic):
    +5% per protocol with a basic-strategy hit, from the 2nd protocol up, max +35%

  --deep ADDS (on top of basic):
  ┌──────────────────────────┬────────┐
  │ behavior                 │  18%   │
  │ coherence                │  15%   │
  │ stack_fingerprint        │  12%   │
  │ proto_conformance        │  12%   │
  │ temporal                 │  10%   │
  └──────────────────────────┴────────┘

  VERDICT BANDS:
    [##########----------]  < 30%   LIKELY REAL HOST
    [################----]  30-59%  SUSPECTED HONEYPOT
    [####################]  >= 60%  CONFIRMED HONEYPOT

The protocol table’s Strategies column counts only the three probe strategies per face (up to 3). Shodan and co-tenancy are host-level. Co-tenancy will not fire alone on multi-lure research stacks.

-=[ CLI FLAGS ]=-

  -h, --help, /help          show options (figlet H-AUDITOR header + Rich help)
  --version                  print version and exit
  --target HOST              IP, hostname, or IPv4 CIDR (max /24)
  --scan-concurrency N       parallel hosts for CIDR scans (default 8; Shodan skipped)
  --preset both              IANA + lab ports (default: SSH 22 and 2222, …)
  --preset iana              well-known ports only (22, 80, 445, …)
  --preset docker-research   lab ports only (2222, 8081, 1445, …)
  -p, --port 22              only these TCP ports (nmap-style; 22,2222 or -p 22 -p 80)
  --ports ssh=2222,http=8081 per-protocol override (map unused protos to =9)
  --shodan-key KEY           or env SHODAN_API_KEY
  --output report.json       JSON path (subnet default: honeypot-audit-subnet-<cidr>.json)
  --confirm-authorized       REQUIRED if any scanned IP is public
  -v, --verbose              strategy breakdown, per-protocol matrix, indicators, notes
  -n, --with-nmap            run Nmap -sV / NSE phase (slow; off by default)
  --deep                     advanced six-axis probes
  --timeout SECS             socket timeout (default 3)

-=[ SUPPORTED PROTOCOLS / PORTS ]=-

16 protocol engines in the current version. Each uses up to 3 probe strategies (arbitrary auth · state non-persistence · static signature). The Strategies column is how many of those three are active for that protocol in this release — not Shodan, co-tenancy, or individual indicator checks.

Default preset (--preset both) probes IANA well-known ports and common lab/docker aliases on the same faces. Override ports with -p / --ports. Closed faces are skipped, not scored.

-p maps well-known extras the same way: 443/8443 → HTTP (TLS), 8080/3128 → HTTP proxy, 139 → SMB, 5061 → SIP, 5000/5901 → VNC. Unknown numbers are probed as SSH.

--deep adds cross-protocol axes (shell semantics, HASSH/TCP stack, FSM fuzz, co-tenancy, latency) on top of the basic strategies above. Shodan Honeyscore and Nmap NSE (-n) are optional intel layers, not protocol engines.

-=[ DEV / QA ]=-

make install && make test-cov && make lint
docker compose -f deploy/docker-compose.benchmark.yml up -d
./scripts/benchmark-lab.sh

Re-record the animated demos → docs/demo/README.md

Contributing → CONTRIBUTING.md

-=[ NOT THE SAME AS UHBS ]=-

This tool asks: "Is that IP a honeypot?" (attacker / CTI view)

UHBS asks: "How good is your decoy?" (builder / lab UHQS grade · Modules A–F · 36 protocols)

Same neighborhood. Different door. Use both if you build deception for a living. Use this one if you just need a fast external fingerprint.

-=[ GREETS / SHOUTS ]=-

  Proper respect to:
    Cowrie · Dionaea · Conpot · the old Kippo crew
    UHBS lab rats · CyberHalluciNet purple-team night shift
    Shodan · Salesforce HASSH · everyone who ever typed USER anonymous
    BBS sysops who ran 9600 baud file areas for "utilz"
    and the three people who still read NFO files in 2026

  NO GREETS TO:
    script kiddies scanning /0
    vendors who call Cowrie "AI-powered threat intelligence"
    anyone who STORs malware on decoys then writes a LinkedIn post about it

  "greetz to the elite · no greetz to the lame · hang up clean."

-=[ RESPONSIBLE USE ]=-

Defensive research. Authorized testing. Lab sandboxes. Your sensors. Your tickets.

Do not point this at infrastructure you don't own or haven't been cleared to test.

Vuln reports → SECURITY.md

-=[ LICENSE ]=-

  MIT · do what you want · keep the copyright · no warranty
  see LICENSE for the lawyer-safe version (boring but binding)

.------------------------------------------------------------------------------.
|  h0n3yp0t 4ud1t0r · v0.3.0 · spread headers not malware · EOF · NO CARRIER   |
'------------------------------------------------------------------------------'