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

Version: 0.5.0
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 | Shodan intel, Nmap NSE (optional), SSH/Telnet/SMB/FTP/HTTP/Redis/SMTP/VNC/SIP/MySQL/Git/RDP/HTTP-proxy/MSSQL/MongoDB |
| 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 --skip-nmap

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

# Subnet sweep (max /24; Shodan skipped; default 8 parallel hosts)
honeypot-auditor --target 192.168.1.0/24 --skip-nmap --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 (v0.5.0)
honeypot-auditor --target DECOY --preset deception-audit --deep -v --confirm-authorized

# Red authorized OPSEC (v0.5.0)
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: Shodan 25%, arbitrary auth 30%, state non-persistence 25%, static signature 20%, co-tenancy 15%. Different categories stack. 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. Default console prints the score panel only; pass `-v` for strategy breakdown and per-protocol HIT/clean/skip/— matrix. JSON always includes `protocol_strategies`. 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:
- < 30% 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 |
| 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)
- `--output report.json` — subnet default: `honeypot-audit-subnet-<cidr>.json`
- `--confirm-authorized` (required if any scanned IP is public)
- `-v`, `--verbose` — strategy breakdown, per-protocol matrix, indicator table, why-this-score, run notes (default is score panel only)
- `--skip-nmap`
- `--deep`
- `--timeout SECS` (default 3)

## Subnet JSON shape

```json
{
  "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/sitemap.xml
- https://mziqudhd92.github.io/honeypot-auditor/robots.txt