honeypot-auditor 1.0.0

.______________________________________________________________________________.
|  :: H-AUDITOR :: v1.0.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."         |
|______________________________________________________________________________|

Does This Look Like An Honeypot? (DTLLAH) — Multi-protocol CLI that fingerprints whether a target IP behaves like an honeypot, implement different strategies to identify honeypots.

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

  ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  █  >>> LIVE DEMO · v1.0.0 · 3-FACE LAB TOUR · -v / --deep / TARPIT <<<   █
  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

  "three faces, three lenses: KEX facade with -v, deep on the buffet,
   silent-accept on the tarpit. same fingerprinter — different tells."
                                              — lab tour · v1.0.0 · authorized only

.------------------------------------------------------------------------------.
|  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, versioned JSON report.

Quickstart Tutorial: AWS Spot honeypot lab

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 ]  passive intel · Nmap NSE · 29 protocol engines (TCP + UDP) · up to 3 strategies each
  [ DEEP  ]  shell semantics · OS coherence · HASSH · TCP stack · FSM fuzz
             · co-tenancy buffet detect · latency · latency-under-load · 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 enables Shodan OSINT (opt-in — not queried otherwise). [full] only installs the client lib. The Nmap executable is a separate trusted system installation.

Windows PowerShell uses py -m venv .venv followed by .\.venv\Scripts\Activate.ps1. Raw-socket probes can require Npcap and an elevated terminal; unavailable capabilities are reported and skipped.

First dial-in:

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

  ┌─ 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,security]"                                   │
  │  make test-cov && make lint && make security                             │
  └──────────────────────────────────────────────────────────────────────────┘

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

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

# go deep · six extra detection axes · still no exploits
honeypot-auditor --target 127.0.0.1 --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 --scan-concurrency 16 \
  --confirm-authorized
# subnet JSON → honeypot-audit-subnet-192.168.1.0_24.json (summary + per-host reports)

-=[ STRATEGIES ]=-

Honeyscore adds triggered category weights. Different categories stack (e.g. static 20% + state 25% = 45%). Extra hits inside the same category add +7.5% each (cap +15%). High-fidelity tells (fidelity: high|decisive, e.g. ssh.kex_facade, pop3.auth_failed_blanket) award a +15% high-signal bonus.

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.

Scoped Honeyscore (-p) — on a single-port audit, a normalized score is reported alongside the global score: scoped = (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).

Pass -v / --verbose for the full calculation: hit counts, intra-category bonuses, score/scoped formulas, fidelity, and the per-protocol matrix. See docs/SCORING.md.

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

  INTRA-CATEGORY: +7.5% per extra hit in the same category (cap +15%)
  HIGH-SIGNAL:    +15% when any triggered indicator has fidelity high|decisive
  CORROBORATION:  +5% per extra protocol with a basic-strategy hit (max +35%)

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

  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

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           enable Shodan (or env SHODAN_API_KEY); opt-in only
  --intel-provider NAME      opt in to a named passive-intel plugin (repeatable)
  --intel-key NAME=KEY       provider key; prefer HONEYPOT_AUDITOR_INTEL_<NAME>_KEY
  --output report.json       JSON path (subnet default: honeypot-audit-subnet-<cidr>.json)
  --confirm-authorized       REQUIRED if any scanned IP is public
  -v, --verbose              score formula, hits/intra, scoped math, matrix, indicators
  -n, --with-nmap            run Nmap -sV / NSE phase (slow; off by default)
  --deep                     advanced six-axis probes
  --safe-mode                handshake-only; disables deep shell/path probes
  --profile audit|blend       probe profile (default audit; blend=mimesis OPSEC)
  --proxy socks5h://host:port  SOCKS5 egress (remote DNS enforced)
  --passive-first            passive intel before active; skip active when score high
  --osint-only               passive intel only — no TCP probes
  --passive-first-confirm    after high passive / osint-only, run safe-mode active verify
  --dual-stack               resolve A+AAAA and compare IPv4 vs IPv6
  --jitter 0.3               fraction of timeout as max random delay (authorized OPSEC)
  --jitter-ms 50-500         random delay range in ms before each probe (authorized OPSEC)
  --max-concurrent 32        global socket concurrency budget
  --seed N                   RNG seed for blend profile
  --preset deception-audit   blue-team QA preset (both ports + --deep)
  --format json|sarif        report format (default json)
  --output-nmap-exclude path append IP when Honeyscore >= 60
  check-sig PATH             validate declarative signature pack offline
  --timeout SECS             socket timeout (default 3)

-=[ SUPPORTED PROTOCOLS / PORTS ]=-

See docs/STRATEGIES.md for more details.

-=[ 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
    @fusiontechstrategies — POP3, intel plugins, scoring/SARIF, Windows+security CI (v0.7.0)

  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 · v1.0.0 · spread headers not malware · EOF · NO CARRIER   |
'------------------------------------------------------------------------------'