Universal Honeypot Benchmarking Standard (UHBS)

Open-source beta framework for lab / sandbox evaluation of honeypots and decoys — vendor-neutral UHQS scoring (0–100) with a non-linear Safety Gate.

UHBS v4.3.5 measures deception realism, containment, scale, and telemetry quality by class and protocol. It is not an industry consortium standard or multi-party governed body. See ROADMAP.md for maturity goals.

NOTICE: UHBS/AEP are for lab/sandbox evaluation of decoys. Do not run them against production or unauthorized real services. CLI tools print this reminder on stderr when commands run.

Table of contents

• Project status
• What you get
• Install
• Quickstart
• Demo
• Scoring (UHQS)
• Optional Advanced Evidence Profile (AEP)
• Documentation map
• Repository layout
• Contributing
• Security
• Citation
• License

Project status

Status: Beta / Experimental — specification status

What you get

Vendor neutrality: normative docs use classes and protocols. Named products appear only under conformance as evaluation proof, not as UHBS requirements.

Install

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Core CLI (validate / score)
pip install uhbs

# Common lab install
pip install 'uhbs[lab]'

# Optional extras (install only what you need)
pip install 'uhbs[mcp]'   # AI-host MCP server
pip install 'uhbs[aep]'   # offline Advanced Evidence Profile
pip install 'uhbs[all]'   # lab + mcp + scapy (convenience; still not an attack runner)

Development checkout:

git clone https://github.com/mziqudhd92/uhbs-standard.git
cd uhbs-standard
pip install -e ".[lab,dev]"
# optional: pip install -e ".[aep,mcp]"
pytest -q

Quickstart

1. Validate a profile or scorecard

# From a git checkout (templates ship in the repo)
cp templates/profile.yaml ./my-honeypot.profile.yaml
uhbs validate-profile my-honeypot.profile.yaml

uhbs validate-scorecard path/to/scorecard.json
uhbs score --class Low-Interaction --scores scores.json

2. Run the lab harness (isolated decoy only)

pip install 'uhbs[lab]'
uhbs lab --list-protocols
# Example shape — point only at a lab decoy you control:
# uhbs lab --tps low_interaction --protocol ssh \
#   --target 127.0.0.1 --port 2222 --out ./.local/bench-reports/my-target

3. Optional AEP (offline lab evidence)

pip install 'uhbs[aep]'
uhbs aep example beginner --out aep-beginner
uhbs aep validate aep-beginner/experiment.yaml
uhbs aep analyze --experiment aep-beginner/experiment.yaml \
  --trials aep-beginner/trials.jsonl \
  --scorecard aep-beginner/linked-scorecard.json \
  --out advanced-evidence.json
uhbs aep report advanced-evidence.json --format markdown --out ADVANCED-EVIDENCE.md

MCP for AI hosts (Cursor, Claude, VS Code, …)

pip install 'uhbs[mcp]'
# Configure the host — see docs/tooling/mcp.md
# uhbs-mcp   or:  python -m uhbs_mcp

Registry metadata: server.json. Live lab probes stay on uhbs lab, not the AI-host MCP server.

Grade MCP honeypot surfaces (JSON-RPC over HTTP/SSE) with the in-tree mcp protocol plugin (uhbs[lab]) — different from the AI-host server above. See MCP honeypot grading.

Docker

docker build -t uhbs:4.3.5 .
docker run --rm -v "$PWD:/work" -w /work uhbs:4.3.5 \
  validate-scorecard ./docs/conformance/fixtures/cowrie-low-interaction.scorecard.json
docker run --rm -v "$PWD:/work" -w /work uhbs:4.3.5 lab --list-protocols

Compose: docker compose run --rm uhbs validate-profile ./my-honeypot.profile.yaml.

Demo

Terminal walkthrough: install UHBS + Cowrie/Conpot, start lab decoys, full UHQS (Cowrie SSH · Conpot Modbus · HellPot HTTP).

Replay: docs/assets/uhbs-lab-demo.cast (asciinema play docs/assets/uhbs-lab-demo.cast).

Scoring (UHQS)

The Universal Honeypot Quality Score is a normalized composite 0–100:

[ \mathrm{UHQS} = \delta_C \cdot (w_A S_A + w_B S_B + w_C S_C + w_E S_E + w_F S_F) ]

A decoy with strong deception scores can still fail lab evaluation if Module D is weak. Normative math: uhqs_math.py · scoring formula.

Lab audit workflow (5 phases)

Profile & config → Static audit (F) → Sandbox provision → Dynamic A–E → Score & report

Optional Advanced Evidence Profile (AEP)

UHQS remains the normative lab grade. AEP is an optional, informative layer for controlled lab decoy-vs-reference experiments. AEP does not change UHQS.

• Offline analysis of local experiment/trial files only — no attack launch
• Status vocabulary: valid | inconclusive | control_failed (not letter grades)
• Packaged examples: uhbs aep example beginner|advanced|template

Academic credit (citation ≠ endorsement): Zhu (2019), Collins et al. (2024), Ersok et al. (2022), Li et al. (2020) — full ledger: Research foundations & credits.

Documentation map

Repository layout

uhbs-standard/
├── docs/                      # MkDocs site + conformance proof
│   ├── advanced-evidence/     # Optional AEP docs
│   ├── conformance/           # Fixtures, lab reports, tutorials
│   ├── mappings/              # ATT&CK, D3FEND, Engage, related frameworks
│   └── specification/         # Normative prose
├── schemas/                   # JSON Schemas (scorecard, AEP, …)
├── templates/                 # Starter TPS + AEP templates
├── examples/advanced-evidence/# Synthetic AEP fixtures (also packaged in wheel)
├── src/uhbs_cli/              # `uhbs` CLI (+ packaged schemas / AEP data)
├── src/uhbs_core/             # UHBS-Lab harness + UHQS math
├── src/uhbs_mcp/              # AI-host MCP server
├── tests/                     # pytest suite
├── Dockerfile                 # Grading image
├── CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · GOVERNANCE.md
└── CITATION.cff

Embed a published grade

After you publish a scorecard (conformance / your own report), you can badge it:

![UHBS v4.3.5](https://img.shields.io/badge/UHBS%20v4.3.5-Grade%20A-brightgreen)

Contributing

Contributions are welcome under the project’s governance constraints.

1. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md
2. Follow GOVERNANCE.md — specification changes use an RFC process
3. Sign off commits (DCO)
4. Run pytest -q and ruff check on touched Python before opening a PR

Security

Please report vulnerabilities via GitHub Security Advisories per SECURITY.md. Do not use UHBS tooling against systems you are not authorized to test.

Citation

@software{uhbs2026,
  author = {Zavdi, Moran},
  title = {Universal Honeypot Benchmarking Standard (UHBS)},
  year = {2026},
  version = {4.3.5},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.21631156},
  url = {https://doi.org/10.5281/zenodo.21631156}
}

Machine-readable: CITATION.cff. Concept DOI (latest deposit): 10.5281/zenodo.21631155.

License

Licensed under the Apache License 2.0.