diff options
| author | Dan Allen <dan.j.allen@gmail.com> | 2021-11-07 23:58:32 -0700 |
|---|---|---|
| committer | Dan Allen <dan.j.allen@gmail.com> | 2021-11-08 02:54:07 -0700 |
| commit | 34bd247150883f4b46922ffed40ae2c88401e53b (patch) | |
| tree | 24b3e5f310a6ce5c95344355dd67fc02652e4e51 /docs/modules | |
| parent | bf74a18657ad7b298c676c7d14c5a04b3ed348bd (diff) | |
document the security assumptions of the processor as they related to the safe mode [skip ci]
Diffstat (limited to 'docs/modules')
| -rw-r--r-- | docs/modules/ROOT/pages/safe-modes.adoc | 16 |
1 files changed, 15 insertions, 1 deletions
diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc index 5a442236..27e94462 100644 --- a/docs/modules/ROOT/pages/safe-modes.adoc +++ b/docs/modules/ROOT/pages/safe-modes.adoc @@ -3,7 +3,21 @@ Asciidoctor provides security levels that control the read and write access of attributes, include directives, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level. -The safe mode can be set from the xref:cli:set-safe-mode.adoc[CLI] and the xref:api:set-safe-mode.adoc[API]. +.Security assumptions +[#security-assumptions] +**** +Asciidoctor's safe modes are primarily focused on what the processor is permitted to do. +The safe modes do not provide a comprehensive security framework. +In particular, there's no safe mode that restricts the kind of content the author can pass through to the output document. +In other words, the safe mode setting does not provide a way to santiize the output. + +Asciidoctor performs sensible escaping to allow an author to safely input text, but does not limit the content that can be included in the output using passthrough blocks or custom substitutions. +The reason for this policy is that we assume the document will be passed through a sanitizer if the HTML must be embedded directly into a web page, precisely what GitHub and GitLab do. +This postprocessing (which could be done using a postprocessor extension) is better handled by a separate tool since. +There are many permutations to consider and only a separate tool would know which restrictions to apply for a given situation. +**** + +The safe mode can be set from the xref:cli:set-safe-mode.adoc[CLI] and the xref:api:set-safe-mode.adoc[API]. You can also xref:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. [#unsafe] |