突破沙箱限制：Sandboxie插件开发实战指南

你是否曾因Sandboxie默认功能无法满足特定隔离需求而困扰？想为浏览器添加自定义沙箱规则却无从下手？本文将带你从零开始构建实用插件，解锁沙箱功能扩展的完整路径。通过4个实战案例，你将掌握插件架构设计、API调用与打包发布全流程，让沙箱真正为你所用。

插件开发基础认知

Sandboxie提供两种扩展机制：通过AddonManager实现的官方插件系统和基于INI配置的规则扩展。官方插件系统支持复杂功能集成，其核心架构在SandboxiePlus/SandMan/AddonManager.h中定义，主要包含以下组件：

class CAddonManager : public QObject {
    Q_OBJECT
public:
    SB_PROGRESS InstallAddon(const QString& Id);      // 安装插件
    SB_PROGRESS RemoveAddon(const QString& Id);       // 卸载插件
    QList<CAddonInfoPtr> GetAddons();                 // 获取插件列表
    // ...
private:
    QList<CAddonPtr> m_Installed;                     // 已安装插件
    QList<CAddonPtr> m_KnownAddons;                   // 已知插件库
};

插件元数据采用JSON格式存储，包含ID、版本、依赖等信息。系统通过UpdateAddons()方法从配置服务器同步插件列表，具体实现见SandboxiePlus/SandMan/AddonManager.cpp。

开发环境搭建

必要工具准备

开发Sandboxie插件需以下工具链：

• Visual Studio 2022（支持C++17及Qt）
• Qt 6.2+ SDK（与Sandboxie Plus版本匹配）
• Windows SDK 10.0.19041.0+
• 7-Zip（用于打包插件）

项目配置要点

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/sa/Sandboxie.git

2. 配置Qt环境：

cd Sandboxie/SandboxiePlus
install_qt.cmd 6.5.2

3. 验证开发环境： 打开Sandboxie/Sandbox.sln解决方案，确认SandMan项目能成功编译，其插件管理模块依赖QSbieAPI提供的核心接口。

插件架构设计规范

目录结构标准

遵循官方插件布局可确保兼容性，推荐结构如下：

MyPlugin/
├── manifest.json      # 插件元数据
├── bin/               # 可执行文件
│   ├── x64/
│   └── x86/
├── rules/             # 沙箱规则文件
└── icons/             # 图标资源

元数据格式详解

manifest.json是插件的身份证，需包含以下关键字段：

{
  "id": "custom-browser-sandbox",
  "version": "1.0.0",
  "name": "自定义浏览器沙箱",
  "description_zh_CN": "为Chromium内核浏览器添加增强隔离规则",
  "author": "Your Name",
  "compatibility": {
    "minVersion": "1.7.5",
    "maxVersion": "*"
  },
  "files-x64": [
    { "src": "bin/x64/sbie_ext.dll", "dest": "addons/custom-browser/" }
  ],
  "rules": [ "rules/chrome-isolation.ini" ]
}

其中多语言支持通过description_<lang>字段实现，如description_en对应英文描述，具体本地化逻辑见CAddonInfo::GetLocalizedEntry方法。

核心API实战应用

插件安装流程解析

当用户点击安装时，AddonManager会触发以下流程（源码位于AddonManager.cpp#L181）：

1. 验证插件ID与版本兼容性
2. 下载并解压插件包至%ProgramFiles%\Sandboxie-Plus\addons\
3. 执行install.bat（若存在）
4. 加载规则文件到沙箱配置

关键代码片段：

SB_PROGRESS CAddonManager::InstallAddon(const QString& Id) {
    CAddonPtr pAddon = GetAddon(Id, eNotINstalled);
    // ... 参数构造与异步安装逻辑 ...
    QtConcurrent::run(RunUpdaterAsync, pAddon, Params);
    return SB_PROGRESS(OP_ASYNC, pAddon->pProgress);
}

规则注入技术

通过插件可动态修改沙箱规则，推荐使用SbieIni接口实现：

#include "../common/ini.h"  // 来自[Sandboxie/common/ini.h](https://gitcode.com/gh_mirrors/sa/Sandboxie/blob/fce71dcedf46d68dbea9587deba2a3c1aca696ef/Sandboxie/common/ini.h?utm_source=gitcode_repo_files)

void InjectCustomRules(const QString& boxName) {
    CIniFile ini(theAPI->GetConfigPath());
    ini.SetValue(boxName, "ClosedIpcPath", "!SystemRoot\\system32\\winsock.dll");
    ini.SetValue(boxName, "OpenPipePath", "\\\\.\\pipe\\mypipe*");
    ini.Save();
}

此代码会添加IPC路径限制，阻止沙箱内程序访问特定系统DLL。规则生效需调用theAPI->ReloadConfig()刷新配置。

实战案例：浏览器增强插件

功能设计目标

实现一个为Microsoft Edge提供增强隔离的插件，包含：

• 自动为Edge创建独立沙箱
• 阻止剪贴板数据泄露
• 限制对下载文件夹的写入权限

关键实现步骤

1. 创建规则模板
   在插件目录下创建rules/edge.ini：

   [EdgeSecureBox]
   Enabled=y
   ConfigLevel=9
   BlockNetworkFiles=y
   ClipboardAccess=n
   ClosedFilePath=!<Downloads>
   

2. 编写安装脚本
   创建install.bat实现沙箱自动创建：

   @echo off
   "C:\Program Files\Sandboxie-Plus\SandMan.exe" /createbox=EdgeSecureBox /template=WebBrowser
   

3. 实现配置界面
   使用Qt创建设置对话框，通过QSbieAPI获取沙箱状态：

   QList<CSandBoxPtr> boxes = theAPI->GetBoxes();
   foreach(CSandBoxPtr box, boxes) {
       if (box->GetName() == "EdgeSecureBox") {
           ui->chkClipboard->setChecked(box->GetConfig("ClipboardAccess") == "n");
       }
   }
   

插件打包与测试

1. 执行打包命令：

7z a -tzip plugin.zip manifest.json rules/ bin/ icons/ install.bat

2. 本地安装测试：

// 调用插件安装API
CAddonManager* pManager = theGUI->m_pAddonManager;
pManager->InstallAddon("plugin.zip");

3. 验证安装结果： 打开Sandboxie控制中心，在插件列表中应能看到已安装的"自定义浏览器沙箱"，且Edge程序启动时会自动使用新创建的隔离环境。

高级功能：系统调用过滤

技术原理概述

通过HookNtCreateFile等系统调用，可实现细粒度文件访问控制。Sandboxie内核驱动在Sandboxie/core/drv/file.c中提供了过滤机制，插件可通过注册回调函数扩展此功能：

// 伪代码演示系统调用过滤注册
typedef NTSTATUS (*SyscallFilter)(PVOID Context, PVOID SyscallArgs);

void RegisterSyscallFilter(SyscallFilter filter, PVOID Context) {
    HANDLE hDriver = CreateFile(L"\\\\.\\SbieDrv", GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL);
    // IOCTL调用注册过滤器...
    CloseHandle(hDriver);
}

实战应用场景

实现禁止沙箱内程序访问USB设备的插件，核心过滤函数：

NTSTATUS UsbFilter(PVOID Context, PVOID SyscallArgs) {
    PIO_STATUS_BLOCK IoStatus = ...;
    PUNICODE_STRING FileName = ...;
    
    if (wcsstr(FileName->Buffer, L"\\\\.\\usb#") != NULL) {
        *IoStatus->Status = STATUS_ACCESS_DENIED;
        return STATUS_ACCESS_DENIED;
    }
    return STATUS_SUCCESS;
}

此功能需插件拥有内核模式权限，开发时需启用Sandboxie/core/drv目录下的驱动项目支持。

插件发布与维护

官方商店提交

开发完成的插件可提交至Sandboxie官方仓库，需遵循CONTRIBUTING.md中的贡献指南，主要步骤：

1. Fork主仓库并创建插件分支
2. 将插件源码放在contrib/addons/目录
3. 提交PR并通过自动化测试

版本更新机制

插件元数据中的version字段采用语义化版本控制，当更新插件时：

1. 递增版本号（如1.0.0 → 1.1.0）
2. 更新CHANGELOG.md说明变更内容
3. 确保兼容性字段compatibility正确设置

Sandboxie会通过OnlineUpdater定期检查插件更新，用户无需手动干预。

常见问题与调试技巧

开发工具链问题

Q: 编译时提示找不到QSbieAPI.h？
A: 确保SandboxiePlus/QSbieAPI项目已被正确引用，可通过install_qt.cmd脚本修复Qt依赖。

插件调试方法

1. 启用详细日志
   修改全局配置文件Sandboxie.ini：

   [GlobalSettings]
   LogLevel=4
   LogFile=C:\SbieDebug.log
   

2. 附加调试器
   在Visual Studio中使用"附加到进程"功能连接SandMan.exe，设置断点于AddonManager.cpp的关键方法。

3. 查看插件状态
   通过以下API获取已安装插件列表：

   CAddonManager* pManager = theGUI->m_pAddonManager;
   QList<CAddonInfoPtr> addons = pManager->GetAddons();
   foreach(CAddonInfoPtr info, addons) {
       qDebug() << info->Id << info->Installed;
   }
   

总结与扩展方向

通过本文介绍的插件开发框架，你已掌握扩展Sandboxie功能的核心技术。未来可探索更高级的应用场景：

• 基于Snapshot Manager实现沙箱状态快照插件
• 开发文件加密传输工具，集成到沙箱右键菜单
• 构建威胁情报联动系统，自动隔离可疑程序

Sandboxie的开源生态持续发展，欢迎将你的创意插件贡献至官方仓库，共同完善这一强大的隔离工具。

下一步行动：立即克隆项目仓库，尝试修改示例插件的元数据，体验插件开发的完整流程。遇到问题可查阅开发者文档或加入Discord社区获取支持。