PeachPDF 安全实践:如何安全地渲染不可信 HTML(关闭本地文件访问)
PeachPDF 安全实践:如何安全地渲染不可信 HTML(关闭本地文件访问)
如果你要用 PeachPDF 这个纯 .NET 的 HTML 转 PDF 渲染库来处理不可信来源的 HTML(用户提交、爬虫抓取、第三方模板),必须牢记一件事:PeachPDF 默认允许文档读取服务器上的本地文件。这一篇给你一套完整的 PeachPDF 安全配置指南:通过关闭本地文件访问,把渲染器变成一个"只读输入"的安全沙箱,防止不可信文档偷读磁盘上的图片、CSS 和字体。
⚠️ 为什么不可信 HTML 是风险?
PeachPDF 的默认行为对"渲染自己的模板"非常友好,但处理外部内容时恰恰是危险的:
- 文档中的
file:资源引用(图片、样式表、字体)会直接从磁盘读取; - 相对路径引用(如
<img src="logo.png">)会回退到进程当前工作目录解析; - 也就是说,一段恶意 HTML 只要写对路径,就可能把服务器上的文件"借道" PDF 渲染读取出来,甚至把敏感内容编码进输出。
核心关键词速记:PeachPDF 安全、渲染不可信 HTML、关闭本地文件访问、AllowLocalFileAccess。
🔧 一键配置:AllowLocalFileAccess = false
PeachPDF 把"文档能否触达本地文件系统"收敛到了一个开关上:PdfGenerateConfig 的 AllowLocalFileAccess 属性(默认 true,保留历史行为)。
渲染不可信输入时,只需在配置里加一行:
var config = new PdfGenerateConfig
{
PageSize = PageSize.A4,
AllowLocalFileAccess = false // 🛡️ 拒绝一切本地文件访问
};
var pdf = await new PdfGenerator().GeneratePdf(untrustedHtml, config);
这一个开关覆盖了文档申请的所有资源类型,因为它们最终都走同一条解析路径(见 HtmlRenderContext.cs 的强制检查):
| 资源类型 | 关闭后的行为 |
|---|---|
<img src="file:///..."> |
解析为"未找到",不嵌入 |
<link rel="stylesheet"> 的 file: 地址 |
样式表不加载 |
CSS url()(背景图、装饰) |
不读取 |
SVG <image href> |
不读取 |
@font-face src: url() |
字体不嵌入,回退到默认字体 |
| 相对路径引用 | 不再回退到工作目录,保持"未解析" |
data: URI(内联内容) |
✅ 不受影响,正常渲染 |
💡 一个重要的安全设计:即使你显式配置了 FileUriNetworkLoader(专门读本地文件的加载器),拒绝依然生效。两个设置互相矛盾时,PeachPDF 选择"拒绝"这个安全读法——deny 永远赢。
📌 注意边界:根文档仍然会被读取
关闭本地文件访问限制的是"文档自己申请的资源",而不是你的输入本身:
- 你直接传给
GeneratePdf的 HTML 字符串,仍会正常渲染; - 你用
FileUriNetworkLoader显式指定的那个根 HTML 文件,仍会被读取。
这是合理的边界:根文档是调用方主动提供的输入,不是文档"抓"来的。换句话说,你关的是文档伸向磁盘的"手",不是喂给它的"饭"。
⌨️ CLI 用户:一条 --no-local-files 就够了
如果你用 PeachPDF 附带的命令行工具,PeachPDF.Cli 提供了对应的开关(映射关系见 CliRunner.cs):
peachpdf input.html --no-local-files -o output.pdf
该选项对所有输入类型(HTML、MHTML、URL)一致生效:文档内的 file: 引用全部落空,相对引用不再回退工作目录;而你在命令行指定的输入文档本身仍会读取。完整说明见 docs/cli.md。
🧪 参考实现:浏览器 WASM 沙箱怎么配
仓库里有一个很好的"标准答案":Blazor WASM 示例 PdfRenderService.cs 把用户上传的文档完全"关进笼子":
AllowLocalFileAccess = false:文档无法触达本地文件系统(浏览器里根本没有文件系统);- 不配置 HTTP 加载器:文档也无法触达网络;
- 默认只解析
data:URI(见 DataUriNetworkLoader.cs),所有内容只能来自用户上传的文件本身。
也就是说:不配置 NetworkLoader + 关闭本地文件 = 零外部访问的最小沙箱。
✅ 安全配置清单(Checklist)
处理不可信 HTML 时,建议逐项核对:
- ✅
AllowLocalFileAccess = false(或 CLI 加--no-local-files) - ✅ 确认是否真的需要
NetworkLoader——不需要就留空,默认加载器只认data:URI,是最安全的组合 - ✅ 需要网络时,用 HttpClientNetworkLoader 之类的加载器并收紧
HttpClient(白名单域名、超时、代理) - ✅ 资源加载失败是静默降级(图片缺位、字体回退),不会抛异常——检查输出 PDF 时别把它当渲染成功
- ✅ 为不可信输入单独创建
PdfGenerator实例,避免字体注册等状态在文档间泄漏
这套行为的完整验证见集成测试 LocalFileAccessTests.cs——其中每个"拒绝"测试都有对应的"允许"孪生测试,确保开关真正被执行而不是空转。
❓ 常见问题
Q:关闭后相对路径图片还能用吗?
A:不能从磁盘读了。把资源内联成 data: URI(base64),或用带 BaseUri 的自定义加载器从你信任的来源(内存字典、对象存储)提供。
Q:这会影响正常渲染自己的模板吗?
A:默认值是 true,你的现有代码不受任何影响;只有显式设 false 时才收紧。
Q:发现 PeachPDF 的安全漏洞怎么报告? A:走 SECURITY.md 中的邮件渠道,不要公开提交 issue。
小结
PeachPDF 的安全模型很简单:一个开关(AllowLocalFileAccess)+ 一个默认安全的最小加载器(data: URI)。渲染自己的模板时保持默认;一旦输入来源不可信,加上 AllowLocalFileAccess = false 这一行,就把文件系统的攻击面整个关掉了——这正是把 HTML 转 PDF 库用在生产环境、处理外部内容时的第一道防线。