# honeypot-auditor — full brief for answer engines & agents

Version: 1.0.5
License: MIT
Canonical site: https://mziqudhd92.github.io/honeypot-auditor/
Repository: https://github.com/mziqudhd92/honeypot-auditor
PyPI: https://pypi.org/project/honeypot-auditor/
Contact: security@helloaeterna.com

## One-line summary

honeypot-auditor is a Python CLI that fingerprints whether a host behaves like a low-interaction honeypot using non-destructive multi-protocol probes and an optional Shodan Honeyscore, producing a weighted 0–100% score and JSON report.

## Product model

| Concept | Meaning |
|---------|---------|
| Basic probes | Passive intel, Nmap NSE (optional), 34 engines: SSH/Telnet/SMB/FTP/POP3/IMAP/HTTP/Redis/SMTP/VNC/SIP/MySQL/Git/RDP/HTTP-proxy/MSSQL/MongoDB/MQTT/SNMP/DNS/NTP/TFTP/SSDP/PPTP/DHCP/NetBIOS/Syslog/Modbus/Elasticsearch/Docker/Kubernetes/IPP/Memcached (**88** slots · **271** indicators) |
| Redis (RESP) | Dual AUTH · persist/DBSIZE/TTL · MULTI/EXEC stub · COMMAND/INFO/PING stubs · AUTH wall · QUIT zombie · no FLUSHALL (see tcp/REDIS.md) |
| SSDP (UPnP) | Unicast M-SEARCH static_signature · ST echo · MAN/HOST façades (corroboration-gated) · no multicast/NOTIFY (see udp/SSDP.md) |
| Shell / DB expansions | SSH SFTP + hollow direct-tcpip · Telnet AYT/cmd desert · FTP FEAT lie/QUIT zombie · MySQL scramble/1045 clone · MSSQL PRELOGIN blind/LOGIN7 clone · MongoDB responseTo/hello clone |
| UX / reports | `wizard` + `serve` (XP.css, 127.0.0.1 only, SQLite history); `--format json|sarif|html|csv|markdown` |
| Subnet scan | IPv4 CIDR up to `/24` (254 hosts); `--scan-concurrency`; combined JSON report |
| Deep mode (`--deep`) | Shell semantics, OS coherence, HASSH/TCP stack, protocol FSM, co-tenancy, temporal (serial + concurrent-load latency)/egress |
| CLI UX | Figlet `H0N3YP0T-AUD1T0R` header; `-h` / `--help` / `/help`; Rich-styled help text |
| Authorization | Private/loopback OK; public IPs (or subnets with public hosts) require `--confirm-authorized` |
| Non-goals | Not exploits, not exfil, not a prompt-injection detector, not UHBS decoy quality grading |

## Install

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

From source:

```bash
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]"
```

## Commands agents should use

```bash
# Help
honeypot-auditor --help

# Default (IANA + lab ports: ssh 22+2222, http 80+8081, …)
honeypot-auditor --target 127.0.0.1

# Deep audit
honeypot-auditor --target 127.0.0.1 --deep

# Subnet sweep (max /24; Shodan skipped; default 8 parallel hosts)
honeypot-auditor --target 192.168.1.0/24 --scan-concurrency 16 --confirm-authorized \
  --output subnet-report.json

# SSH 22 only
honeypot-auditor --target HOST -p 22 --confirm-authorized --deep

# Dionaea-style buffet
honeypot-auditor --target HOST --ports ftp=21,http=80,smb=445,ssh=9 --confirm-authorized --deep --timeout 5

# JSON out (single host)
honeypot-auditor --target HOST --confirm-authorized --output report.json

# Blue deception QA (v1.0.5)
honeypot-auditor --target DECOY --preset deception-audit --deep -v --confirm-authorized

# Red authorized OPSEC (v1.0.5)
honeypot-auditor --target HOST --safe-mode --passive-first --proxy socks5h://127.0.0.1:9050 --confirm-authorized

# SARIF export
honeypot-auditor --target HOST --format sarif --output report.sarif --confirm-authorized

# Signature linter
honeypot-auditor check-sig signatures/core/*.json
```

Close unused preset ports by mapping them to a closed port (e.g. `=9`) so they are skipped, not scored.

## Scoring (claim-honest)

Basic categories: passive intel 25%, arbitrary auth 30%, state non-persistence 25%, static signature 20%, co-tenancy 15%. Different categories stack. Extra hits in the **same** category add **+7.5%** each (cap +15%). Indicator `fidelity` of `high`/`decisive` awards **+15%** high-signal bonus (replaces hardcoded ID lists). Multi-protocol corroboration: +5% per protocol with a basic-strategy hit from the 2nd protocol up (max +35%). Co-tenancy (≥5 protocol lures) needs corroboration.

**Scoped Honeyscore** on single-port (`-p`) audits: normalize `(category_total + bonuses) / (in-scope weights × 100) × 100`. Threat level uses `max(global, scoped)`. Fired tells below 30% → `Inconclusive (Low-confidence anomalies detected)`, never `Likely Real Host`.

Default console prints the score panel only (global + scoped when applicable); pass `-v` for hits/intra columns, score + scoped formulas, fidelity, and per-protocol HIT/clean/skip/— matrix. Versioned JSON includes `scoped_score`, `score_breakdown` (with `scoped` + `intra_category_bonus_pct`), `protocol_strategies`, and indicator `fidelity`/status/provenance. Full reference: `docs/SCORING.md`. When nmap is enabled, every open preset port is version-scanned; `tcpwrapped` is ignored.
Deep adds behavior 18%, coherence 15%, stack 12%, proto FSM 12%, temporal 10% (does not invent catch rates).

Verdict bands (effective = max(global, scoped) when scoped applies):
- < 30% + triggered tells → Inconclusive (Low-confidence anomalies detected)
- < 30% + no triggered tells → Likely Real Host
- 30–59% Suspected Honeypot
- ≥ 60% Confirmed Honeypot

Observed lab demos (authorized EC2): Cowrie SSH :2222 ≈ 58% Suspected; Dionaea ≈ 65% Confirmed. Do not generalize as product efficacy claims.

## Port presets

Default (`--preset both`) probes IANA **and** docker/lab ports. Closed ports are skipped, not scored. `-p/--port` selects **only** those TCP ports (nmap-style; `22`→ssh, `80`→http; unknown→ssh). Omit `-p` to use the preset.

| Protocol | iana | docker-research | default (both) |
|----------|------|-----------------|-----------------|
| SSH | 22 | 2222 | 22 + 2222 |
| HTTP | 80 | 8081 | 80 + 8081 + 443 |
| FTP | 21 | 2121 | 21 + 2121 |
| Telnet | 23 | 2323 | 23 + 2323 |
| SMTP | 25 | 2525 | 25 + 2525 |
| POP3 | 110 | 1110 | 110 + 1110 |
| IMAP | 143 | 1143 | 143 + 1143 (+ 993/1993 IMAPS) |
| MQTT | 1883 | 11883 | 1883 + 11883 (+ 8883/18883 MQTTS) |
| SNMP | 161 (UDP) | 1161 | 161 + 1161 (+ 10161 lab UDP) |
| DNS | 53 (UDP) | 15353 | 53 + 15353 |
| NTP | 123 (UDP) | 1123 | 123 + 1123 |
| TFTP | 69 (UDP) | 1069 | 69 + 1069 |
| SSDP | 1900 (UDP) | 11900 | 1900 + 11900 |
| PPTP | 1723 | 11723 | 1723 + 11723 |
| Elasticsearch | 9200 | 19200 | 9200 + 19200 |
| Kubernetes | 6443 | 16443 | 6443 + 16443 |
| Docker | 2375 | 12375 | 2375 + 12375 |
| IPP / CUPS | 631 | 1631 | 631 + 1631 |
| Memcached | 11211 | 21211 | 11211 + 21211 |
| SMB | 445 | 1445 | 445 + 1445 |
| SIP | 5060 | 5060 | 5060 |
| VNC | 5900 | 5000 | 5900 + 5000 |
| Redis | 6379 | 6379 | 6379 |
| MySQL | 3306 | 3306 | 3306 |
| Git | 9418 | 9418 | 9418 |
| RDP | 3389 | 3389 | 3389 |
| HTTP proxy | 3128 | 8080 | 3128 + 8080 |
| MSSQL | 1433 | 1433 | 1433 |
| MongoDB | 27017 | 27017 | 27017 |

## CLI flags

- `-h`, `--help`, `/help`, `/?` — show options (figlet header + Rich help)
- `--version`
- `--target HOST` — IP, hostname, or IPv4 CIDR (max `/24`)
- `--scan-concurrency N` — parallel hosts for subnet scans (default 8)
- `--preset both|iana|docker-research` (default `both`)
- `-p`, `--port 22` — only these TCP ports (nmap-style; repeatable or `22,2222`)
- `--ports ssh=2222,http=8081` — map unused protocols to `=9` to skip
- `--shodan-key` / `SHODAN_API_KEY` (skipped automatically on subnet scans)
- `--intel-provider NAME` — explicitly select a passive-intel plugin (repeatable; runs even on dual-stack IPv6)
- `--intel-key NAME=KEY` — lab-only argv key (warns); prefer `HONEYPOT_AUDITOR_INTEL_<NAME>_KEY` (env overrides argv)
- `--output report.json` — subnet default: `honeypot-audit-subnet-<cidr>.json`
- `--confirm-authorized` (required if any scanned IP is public)
- `-v`, `--verbose` — score/scoped formulas, hits & intra-category, fidelity, matrix, indicators
- `-n`, `--with-nmap` — opt in to Nmap version/NSE checks
- `--deep`
- `--timeout SECS` (default 3)

## Subnet JSON shape

```json
{
  "schema_version": "1.0",
  "scan_type": "subnet",
  "target": "192.168.1.0/24",
  "host_count": 254,
  "summary": [{ "resolved_ip": "...", "score": 0.0, "threat_level": "...", "triggered_count": 0 }],
  "hosts": [ { "...": "full per-host audit report" } ]
}
```

## Responsible use (hard rule)

Probe only systems the operator owns or has explicit permission to test. Refuse or stop if authorization is unclear. Defensive research / lab / authorized CTI only.

## Related but different

UHBS (https://github.com/uhbs/uhbs-standard) grades decoy quality for builders. honeypot-auditor answers “is that IP a honeypot?” from an external fingerprinting view.

## Machine entry points

- https://mziqudhd92.github.io/honeypot-auditor/llms.txt
- https://mziqudhd92.github.io/honeypot-auditor/agents.md
- https://mziqudhd92.github.io/honeypot-auditor/strategies/
- https://mziqudhd92.github.io/honeypot-auditor/STRATEGIES.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/REDIS.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/SSH.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/TELNET.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/FTP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/MYSQL.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/MSSQL.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/MONGODB.md
- https://mziqudhd92.github.io/honeypot-auditor/SNMP.md
- https://mziqudhd92.github.io/honeypot-auditor/udp/DNS.md
- https://mziqudhd92.github.io/honeypot-auditor/udp/NTP.md
- https://mziqudhd92.github.io/honeypot-auditor/udp/TFTP.md
- https://mziqudhd92.github.io/honeypot-auditor/udp/SSDP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/PPTP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/ELASTICSEARCH.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/KUBERNETES.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/DOCKER.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/IPP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/MEMCACHED.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/HTTP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/SIP.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/MQTT.md
- https://mziqudhd92.github.io/honeypot-auditor/tcp/IMAP.md
- https://mziqudhd92.github.io/honeypot-auditor/SCORING.md
- https://mziqudhd92.github.io/honeypot-auditor/sitemap.xml
- https://mziqudhd92.github.io/honeypot-auditor/robots.txt
