70. Running Asciidoctor Securely

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.

UNSAFE

A safe mode level that disables any security features enforced by Asciidoctor. Ruby is still subject to its own restrictions.

This is the default safe mode for the CLI. Its integer value is 0.
SAFE

This safe mode level prevents access to files which reside outside of the parent directory of the source file. The include directive is enabled, but paths to include files must be within the parent directory. This mode allows assets (such as the stylesheet) to be embedded in the document.

Its integer value is 1.
SERVER

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

  • setting source-highlighter, doctype, docinfo and backend

  • seeing docdir (as it can reveal information about the host filesystem)

It allows icons and linkcss.

Its integer value is 10.
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 JavaScripts

  • sets the backend to html5

  • disables docinfo files

  • disables data-uri

  • disables interactive (opts=interactive) and inline (opts=inline) modes for SVGs

  • disables docdir and docfile (as these can reveal information about the host filesystem)

  • disables source highlighting

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

This is the default safe mode for the API. Its integer value is 20.

You can set Asciidoctor’s safe mode level using the CLI or API.

70.1. Set the Safe Mode in the CLI

When Asciidoctor is invoked via the CLI, the safe mode is set to UNSAFE by default. You can change the safe level by executing one of the following commands in the CLI.

-S, --safe-mode=SAFE_MODE

Sets the safe mode level of the document according to the assigned level (UNSAFE, SAFE, SERVER, SECURE).

--safe, asciidoctor-safe

Sets the safe mode level to SAFE. Provided for compatibility with the python AsciiDoc safe command.

70.2. Set the Safe Mode in the API

The default safe level in the API is SECURE.

In the API, you can set the safe mode using a string, symbol or integer value. The value must be set in the document constructor using the :safe option.

result = Asciidoctor.convert_file('master.adoc', :safe => 'server')

or

result = Asciidoctor.convert_file('master.adoc', :safe => :server)

or

result = Asciidoctor.convert_file('master.adoc', :safe => 10)

70.3. Set Attributes Based on the Safe Mode

Asciidoctor provides access to the current safe mode through built-in attributes. You can use these attributes to enable or disable content based on the current safe mode of the processor.

The safe mode can be referenced by one of the following attributes:

  • The value of the safe-mode-name attribute (e.g., unsafe, safe, etc.)

  • The value of the safe-mode-level attribute (e.g., 0, 10, etc.)

  • The presense of the safe-mode-<name> attribute, where <name> is the safe mode name.

The attributes in the next example define replacement text for features that are disabled in high security environments:

ifdef::safe-mode-secure[]
Link to chapters instead of including them.
endif::safe-mode-secure[]

This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure.