Open-source evaluation framework for lab / sandboxevaluation of honeypots and decoys — vendor-neutral UHQS scoring (0–100) with a non-linear Safety Gate.
UHBS v5.0.1 measures deception realism, containment, scale, and telemetry quality by class and protocol. It is not an industry consortium standard or multi-party governed body. Source and docs: github.com/uhbs/uhbs-standard · uhbs.github.io/uhbs-standard · ROADMAP.
| Link | |
|---|---|
| Docs | Landing · MkDocs |
| Install | pip install uhbs · extras: lab, mcp, aep |
| Python | ≥ 3.11 |
| License | Apache-2.0 |
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.
- What you get
- Install
- Quickstart
- Demo
- Scoring (UHQS)
- Optional Advanced Evidence Profile (AEP)
- Documentation map
- Repository layout
- Contributing
- Security
- Citation
- License
| Capability | Package / surface |
|---|---|
| Spec + schemas (TPS, scorecard, evidence) | Repo docs/ · schemas/ |
| Validate profiles & scorecards; recompute UHQS | pip install uhbs → uhbs |
| Live Modules A–F lab harness (36 protocols) | pip install 'uhbs[lab]' → uhbs lab / uhbs-lab |
| AI-host MCP tools (validate/score fixtures; no live probes) | pip install 'uhbs[mcp]' → uhbs-mcp |
| Offline Advanced Evidence Profile (optional; does not change UHQS) | pip install 'uhbs[aep]' → uhbs aep |
| AEP SLM trial generator (alpha; off until you edit config) | pip install 'uhbs[aep-slm]' → uhbs aep slm |
| Published lab grades / fixtures | docs/conformance/ |
Vendor neutrality: normative docs use classes and protocols. Named products appear only under conformance as evaluation proof, not as UHBS requirements.
| Pillar | Detail |
|---|---|
| Protocol-agnostic | IT, OT/ICS, AI, and cloud decoy classes |
| Quantitative | UHQS 0–100 with Safety Gate (\delta_C) from Module D |
| Dual-plane | Static audit (F) + dynamic Modules A–E |
| Optional AEP | Lab decoy-vs-reference evidence (VoD, FSV, DTDR, EER) |
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[aep-slm]' # alpha SLM trial helper (still off until you edit config)
pip install 'uhbs[all]' # lab + mcp + scapy (convenience; still not an attack runner)| Extra | Purpose |
|---|---|
| (none) | Validators + UHQS math |
lab |
Controlled live Modules A–F harness |
mcp |
Local AI-host scorecard tools (stdio MCP) |
aep |
Offline advanced evidence analysis |
aep-slm |
Alpha AEP SLM trial generator (disabled until you edit aep-slm.yaml) |
scapy |
Optional protocol-encoding backend |
dev |
pytest, ruff, mypy (+ lab/mcp for contributors) |
all |
lab + mcp + scapy |
Development checkout:
git clone https://github.com/uhbs/uhbs-standard.git
cd uhbs-standard
pip install -e ".[lab,dev]"
# optional: pip install -e ".[aep,mcp]"
pytest -qShort walkthrough: Install & use UHBS (install → validate profile → validate scorecard → compute UHQS). No honeypot required.
Published honeypot pages under docs/conformance are reproduce-a-grade recipes, not that guide.
# 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.jsonpip 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-targetpip 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.mdDraft AEP trial JSONL with a deterministic mock or a loopback-only local model.
Install does not enable it — edit aep-slm.yaml first. Does not change UHQS.
Guide: SLM evaluator (alpha).
pip install 'uhbs[aep-slm]'
uhbs aep slm init --out aep-slm.yaml
uhbs aep slm status aep-slm.yaml # shows LOCKED until you edit the file
# Edit aep-slm.yaml: enabled + unlock phrase + attestations (see docs)
# uhbs aep slm generate aep-slm.yamlpip install 'uhbs[mcp]'
# Configure the host — see docs/tooling/mcp.md
# uhbs-mcp or: python -m uhbs_mcpRegistry 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 build -t uhbs:5.0.1 .
docker run --rm -v "$PWD:/work" -w /work uhbs:5.0.1 \
validate-scorecard ./docs/conformance/fixtures/cowrie-low-interaction.scorecard.json
docker run --rm -v "$PWD:/work" -w /work uhbs:5.0.1 lab --list-protocolsCompose: docker compose run --rm uhbs validate-profile ./my-honeypot.profile.yaml.
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).
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) ]
| Symbol | Meaning |
|---|---|
| (S_A \ldots S_F) | Module scores 0–100 |
| (w_A \ldots w_F) | Profile-adaptive weights (sum to 1.00) |
| (\delta_C) | Safety Gate from Module D: (1.0) if (C \ge 95), else ((C/100)^2) |
| Module | Focus |
|---|---|
| A | Protocol & syntax fidelity |
| B | Behavioral & stateful realism |
| C | Telemetry quality & pipeline resilience |
| D | Safety, containment & boundary controls (Safety Gate) |
| E | Scalability, latency & stress |
| F | White-box static code audit |
A decoy with strong deception scores can still fail lab evaluation if Module D is weak. Normative math: uhqs_math.py · scoring formula.
Profile & config → Static audit (F) → Sandbox provision → Dynamic A–E → Score & report
UHQS remains the normative lab grade. AEP is an optional, informative layer for controlled lab decoy-vs-reference experiments. AEP does not change UHQS.
| When | Use |
|---|---|
| Lab release / conformance | UHBS scorecard alone |
| Comparative lab study | Add AEP (VoD, FSV, DTDR, EER + uncertainty) |
- 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.
| Doc | URL |
|---|---|
| Overview | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/ |
| Beginner tutorial | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/tutorial-beginner/ |
| CLI | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/cli/ |
| SLM evaluator (alpha, opt-in) | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/slm-alpha/ |
| Related frameworks | https://uhbs.github.io/uhbs-standard/mkdocs/mappings/related-frameworks/ |
| Resource | Link |
|---|---|
| Landing hub | https://uhbs.github.io/uhbs-standard/ |
| Specification | https://uhbs.github.io/uhbs-standard/mkdocs/specification/core-principles/ |
| Sitemap index (SEO) | https://uhbs.github.io/uhbs-standard/sitemap.xml |
| CLI guide | docs/tooling/cli.md |
| MCP (AI hosts) | docs/tooling/mcp.md |
| AEP SLM (alpha) | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/slm-alpha/ |
| Reference harness | docs/reference-implementation.md |
| Conformance & lab reports | docs/conformance/index.md |
| Framework mappings | docs/mappings/index.md |
| Maturity roadmap | ROADMAP.md |
| Agent / SEO / AEO index | llms.txt · AGENTS.md · humans.txt |
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
After you publish a scorecard (conformance / your own report), you can badge it:
Contributions are welcome under the project’s governance constraints.
- Read CONTRIBUTING.md and CODE_OF_CONDUCT.md
- Follow GOVERNANCE.md — specification changes use an RFC process
- Sign off commits (DCO)
- Run
pytest -qandruff checkon touched Python before opening a PR
Please report vulnerabilities via GitHub Security Advisories per SECURITY.md. Do not use UHBS tooling against systems you are not authorized to test.
@software{uhbs2026,
author = {Zavdi, Moran},
title = {Universal Honeypot Benchmarking Standard (UHBS)},
year = {2026},
version = {5.0.1},
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.
Licensed under the Apache License 2.0.