为何docutils/Sphinx的include指令存在潜在安全漏洞？相关疑问解析

为什么include指令是潜在安全漏洞？ #

include指令的核心作用是在解析reStructuredText文档时，将外部文件的内容插入到当前文档中。如果解析的文档来自不可信来源（比如用户上传的自定义rst文件），攻击者可以利用这个指令突破文件访问限制，引发安全问题。官方文档也明确提示了这一点，并提供了file_insertion_enabled配置用于禁用该功能。

需要关注的具体风险 #

• 敏感文件泄露：攻击者可以构造类似.. include:: /etc/passwd的指令，让解析器读取服务器上的系统敏感文件，泄露账户信息、数据库配置密钥等核心数据。
• 路径遍历攻击：通过多级上级目录的写法（比如.. include:: ../../../../var/log/nginx/access.log），绕过预设的文件目录范围，访问原本无权查看的上级目录文件。
• 恶意内容注入：如果被包含的文件带有恶意的reStructuredText语法，或者结合Sphinx的扩展功能，可能在文档渲染过程中执行未预期的操作，甚至生成包含恶意脚本的输出页面。

既然有安全风险，为何不直接移除该指令？ #

• 不可替代的实用价值：include是reStructuredText生态中用于文档片段复用的核心功能，很多合法场景（比如项目文档的通用说明、跨文档重复内容的统一维护）都依赖它，移除会大幅降低文档编写和维护的效率。
• 灵活的安全控制机制：docutils提供了file_insertion_enabled运行时开关，使用者可以根据场景选择：在不可信环境（比如接受用户上传文档的平台）中禁用，在可信环境（本地文档构建、内部团队文档系统）中启用，平衡安全性和实用性。
• 分层防御的设计思路：官方将其标记为潜在漏洞而非直接移除，是为了给用户自主选择的空间——用户可以通过配置、权限控制等手段规避风险，而非被迫放弃实用功能。

内容的提问来源于stack exchange，提问作者Yerushalmi