Why does the docutils/Sphinx "include" directive represent a potential security hole?

Question

The source of the claim is in the Docutils documentation, at https://docutils.sourceforge.io/docs/ref/rst/directives.html#include:

Warning

The "include" directive represents a potential security hole. It can be disabled with the "file_insertion_enabled" runtime setting.

What exactly is it that I should be concerned about, and if it's a potential security hole why hasn't it been removed?

Answer 1

"if it's a potential security hole why hasn't it been removed?" Then you can use any programming language to write malware, and why they still exist? You should learn the right attitude to discuss security topics, as often you need to accept some risks and build up fences against them.

To understand the security risks, you need to build up a specific context, such as generating a web site from Sphinx files.

If you choose another context such as generating PDF files, the risks can be different.

First, in .rst files people can write bad JavaScript code in raw directive,

.. raw:: html

 <script>
 function badCode() {
  alert("I am bad code");
 }
 badCode();
 </script>

Second, include directive allows you to include files you might not fully controlled (for example, a file from an external storage, or simply out of your working directory).

So, if you didn't pay enough attention to what you include and someone really hacks the contents included in your Sphinx files, then the final generated sites can contain malicious code and harm the end users who view those pages.

To minimize such risks, clearly

• Sphinx allows you to disable include completely as that documentation page says, but you lose this useful feature.
• You can include only contents that you trust (from the same Git repository for example), because you know a good enough code review can reduce risks from there.
• If you still want to include external contents, set up procedures to actively verify the actual contents before generating the web site.