NebulaShell

Python License Build Security

插件化运行时框架 · 多重签名加密分发 · NIR 一次编译到处运行 · 企业级安全体系


--- ## 目录 - [项目定位](#项目定位) - [快速开始](#快速开始) - [CLI 工具链](#cli-工具链) - [插件开发](#插件开发) - [权限白名单](#权限白名单manifestpermissionsimports) - [NBPF 包格式](#nbpf-包格式) - [内置插件](#内置插件) - [安全体系](#安全体系) - [贡献指南](#贡献指南) - [许可证](#许可证) --- ## 项目定位 NebulaShell 是一个**以安全为基石、以插件为灵魂**的运行时框架。核心只做两件事：**加载插件**与**调度插件**，其余一切功能均由插件生态提供。 ### 设计原则 | 原则 | 说明 | |:----|:-----| | 🧩 **一切皆插件** | 框架本身只提供加载和调度能力，所有功能都来自插件 | | 🔒 **安全默认** | 沙箱执行、签名验证、权限声明、完整性校验，层层防护 | | 📦 **一次编译到处运行** | NIR 中间表示使插件可在任何 Python 3.10+ 平台运行 | | 🎯 **最小权限** | 插件必须显式声明所需权限，未授权操作被拒绝 | | 🔧 **开发者体验** | 脚手架生成、热重载、详细日志，让开发尽可能愉快 | --- ## 快速开始 ### 一键启动（推荐） ```bash # 非交互式启动（适合 Docker / CI / 后台服务） python headless.py # 自动信任所有 NBPF 插件 python headless.py --trust-all # 仅检查运行环境 python headless.py --dry-run ``` ### 手动启动 ```bash # 安装依赖 pip install -r requirements.txt # 开发模式（热重载，推荐开发时使用） python main.py dev # 生产模式（交互式 REPL） python main.py serve # 生产模式（非交互，适合 Docker） python main.py serve --headless ``` ### 快速创建第一个模组 ```bash # 一行命令创建模组脚手架 python main.py create mod hello-world -a "我" -d "我的第一个模组" # 编辑功能 cd hello-world # vim main.py # 实现你的功能 # 生成签名密钥 python main.py create key -o ./keys --name mykey # 打包为 .nbpf python main.py nbpf pack ./hello-world -o mods/hello-world.nbpf \ --ed25519-key ./keys/mykey_ed25519.pem \ --rsa-key ./keys/mykey_rsa.pem \ --rsa-pub ./keys/mykey_rsa.pub.pem \ --signer "我" # 启动开发模式测试 python main.py dev ``` > 默认 HTTP 服务端口：**10086**（可在 `data/config.json` 或环境变量 `HTTP_API_PORT` 中修改） --- ## CLI 工具链 | 命令 | 说明 | |:----|:------| | `serve` | 启动 NebulaShell 服务端 | | `serve --headless` | 🆕 非交互模式（不启动 REPL，适合 Docker/后台） | | `dev` | 🆕 **开发模式** — 监听文件变化 + 自动热重载 | | `version` | 显示版本信息 | | `info` | 显示系统信息 | | `create mod` | 🆕 **模组脚手架** — 交互式生成插件骨架 | | `create key` | 🆕 快速生成 Ed25519 + RSA 签名密钥对 | | `create list-templates` | 🆕 查看可用模板 | | `nbpf pack` | 打包插件目录为 .nbpf 文件 | | `nbpf unpack` | 解包 .nbpf 文件到目录 | | `nbpf verify` | 验证 .nbpf 签名 | | `nbpf sign` | 为 .nbpf 重新签名 | | `nbpf keygen` | 生成 Ed25519 + RSA-4096 密钥对 | ### 典型用法 ```bash # 🚀 快速创建模组（脚手架） nebula create mod my-plugin -a "我" -d "插件描述" nebula create mod my-service --type service --with-keys # 🔑 生成签名密钥 nebula create key -o ./keys --name mykey # 💻 开发模式（热重载） nebula dev # 监听当前目录 nebula dev ./my-plugin --port 10086 # 监听指定目录 nebula dev --skip-sign # 跳过签名验证（调试用） # 🚀 启动服务 nebula serve nebula serve --headless # 非交互模式 # 📦 打包插件 nebula nbpf pack ./my-plugin -o my-plugin.nbpf \ --ed25519-key ./keys/ed25519.pem \ --rsa-key ./keys/rsa.pem \ --rsa-pub ./keys/rsa.pub.pem \ --signer "作者名" # ℹ️ 系统信息 nebula info ``` --- ## 插件开发 ### 模组结构（目录模式） ``` my-plugin/ ├── manifest.json ← 【必填】模组身份证 ├── main.py ← 【必填】模组代码（类 + New() 工厂函数） └── README.md ← 【推荐】说明文档 ``` ### main.py 规范 插件支持两种写法，**推荐使用类 + New() 工厂函数**以兼容目录和 nbpf 两种加载方式： ```python class MyPlugin: name = "my-plugin" version = "1.0.0" description = "描述" def init(self, deps=None): # 初始化，可获取依赖 pass def start(self): # 启动 pass def stop(self): # 停止，释放资源 pass def reload(self, config): # 热重载（可选） pass def health(self) -> dict: # 健康检查（可选） return {"status": "ok"} def New(): """目录插件工厂函数（必需）""" return MyPlugin() ``` ### manifest.json ```json { "name": "@作者/模组名", "version": "1.0.0", "description": "描述", "author": "作者", "type": "example", "main": "main.py", "enabled": true, "priority": 999, "runtime": { "language": "python", "entry_point": "main.py", "requirements": [] }, "permissions": { "imports": [] ← 声明的系统模块导入权限 }, "services": { "provides": [], "consumes": [] }, "config": {} } ``` ### 开发流程 ```bash # 1. 使用脚手架创建模组（推荐） nebula create mod my-plugin -a "我" -d "描述" # 2. 编辑 main.py 实现功能 cd my-plugin # vim main.py ... # 3. 开发模式：边改边测，自动热重载 nebula dev ./my-plugin # 4. 满意后生成签名密钥 nebula create key -o ./keys --name mykey # 5. 打包为 .nbpf 发布 nebula nbpf pack ./my-plugin -o mods/my-plugin.nbpf \\ --ed25519-key ./keys/mykey_ed25519.pem \\ --rsa-key ./keys/mykey_rsa.pem \\ --rsa-pub ./keys/mykey_rsa.pub.pem \\ --signer "我" ``` --- ## 权限白名单（manifest.permissions.imports） NBPF 安全沙箱默认禁止导入 `os`、`threading`、`socket` 等系统模块。 如果插件确实需要，**必须在 manifest.json 的 `permissions.imports` 中显式声明**。 ```json { "permissions": { "imports": ["os", "threading", "json", "http"] } } ``` | 声明方式 | 效果 | |:---------|:-----| | 不声明 `permissions` | 仅限纯 Python 计算，不可导入任何系统模块 | | `"imports": ["os", "json"]` | 只允许导入 `os` 和 `json` | | 使用未声明的模块 | **编译时报错**，拒绝打包 | | 运行时突破白名单 | **安全沙箱拦截**，抛出 `ImportError` | > **安全原则**：最小权限。只声明你真正需要的模块，不要图省事全写上。 --- ## NBPF 包格式 `.nbpf` 是 NebulaShell 的插件分发格式，本质上是一个多层加密签名的 ZIP 包。 ### 包结构 ``` my-plugin.nbpf ├── META-INF/ │ ├── SIGNATURE ← 外层 Ed25519 签名 │ ├── SIGNER.PEM ← 签名者 Ed25519 公钥 │ ├── ENCRYPTION ← 外层加密信息（RSA 加密 AES 密钥） │ ├── INNER_SIGNATURE ← 中层 RSA-4096 签名 │ ├── INNER_ENCRYPTION ← 中层加密信息 │ ├── MODULE_SIGS ← 内层 HMAC 模块签名 │ └── PLUGIN.MF ← 插件清单 ├── NIR/ ← 编译后的 NIR 中间表示 │ └── main ← 主模块序列化 code object └── RES/ ← 资源文件（README、图片等） ``` ### 安全层级 ``` 外层: Ed25519 签名 → 验证包完整性 & 作者身份 ↓ 中层: RSA-4096 签名 → 验证 NIR 数据完整性 ↓ 内层: HMAC 签名 → 验证每个模块未被篡改 ↓ 执行: 安全沙箱 + 权限白名单 → 限制运行时能力 ``` --- ## 内置插件 NebulaShell 内置了以下官方插件（位于 `store/NebulaShell/`）： | 插件 | 说明 | |:----|:------| | `plugin-bridge` | 事件总线 + 服务注册 + 跨插件 RPC | | `plugin-storage` | 插件持久化 KV 存储 | | `ws-api` | WebSocket 实时推送 | | `i18n` | 国际化多语言支持 | | `nodejs-adapter` | Node.js 运行时适配 | | `system-monitor` 🆕 | **系统监控仪表盘** — CPU/内存/磁盘/网络/进程TOP | | | 提供 HTML 仪表盘 + REST API，默认端口 **10087** | ### system-monitor API ``` http://localhost:10087/ → 📊 仪表盘 HTML http://localhost:10087/health → 💚 {"status": "ok"} http://localhost:10087/stats → 📄 系统状态 JSON http://localhost:10087/stats/cpu → 🧠 CPU 详情 http://localhost:10087/stats/memory → 💾 内存详情 http://localhost:10087/stats/disk → 💿 磁盘详情 http://localhost:10087/stats/network → 🌐 网络详情 http://localhost:10087/stats/processes → ⚡ TOP 进程 http://localhost:10087/stats/history → 📈 历史数据（最近60条） ``` --- ## 安全体系 | 层级 | 措施 | 说明 | |:----|:-----|:------| | 🛡 **分发安全** | 三层签名（Ed25519 + RSA-4096 + HMAC） | 防止包被篡改或伪造 | | 🔐 **传输安全** | AES-256-GCM 双层加密 | 插件代码在传输和存储中均加密 | | 🏖 **执行沙箱** | NIR 安全沙箱 | 限制危险模块和内置函数 | | 📋 **权限控制** | manifest 权限白名单 | 插件必须声明所需模块导入权限 | | 🔍 **完整性检查** | SHA-256 文件 hash 监控 | 运行时定期校验插件文件完整性 | | 🧠 **内存防护** | MemoryGuard 冻结核心属性 | 防止插件修改框架内部状态 | | 📝 **行为审计** | AuditLogger | 记录所有插件操作行为 | | 👀 **防篡改监控** | TamperMonitor 后台线程 | 自动检测篡改并停止被篡改插件 | | 🔄 **降级恢复** | FallbackManager 自动重试 | 插件崩溃时自动重启（最多3次） | --- ## 贡献指南 ### 开发环境 ```bash # 克隆仓库 git clone https://git.starlight-apk.cn/starlight-apk/NebulaShell.git cd NebulaShell # 安装依赖 pip install -r requirements.txt # 启动开发模式 python main.py dev # 运行测试 python -m pytest tests/ ``` ### 贡献流程 1. Fork 项目并创建特性分支 2. 编写代码，确保语法检查零错误 3. 添加或更新测试 4. 更新文档（README、注释等） 5. 提交 Pull Request ### 代码规范 - 遵循 PEP 8 编码规范 - 插件必须实现 `init()`、`start()`、`stop()` 方法 - 插件必须包含 `New()` 工厂函数（兼容目录 + nbpf 两种加载方式） - 插件必须声明完整的 `permissions.imports` 权限白名单 - 提交前确保所有测试通过 --- ## 许可证 Copyright 2026 Falck, yongwanxing, NebulaShell Contributors Licensed under the [Apache License, Version 2.0](LICENSE).