Safe Modes

Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level.

The safe modes in order from most insecure to most secure are:

UNSAFE

A safe mode level that disables any security features enforced by Asciidoctor.

This is the default safe mode for the CLI.

SAFE

This safe mode level prevents access to files which reside outside of the parent directory of the source file. It disables all macros, except the include directive. The paths to include files must be within the parent directory. It allows assets to be embedded in the document.

SERVER

A safe mode level that disallows the document from setting attributes that would affect the rendering of the document. This level trims the attribute docfile to its relative path and prevents the document from:

  • setting source-highlighter, doctype, docinfo and backend

  • seeing docdir

It allows icons and linkcss.

SECURE

A safe mode level that disallows the document from attempting to read files from the file system and including their contents into the document. Additionally, it:

  • disables icons

  • disables the include directive

  • data can not be retrieved from URIs

  • prevents access to stylesheets and JavaScript files

  • sets the backend to html5

  • disables docinfo files

  • disables data-uri

  • disables docdir and docfile

  • disables source highlighting

Asciidoctor extensions may still embed content into the document depending on whether they honor the safe mode setting.

This is the default safe mode for the API.

When Asciidoctor (and AsciidoctorJ) is used as API, it uses SECURE safe mode by default. This mode is the most restrictive one and in summary it disallows the document from attempting to read files from the file system and including their contents into the document.

We recommend you to set SAFE safe mode when converting AsciiDoc documents using AsciidoctorJ to have almost all Asciidoctor features such as icons, include directive or retrieving content from URIs enabled.

Safe mode is set as option when a document is converted. For example:

Options options = Options.builder()
                            .safe(SafeMode.SAFE)
                            .build();

String outfile = asciidoctor.convertFile(new File("sample.adoc"), options);

We are going to explain in more detail options in Conversion Options section.

You can read more about safe modes in asciidoctor.org/docs/user-manual/#running-asciidoctor-securely