You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

86 lines
2.3 KiB

4 years ago
////
Included in:
- user-manual: 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.
[horizontal]
`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`
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`
* 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`.
--
////
|===
|{empty} |Unsafe |Safe |Server |Secure
|URI access
|system access
|base directory access
|docdir
|docfile
|docinfo
|backend
|doctype
|source-highlighter
|macros
|include
|data-uri
|linkcss
|icons
|===
TIP: GitHub processes AsciiDoc files using the `SECURE` level.
////
You can set Asciidoctor's safe mode level using the CLI or API.