yunxiao.zhu
070d2ba5c0
- 新增 Obfuscar 混淆发布脚本、发布测试与产物隐私检查 - 调整 VS Code 发布任务和宿主发布配置，统一走混淆流程 - 为 debug 页面内嵌静态接口说明，并补充对应集成测试 - 更新 README 与设计计划文档，记录跨平台发布约束
2.8 KiB
2.8 KiB
Flyshot 跨平台混淆发布设计
目标
为全部 Flyshot.* 自研程序集增加统一的 Obfuscar 混淆发布流程，生成一份 Windows 与 Linux 共用的 .NET 8 框架依赖部署包。混淆流程必须显式失败，不能在工具缺失或混淆失败时留下看似成功的未保护发布包。
工具与环境边界
- 使用环境中安装的 Obfuscar 全局工具，命令名为
obfuscar.console。 - 仓库不增加 Obfuscar NuGet
PackageReference，也不增加.config/dotnet-tools.json。 - 构建环境需预先执行
dotnet tool install --global Obfuscar.GlobalTool --version 2.2.50。 - 发布脚本只依赖 PowerShell 7、.NET 8 SDK 和环境中的 Obfuscar。
发布结构
发布脚本不接受运行平台或 RID，固定执行一次框架依赖发布：
- 使用
dotnet publish生成自包含、多文件的原始发布目录。 - 动态生成包含绝对路径的 Obfuscar XML 配置。
- 校验当前八个核心程序集不可缺失，并将发布目录中的全部
Flyshot.*.dll加入混淆模块列表。 - Obfuscar 输出到独立临时目录。
- 仅在混淆成功且输出程序集完整时，用混淆程序集替换原始发布目录中的对应文件。
- 将映射文件移入不随部署包交付的
outputs/obfuscation-maps/<rid>/。 - 最终部署包输出到
outputs/obfuscated/framework-dependent/。
混淆边界
KeepPublicApi=true：保留公共 API 名称，保护 ASP.NET Core 控制器发现、配置绑定、DI、JSON DTO、Swagger 和程序集间调用。HidePrivateApi=true：重命名内部类型、私有方法和字段。RenameProperties=false、RenameEvents=false：避免配置绑定、JSON 序列化和框架约定受属性或事件重命名影响。- 不处理
Microsoft.*、System.*、NLog、Swashbuckle 等第三方程序集。 - 所有
Flyshot.*.dll必须被发现并加入配置；缺少任何当前核心程序集都视为发布失败，未来新增模块会自动纳入。
验证
- 脚本契约测试验证：RID 列表、环境工具缺失失败、全部自研程序集进入配置、第三方程序集不进入配置、映射文件不进入部署目录。
- 执行现有解决方案测试与 Release 构建。
- 真实执行框架依赖发布及混淆，并分别在 Windows 与 Linux 的 .NET 8 运行时上启动。
- Windows 包实际启动并请求
/healthz。 - Linux 包至少验证 ELF 启动文件、依赖文件和全部混淆程序集完整；环境存在 WSL 时再实际启动并请求
/healthz。
风险与限制
Obfuscar 能显著提高普通反编译的阅读成本，但不能绝对阻止有经验的逆向分析。保留公共 API 是当前 ASP.NET Core 稳定运行所需的安全边界；若未来需要更强的控制流混淆、字符串加密或防篡改，应评估商业混淆器。