uhbs/uhbs-standard

# 通用蜜罐基准测试标准 (UHBS) [](https://github.com/uhbs/uhbs-standard/actions/workflows/ci-validate.yml) [](https://uhbs.github.io/uhbs-standard/) [](https://github.com/uhbs/uhbs-standard/actions/workflows/codeql-analysis.yml) [](https://www.bestpractices.dev/projects/13853) [](https://pypi.org/project/uhbs/) [](https://doi.org/10.5281/zenodo.21631156) [](LICENSE) [](docs/specification/core-principles.md) [](docs/specification/scoring-formula.md) *已迁移至 uhbs 组织以保持更加清晰的结构* **UHBS v4.3.6** 按**类别和协议**衡量欺骗真实性、遏制能力、可扩展性和遥测质量。它**不是**一个行业协会标准或多党治理机构。有关成熟度目标，请参阅 [ROADMAP.md](ROADMAP.md)。 | | | | --- | --- | | **文档** | [着陆页](https://uhbs.github.io/uhbs-standard/) · [MkDocs](https://uhbs.github.io/uhbs-standard/mkdocs/) | | **PyPI** | [`uhbs`](https://pypi.org/project/uhbs/) | | **Python** | ≥ 3.11 | | **许可证** | [Apache-2.0](LICENSE) | ## 目录 - [项目状态](#project-status) - [您将获得什么](#what-you-get) - [安装](#install) - [快速开始](#quickstart) - [演示](#demo) - [评分 (UHQS)](#scoring-uhqs) - [可选的高级证据配置文件 (AEP)](#optional-advanced-evidence-profile-aep) - [文档导航](#documentation-map) - [仓库布局](#repository-layout) - [贡献](#contributing) - [安全](#security) - [引用](#citation) - [许可证](#license) ## 项目状态 **状态：** Beta / 实验性 — [规范状态](docs/specification/status.md) | 主题 | 当前现状 | | --- | --- | | 维护者 | [@mziqudhd92](https://github.com/mziqudhd92) — [MAINTAINERS.md](MAINTAINERS.md) | | 治理 | 单一维护者；尚无指导委员会 — [第 6 阶段路线图](ROADMAP.md#phase-6--community-maturity-aspirational--not-done) | | 评估范围 | **仅限实验室 / 沙盒** | | 建议的内部准入条件 | 在实验室评级之后，组织在部署诱饵之前**可以**使用 **UHQS > 80** + 通过安全关卡 — 这并非标准机构的强制要求 | ## 您将获得什么 | 能力 | 包 / 表面 | | --- | --- | | 规范 + schema (TPS、评分卡、证据) | 仓库 `docs/` · `schemas/` | | 验证配置文件和评分卡；重新计算 UHQS | `pip install uhbs` → `uhbs` | | 实时模块 A–F 实验室测试套件（**36** 个协议） | `pip install 'uhbs[lab]'` → `uhbs lab` / `uhbs-lab` | | AI 宿主 MCP 工具（验证/评分测试夹具；无实时探测） | `pip install 'uhbs[mcp]'` → `uhbs-mcp` | | 离线高级证据配置文件（可选；不改变 UHQS） | `pip install 'uhbs[aep]'` → `uhbs aep` | | AEP SLM 测试用例生成器（alpha 版；**在您修改配置前保持关闭**） | `pip install 'uhbs[aep-slm]'` → `uhbs aep slm` | | 已发布的实验室评级 / 测试夹具 | [docs/conformance/](docs/conformance/index.md) | **供应商中立性：** 规范文档使用类别和协议。具体产品仅在一致性测试部分作为评估**证明**出现，而非 UHBS 的要求。 | 支柱 | 详情 | | --- | --- | | 协议无关 | IT、OT/ICS、AI 和云诱饵类别 | | 定量化 | UHQS 0–100，带有来自模块 D 的安全关卡 \(\delta_C\) | | 双平面 | 静态审计 (F) + 动态模块 A–E | | 可选 AEP | 实验室诱饵与参考实验对比证据 (VoD, FSV, DTDR, EER) | ## 安装 ``` python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Core CLI (验证 / 评分) pip install uhbs # 通用 lab 安装 pip install 'uhbs[lab]' # 可选附加项 (仅安装所需内容) 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) ``` | 扩展包 | 用途 | | --- | --- | | *(无)* | 验证器 + UHQS 计算 | | `lab` | 受控的实时模块 A–F 测试套件 | | `mcp` | 本地 AI 宿主评分卡工具 (stdio MCP) | | `aep` | 离线高级证据分析 | | `aep-slm` | Alpha AEP SLM 测试用例生成器（**在您修改 `aep-slm.yaml` 前处于禁用状态**） | | `scapy` | 可选的协议编码后端 | | `dev` | pytest, ruff, mypy（面向贡献者包含 lab/mcp） | | `all` | `lab` + `mcp` + `scapy` | 开发版本检出： ``` git clone https://github.com/uhbs/uhbs-standard.git cd uhbs-standard pip install -e ".[lab,dev]" # 可选: pip install -e ".[aep,mcp]" pytest -q ``` ## 快速开始 ### 1. 验证配置文件或评分卡 ``` # 从 git checkout 安装 (模板随 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. 运行实验室测试套件（仅限隔离诱饵） ``` pip install 'uhbs[lab]' uhbs lab --list-protocols # 示例 shape — 仅指向你控制的 lab decoy: # uhbs lab --tps low_interaction --protocol ssh \ # --target 127.0.0.1 --port 2222 --out ./.local/bench-reports/my-target ``` ### 3. 可选 AEP（离线实验室证据） ``` 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 ``` ### 3b. 可选 AEP SLM alpha 版（默认关闭） 使用确定性的模拟程序或仅限本地回环的本地模型草拟 AEP 测试 JSONL。 **安装并不会启用它** —— 请先修改 `aep-slm.yaml`。这不会改变 UHQS。 指南：[SLM 评估器（alpha 版）](https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/slm-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 # 编辑 aep-slm.yaml: enabled + unlock phrase + attestations (参见文档) # uhbs aep slm generate aep-slm.yaml ``` ### 面向 AI 宿主的 MCP（Cursor, Claude, VS Code, …） ``` pip install 'uhbs[mcp]' # 配置主机 — 参见 docs/tooling/mcp.md # uhbs-mcp 或者: python -m uhbs_mcp ``` 注册表元数据：[`server.json`](server.json)。实时实验室探测保留在 `uhbs lab` 上，而不是 AI 宿主的 MCP 服务器上。 使用树内的 `mcp` **协议插件**（`uhbs[lab]`）对 **MCP 蜜罐**表面（基于 HTTP/SSE 的 JSON-RPC）进行评级 —— 这与上面的 AI 宿主服务器不同。请参阅 [MCP 蜜罐评级](docs/architecture/mcp-honeypot-grading.md)。 ### Docker ``` docker build -t uhbs:4.3.6 . docker run --rm -v "$PWD:/work" -w /work uhbs:4.3.6 \ validate-scorecard ./docs/conformance/fixtures/cowrie-low-interaction.scorecard.json docker run --rm -v "$PWD:/work" -w /work uhbs:4.3.6 lab --list-protocols ``` Compose：`docker compose run --rm uhbs validate-profile ./my-honeypot.profile.yaml`. ## 演示 终端演练：安装 UHBS + Cowrie/Conpot，启动实验室诱饵，完整的 UHQS (Cowrie SSH · Conpot Modbus · HellPot HTTP)。  回放：[`docs/assets/uhbs-lab-demo.cast`](docs/assets/uhbs-lab-demo.cast) (`asciinema play docs/assets/uhbs-lab-demo.cast`). ## 评分 (UHQS) **通用蜜罐质量评分**是一个标准化的综合分，范围为 **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) \] | 符号 | 含义 | | --- | --- | | \(S_A \ldots S_F\) | 模块得分 0–100 | | \(w_A \ldots w_F\) | 配置文件自适应权重（总和为 1.00） | | \(\delta_C\) | 来自模块 D 的安全关卡：若 \(C \ge 95\) 则为 \(1.0\)，否则为 \((C/100)^2\) | | 模块 | 重点 | | --- | --- | | **A** | 协议与语法保真度 | | **B** | 行为与状态真实性 | | **C** | 遥测质量与流水线韧性 | | **D** | 安全、遏制与边界控制（**安全关卡**） | | **E** | 可扩展性、延迟与压力测试 | | **F** | 白盒静态代码审计 | 如果模块 D 较弱，即使诱饵的欺骗性得分很高，也可能无法通过实验室评估。规范性数学定义：[`uhqs_math.py`](src/uhbs_core/uhqs_math.py) · [评分公式](docs/specification/scoring-formula.md)。 ### 实验室审计工作流（5 个阶段） ``` Profile & config → Static audit (F) → Sandbox provision → Dynamic A–E → Score & report ``` ## 可选的高级证据配置文件 (AEP) UHQS 仍然是规范性的实验室评级。**AEP** 是一个可选的、信息化的层，用于受控的**实验室**诱饵与参考对比实验。**AEP 不会改变 UHQS。** | 何时使用 | 用途 | | --- | --- | | 实验室发布 / 一致性 | 仅使用 UHBS 评分卡 | | 比较性实验室研究 | 添加 AEP（`VoD`, `FSV`, `DTDR`, `EER` + 不确定性） | - 仅对本地实验/测试文件进行离线分析 —— 不发起攻击 - 状态词汇：`valid | inconclusive | control_failed`（不是字母等级） - 打包的示例：`uhbs aep example beginner|advanced|template` **学术致谢**（引用 ≠ 认可）：Zhu (2019), Collins et al. (2024), Ersok et al. (2022), Li et al. (2020) — 完整记录： [研究基础与致谢](https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/research-foundations/)。 | 文档 | URL | | --- | --- | | 概述 | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/ | | 初学者教程 | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/tutorial-beginner/ | | CLI | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/cli/ | | SLM 评估器（alpha 版，选择性启用） | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/slm-alpha/ | | 着陆页中心（AEP 部分） | https://uhbs.github.io/uhbs-standard/#advanced-evidence | | 相关框架 | https://uhbs.github.io/uhbs-standard/mkdocs/mappings/related-frameworks/ | ## 文档导航 | 资源 | 链接 | | --- | --- | | 着陆页中心 | https://uhbs.github.io/uhbs-standard/ | | 规范 | https://uhbs.github.io/uhbs-standard/mkdocs/specification/core-principles/ | | 站点地图索引 (SEO) | https://uhbs.github.io/uhbs-standard/sitemap.xml | | CLI 指南 | [docs/tooling/cli.md](docs/tooling/cli.md) | | MCP（AI 宿主） | [docs/tooling/mcp.md](docs/tooling/mcp.md) | | AEP SLM（alpha 版） | https://uhbs.github.io/uhbs-standard/mkdocs/advanced-evidence/slm-alpha/ | | 参考测试套件 | [docs/reference-implementation.md](docs/reference-implementation.md) | | 一致性与实验室报告 | [docs/conformance/index.md](docs/conformance/index.md) | | 框架映射 | [docs/mappings/index.md](docs/mappings/index.md) | | 成熟度路线图 | [ROADMAP.md](ROADMAP.md) | | Agent / SEO / AEO 索引 | [llms.txt](llms.txt) · [AGENTS.md](AGENTS.md) · [humans.txt](docs/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 ``` ## 嵌入已发布的评级 在您发布评分卡（一致性测试 / 您自己的报告）之后，您可以为其添加徽章： ```  ``` ## 安全 请按照 [SECURITY.md](SECURITY.md) 的说明，通过 [GitHub 安全公告](https://github.com/uhbs/uhbs-standard/security/advisories/new) 报告漏洞。请勿将 UHBS 工具用于未经授权测试的系统。 ## 引用 ``` @software{uhbs2026, author = {Zavdi, Moran}, title = {Universal Honeypot Benchmarking Standard (UHBS)}, year = {2026}, version = {4.3.6}, publisher = {Zenodo}, doi = {10.5281/zenodo.21631156}, url = {https://doi.org/10.5281/zenodo.21631156} } ``` 机器可读格式：[`CITATIONff`](CITATION.cff)。概念 DOI（最新存入）： [10.5281/zenodo.21631155](https://doi.org/10.5281/zenodo.21631155)。 ## 许可证 根据 [Apache License 2.0](LICENSE) 授权。

标签：BOF, CSP, Python, 反取证, 安全标准, 安全评估, 实时处理, 密码管理, 无后门, 欺骗防御, 蜜罐, 证书利用, 请求拦截, 逆向工具