Jonnenpijonne/esp32-iot-security-governance-lab
GitHub: Jonnenpijonne/esp32-iot-security-governance-lab
面向ESP32和嵌入式边缘设备的安全治理实验室，提供威胁建模、就绪度评估、变更控制与审计证据的参考基线。
Stars: 0 | Forks: 0
# ESP32 / 嵌入式边缘设备安全治理实验室
**面向 ESP32 和嵌入式边缘设备安全、就绪性验证、网络节点清单、防御性演练关卡、EMB3D 对齐威胁建模证据以及 KATAKRI 风格的公开/私有边界的治理优先实验室。**
本仓库是一个公开的作品集和参考基线。它不是生产级固件产品、客户交付包、机密项目记录、渗透测试工具包、无人机控制项目或通用的 ESP32 教程。
其目标是演示一个小型的嵌入式/边缘设备项目如何在不变成过度设计的企业流程怪物的情况下，保持可理解、可测试、可回滚和证据驱动。
## 作品集 / 作者背景
本仓库是 Jonne Silvennoinen 公开 GitHub 作品集的一部分：
- GitHub 主页：[Jonnenpijonne](https://github.com/Jonnenpijonne)
更广泛的作品集侧重于实用的安全治理、嵌入式/边缘设备保障、文档驱动的 DevSecOps、基于证据的验证以及受控的公开/私有项目边界。
## 从这里开始
| 资源 | 用途 |
| --- | --- |
| `docs/QUICK_LOCAL_VALIDATION.md` | 适用于 Git Bash 的复制粘贴本地验证路径 |
| `docs/GETTING_STARTED.md` | 本地设置与验证命令 |
| `docs/GATEHOUSE_INTEGRATION.md` | 与 Gatehouse 变更治理验证集成的轻量级模型 |
| `docs/PROJECT_INDEX.md` | 项目级路线图 |
| `wiki/Home.md` | 随仓库版本控制的 Wiki 首页 |
| `wiki/Model-Catalog.md` | Python 模型目录 |
| `wiki/Evidence-Pack.md` | 证据示例 |
| `wiki/License-and-Use.md` | 许可证与预期用途摘要 |
| `docs/LICENSE_POLICY.md` | Apache-2.0 许可政策 |
| `NOTICE` | 项目声明与归属上下文 |
## 在临时沙箱中验证
如果您想在不保留永久本地副本的情况下测试此仓库，请使用此方法。
前置条件：
- Git
- Windows 上的 Git Bash，或其他兼容 Bash 的 shell
- Python 3.x
- 用于安装依赖的 Internet 连接
此验证不需要物理 ESP32 开发板。固件构建目标为 `esp32dev`，但本指南不会烧录设备。
在 Git Bash 中复制并运行以下内容：
```
cd /tmp
rm -rf esp32-iot-security-governance-lab
git clone https://github.com/Jonnenpijonne/esp32-iot-security-governance-lab.git
cd esp32-iot-security-governance-lab
bash scripts/validate-docs.sh
python -m pytest \
tests/test_readiness_model.py \
tests/test_network_inventory_model.py \
tests/test_network_point_model.py \
tests/test_change_control_model.py \
tests/test_vectorization_model.py \
tests/test_model_package_gate.py \
tests/test_blue_team_protection_model.py \
tests/test_authorized_exercise_gate.py \
tests/test_interference_observation_model.py \
tests/test_emb3d_mapping_model.py \
tests/test_emb3d_alignment_model.py
python -m pip install --upgrade platformio
python -m platformio --version
python -m platformio run
```
预期结果：
```
Documentation validation: PASSED
Python tests: passed
PlatformIO firmware build: SUCCESS
Build artifacts: firmware.elf, firmware.bin
```
可选清理：
```
cd /tmp
rm -rf esp32-iot-security-governance-lab
```
如需更长的验证指南，请参阅 `docs/QUICK_LOCAL_VALIDATION.md`。
## 本仓库演示的内容
| 领域 | 证据 |
| --- | --- |
| ESP32 固件基线 | `platformio.ini`、`src/main.cpp`、仅限本地的串口输出 |
| 设备身份与配置边界 | `include/lab_config.example.h`、`docs/DEVICE_IDENTITY_AND_CONFIGURATION.md` |
| 传感器数据治理 | 本地合成读数、`docs/SENSOR_DATA_GOVERNANCE.md` |
| 数据留存边界 | 仅保留易失性的最后一次读数、`docs/DATA_RETENTION_BOUNDARY.md` |
| 事件可见性 | 本地串口事件、`include/audit_events.h`、`docs/EVENT_VISIBILITY_MODEL.md` |
| 就绪度评分 | `models/readiness_model.py`、pytest |
| 网络节点清单质量 | `models/network_inventory_model.py`、`docs/NETWORK_POINT_INVENTORY_MODEL.md` |
| 网络节点就绪度审查 | `models/network_point_model.py`、`docs/NETWORK_POINT_READINESS.md` |
| 变更控制与回滚 | `models/change_control_model.py`、回滚文档、测试 |
| 向量化 / 模型包关卡 | `models/vectorization_model.py`、`models/model_package_gate.py` |
| 防御性演练关卡 | `models/authorized_exercise_gate.py`、`docs/DEFENSIVE_EXERCISE_READINESS.md` |
| 蓝队保护评分 | `models/blue_team_protection_model.py`、`docs/BLUE_TEAM_PROTECTION_MODEL.md` |
| 干扰观测 | `models/interference_observation_model.py`、`docs/INTERFERENCE_OBSERVATION_MODEL.md` |
| MITRE EMB3D 对齐层 | `docs/EMB3D_ALIGNMENT.md`、`docs/EMB3D_MAPPING_MODEL.md`、EMB3D 模型/测试 |
| KATAKRI 对齐的公开/私有边界 | `docs/KATAKRI_ALIGNMENT.md`、`docs/PUBLIC_SCOPE.md` |
| CI 验证 | 文档验证、固件构建、Python 模型测试 |
## 核心原则
小型技术系统在涉及物理空间、设备身份、环境数据、网络节点、就绪度决策、防御性验证、证据记录或受监管的运行环境时，仍然需要明确的治理。
该项目有意识地保持基线的安全性：
```
no real customer data
no real site details
no network scanning
no wireless discovery
no credential testing
no exploit logic
no interference generation
no telemetry upload
no persistent sensor storage
no production-readiness claim
no certification claim
```
## 高层架构
```
flowchart LR
A[ESP32 firmware skeleton] --> B[Local synthetic sensor reading]
B --> C[Volatile last-reading retention]
C --> D[Serial status output]
D --> E[Local event visibility]
F[Readiness model] --> G[READY / LIMITED / NOT_READY]
H[Network inventory model] --> I[DOCUMENTED / NEEDS_REVIEW / INCOMPLETE]
J[Network point readiness] --> K[READY / REVIEW / UNUSABLE]
L[Change control model] --> M[PROCEED / REVIEW / STOP]
N[Blue-team protection model] --> O[STRONG / PARTIAL / WEAK]
P[Exercise gate] --> Q[GO / PREPARE / NO_GO]
R[Interference observation] --> S[NORMAL / WATCH / ESCALATE]
T[EMB3D alignment models] --> U[LOW / MEDIUM / HIGH and VALIDATED / EVIDENCED / IDENTIFIED / GAP]
V[Evidence reports] --> W[Audit-ready public examples]
F --> V
H --> V
J --> V
L --> V
N --> V
P --> V
R --> V
T --> V
E --> V
```
## 治理流程
```
flowchart TD
A[Proposed change or exercise] --> B{Scope clear?}
B -- No --> X[STOP: clarify scope]
B -- Yes --> C{Permission / boundary clear?}
C -- No --> X
C -- Yes --> D[Classify change size or exercise type]
D --> E[Assess blast radius]
E --> F{Rollback owner defined?}
F -- No --> Y[REVIEW: define rollback]
F -- Yes --> G{Validation passed?}
G -- No --> Y
G -- Yes --> H{Evidence recorded?}
H -- No --> Y
H -- Yes --> I[Proceed or controlled review]
```
## EMB3D 对齐流程
```
flowchart TD
A[Identify embedded device property] --> B[Ask exposure question]
B --> C[Map mitigation evidence]
C --> D{CI or test validation?}
D -- Yes --> E[VALIDATED]
D -- No --> F[EVIDENCED / IDENTIFIED]
F --> G[Private annex needed for real deployment]
E --> H[Evidence package]
```
本仓库未复制 MITRE EMB3D 数据集。它提供了一个轻量级的公开映射层，可在需要时连接到真实的 EMB3D 参考资料和私有项目附件。
## 公开/私有边界
```
flowchart LR
A[Public repository] --> A1[Synthetic examples]
A --> A2[Reusable templates]
A --> A3[Governance models]
A --> A4[Validation scripts]
A --> A5[Portfolio evidence]
B[Private project annex] --> B1[Real site names]
B --> B2[Real room labels]
B --> B3[Real device inventory]
B --> B4[Real evidence]
B --> B5[Approvals and project records]
B --> B6[Real EMB3D mappings]
A -. never store real project material .-> B
```
## 当前仓库目录结构
```
docs/
QUICK_LOCAL_VALIDATION.md
GETTING_STARTED.md
GATEHOUSE_INTEGRATION.md
PROJECT_INDEX.md
LICENSE_POLICY.md
ARCHITECTURE.md
THREAT_MODEL.md
SECURITY_BASELINE.md
DEVICE_LIFECYCLE.md
OTA_AND_ROLLBACK.md
PRIVACY_AND_TELEMETRY.md
CHANGE_GOVERNANCE.md
EVIDENCE_MODEL.md
PRODUCTIZATION_MODEL.md
ASSURANCE_CASE.md
SUPPLIER_AND_COMPONENT_GOVERNANCE.md
RELEASE_GOVERNANCE.md
OPERATIONS_RUNBOOK.md
PUBLIC_SCOPE.md
KATAKRI_ALIGNMENT.md
FIRMWARE_SECURITY_MODEL.md
DEVICE_IDENTITY_AND_CONFIGURATION.md
SENSOR_DATA_GOVERNANCE.md
DATA_RETENTION_BOUNDARY.md
EVENT_VISIBILITY_MODEL.md
NETWORK_POINT_INVENTORY_MODEL.md
NETWORK_POINT_READINESS.md
DEFENSIVE_EXERCISE_READINESS.md
BLUE_TEAM_PROTECTION_MODEL.md
INTERFERENCE_OBSERVATION_MODEL.md
EMB3D_ALIGNMENT.md
EMB3D_MAPPING_MODEL.md
wiki/
Home.md
Project-Overview.md
Architecture.md
Validation-Guide.md
Security-Boundary.md
EMB3D-Alignment.md
Model-Catalog.md
Evidence-Pack.md
License-and-Use.md
include/
lab_config.example.h
sensor_simulation.h
retention_policy.h
audit_events.h
src/
main.cpp
models/
readiness_model.py
network_inventory_model.py
network_point_model.py
change_control_model.py
vectorization_model.py
model_package_gate.py
blue_team_protection_model.py
authorized_exercise_gate.py
interference_observation_model.py
emb3d_mapping_model.py
emb3d_alignment_model.py
README.md
tests/
test_readiness_model.py
test_network_inventory_model.py
test_network_point_model.py
test_change_control_model.py
test_vectorization_model.py
test_model_package_gate.py
test_blue_team_protection_model.py
test_authorized_exercise_gate.py
test_interference_observation_model.py
test_emb3d_mapping_model.py
test_emb3d_alignment_model.py
examples/
esp32-wifi-sensor-change.md
esp32-ota-update-change.md
esp32-device-identity-change.md
esp32-sensor-simulation-change.md
esp32-data-retention-boundary-change.md
network-point-readiness-review.md
emb3d-property-alignment-review.md
evidence/
EXAMPLE_VALIDATION_REPORT.md
EXAMPLE_FIRMWARE_BASELINE_REPORT.md
EXAMPLE_DEVICE_IDENTITY_REPORT.md
EXAMPLE_SENSOR_SIMULATION_REPORT.md
EXAMPLE_DATA_RETENTION_REPORT.md
EXAMPLE_EMB3D_ALIGNMENT_REPORT.md
.github/workflows/
validation.yml
firmware-build.yml
python-model-tests.yml
```
## 验证命令
运行完整的本地验证集：
```
bash scripts/validate-docs.sh
python models/readiness_model.py
python models/network_inventory_model.py
python models/network_point_model.py
python models/change_control_model.py
python models/vectorization_model.py
python models/model_package_gate.py
python models/blue_team_protection_model.py
python models/authorized_exercise_gate.py
python models/interference_observation_model.py
python models/emb3d_mapping_model.py
python models/emb3d_alignment_model.py
python -m pytest \
tests/test_readiness_model.py \
tests/test_network_inventory_model.py \
tests/test_network_point_model.py \
tests/test_change_control_model.py \
tests/test_vectorization_model.py \
tests/test_model_package_gate.py \
tests/test_blue_team_protection_model.py \
tests/test_authorized_exercise_gate.py \
tests/test_interference_observation_model.py \
tests/test_emb3d_mapping_model.py \
tests/test_emb3d_alignment_model.py
pio run
```
有关可通过复制粘贴执行的 Git Bash 验证路径，请参阅：
```
docs/QUICK_LOCAL_VALIDATION.md
```
预期文档验证结果：
```
ESP32 IoT Security Governance Lab validation: PASSED
```
## 验证证据
最新本地验证结果：
| 检查项 | 结果 |
| --- | --- |
| 文档验证 | 通过 |
| Python 模型测试 | 38 项通过 |
| PlatformIO ESP32 固件构建 | 成功 |
| 目标开发板 | `esp32dev` |
| 构建产物 | `firmware.elf`、`firmware.bin` |
| RAM 占用 | 6.6% |
| Flash 占用 | 20.5% |
| 仓库状态 | clean |
此证据表明该仓库不仅有文档记录，而且还通过文档检查、Python 模型测试和 ESP32 固件构建进行了本地验证。
## CI 工作流
```
flowchart LR
A[Push or Pull Request] --> B[Documentation validation]
A --> C[ESP32 firmware build]
A --> D[Python model tests]
B --> E[Required files present]
C --> F[PlatformIO build passes]
D --> G[Readiness / inventory / protection / EMB3D tests pass]
```
## 实施路线图
| 阶段 | 目标 | 状态 |
| --- | --- | --- |
| 1 | 文档基线 | 已完成 |
| 2 | 固件骨架 | 已完成 |
| 3 | 设备身份/配置边界 | 已完成 |
| 4 | 传感器模拟 | 已完成 |
| 5 | 数据留存边界 | 已完成 |
| 6 | 事件可见性 | 已完成 |
| 7 | 就绪度与清单 Python 模型 | 已完成 |
| 8 | 网络节点就绪度 | 已完成 |
| 9 | 影响范围 / 回滚可重复性 | 已完成 |
| 10 | 向量化 / 模型包关卡 | 已完成 |
| 11 | 防御性演练关卡 | 已完成 |
| 12 | 蓝队保护评分 | 已完成 |
| 13 | 干扰观测 | 已完成 |
| 14 | EMB3D 对齐层 | 已完成 |
| 15 | README 及项目级指南 | 已完成 |
| 16 | Apache-2.0 许可与 NOTICE | 已完成 |
| 17 | 随仓库版本控制的 Wiki | 已完成 |
| 18 | 发布候选检查清单 | 下一步 |
| 19 | 作品集首页摘要 | 下一步 |
## 定位
本仓库可描述为：
简短版本：
作品集版本：
## 本项目不包含的内容
本仓库不是：
- 生产级 ESP32 固件产品
- 客户现场报告
- 机密项目记录
- 自动化网络发现工具
- 无线发现工具
- 渗透测试工具包
- 漏洞利用代码库
- 无人机控制项目
- 医疗决策系统
- 认证声明
## 许可证
Apache License, Version 2.0。
请参阅：
- `LICENSE`
- `NOTICE`
- `docs/LICENSE_POLICY.md`
- `wiki/License-and-Use.md`
标签：ESP32, 威胁建模, 安全治理, 安全规则引擎, 物联网, 边缘计算, 逆向工具