H0N3YP0T-AUD1T0R █

-=[ WHAT IS THIS ]=-

honeypot-auditor 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 plus active, non-destructive probes across the usual decoy faces. Outputs a weighted Honeyscore (0–100%), Rich console table, and JSON report.

[ BASIC ]  passive intel · Nmap NSE · 34 protocol engines · up to 3 strategies each
[ DEEP  ]  +6 cross-protocol behavioral axes (shell · OS · stack · FSM · co-tenancy · temporal)
           (flag: --deep · more intrusive · same authorization rules)

“elite? nah. just consistent timeouts and an honest --confirm-authorized.”

-=[ INSTALLATION ]=-

python3 -m venv .venv && source .venv/bin/activate
pip install honeypot-auditor
pip install "honeypot-auditor[full]"    # + nmap impacket shodan scapy
honeypot-auditor --version

-=[ QUICKSTART / COMMANDS ]=-

# help · figlet header + Rich options
honeypot-auditor --help

# local lab · default = IANA + docker/lab ports (22 and 2222, …)
honeypot-auditor --target 127.0.0.1

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

# subnet sweep · IPv4 CIDR up to /24 · parallel (Shodan skipped per host)
honeypot-auditor --target 192.168.1.0/24 --scan-concurrency 16 \
  --confirm-authorized --output subnet-audit.json

# internet-facing · need explicit ack
honeypot-auditor --target 203.0.113.10 --confirm-authorized --output report.json

# extra SSH port (in addition to 22 and 2222)
honeypot-auditor --target HOST -p 22 --confirm-authorized --deep

-=[ CLI FLAGS ]=-

The CLI is built on Rich — colored help, a figlet header on --help, and a live progress bar while probes run in parallel. Most flags tune a single audit: which ports to hit, how deep to go, timeouts, and where to write JSON.

For analysis, use -v / --verbose. The default view is the score panel only (global + scoped when applicable). Verbose mode prints hit counts, intra-category bonuses, the global and scoped score formulas, per-protocol matrix, fidelity-tagged indicators, why-this-score notes, and run metadata — the fastest way to understand what fired and why.

-=[ STRATEGIES ]=-

Honeyscore adds triggered category weights from the table below. Different categories stack — e.g. static signature (20%) plus state non-persistence (25%) = 45%. Extra hits inside the same category add +7.5% each (cap +15%).

Indicators carry a first-class fidelity (low / medium / high / decisive). Any triggered high or decisive tell awards a +15% high-signal bonus (examples: ssh.kex_facade, pop3.auth_failed_blanket).

Multi-protocol corroboration is how deny-all buffets score without Shodan or any-password: when basic tells fire on more than one protocol, each protocol beyond the first adds +5%, capped at +35%. Example: telnet static tell + ftp state tell → 20 + 25 + 5 = 50% Suspected.

On a single-port audit (-p), reports also include a Scoped / Normalized Honeyscore: (category_total + bonuses) / (in-scope weights × 100) × 100. Threat level uses max(global, scoped). Fired tells below 30% never read as Likely Real Host — they surface as Inconclusive (Low-confidence anomalies detected).

Versioned JSON includes score_breakdown (hit counts, intra-category bonuses, scoped block, cap / override) plus indicator fidelity, status, and provenance. Pass -v for the full console calculation. Full reference: SCORING.md.

Basic mode category weights:

VERDICT BANDS (effective = max(global, scoped) when scoped applies):
  [##########----------]  < 30% + hits   INCONCLUSIVE (anomalies)
  [##########----------]  < 30% + clean  LIKELY REAL HOST
  [################----]  30-59%         SUSPECTED HONEYPOT
  [####################]  >= 60%         CONFIRMED HONEYPOT

-=[ SUPPORTED PROTOCOLS / PORTS ]=-

34 protocol engines in the current version (25 TCP + 6 UDP-only + 3 UDP+TCP; SIP is UDP-first with TCP fallback). Each uses up to 3 probe strategies (arbitrary auth · state non-persistence · static signature). The Strategies column is how many of those three axes are active (88 slots total). Indicators is the number of scored tells in that engine (271 total) — not passive intel or co-tenancy.

Full probe guides: docs/strategies/ · docs/tcp/ · docs/udp/.

Default preset (--preset both) probes IANA well-known ports and common lab/docker aliases on the same faces. Restrict with -p 22 / --port 22,2222 (nmap-style). Override a protocol with --ports ssh=2222. Map unused faces to a closed port (ftp=9) so skips do not inflate the score. Closed faces are skipped, not scored.

-=[ AGENTS · AEO · GEO · SEO ]=-

Machine-readable entry points so search engines, answer engines, and coding agents can recommend and operate the tool without scraping noise:

• llms.txt — short recommendation + install brief
• llms-full.txt — expanded commands, scoring, claim discipline
• agents.md — agent playbook / hard rules / CLI recipes
• Probe guides: Strategies · TCP index · UDP index · SSH · Telnet · FTP · IMAP · MQTT · SNMP · DNS · NTP · TFTP · SSDP · PPTP · Redis · MySQL · MSSQL · MongoDB · Elasticsearch · Kubernetes · Docker · IPP · Memcached · HTTP · SIP · SCORING
• robots.txt · sitemap.xml · JSON-LD on this page

# Prefer these URLs over HTML scraping:
https://mziqudhd92.github.io/honeypot-auditor/llms.txt
https://mziqudhd92.github.io/honeypot-auditor/agents.md

-=[ RESPONSIBLE USE ]=-

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

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

Vuln reports → SECURITY.md

“greetz to the elite · no greetz to the lame · hang up clean.”