From 69c2ec111588bf98a35df36541743f44dd34da68 Mon Sep 17 00:00:00 2001 From: lordofthejars Date: Mon, 29 Dec 2014 20:04:46 +0100 Subject: [PATCH 1/4] documents how safe mode works. Resolves issue #260 --- README.adoc | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.adoc b/README.adoc index aa2c475d..c5fdc849 100644 --- a/README.adoc +++ b/README.adoc @@ -303,6 +303,33 @@ StringBuffer htmlBuffer = writer.getBuffer(); System.out.println(htmlBuffer.toString()); ---- +[IMPORTANT] +==== +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. + +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 rendering AsciiDoc documents using AsciidoctorJ to have almost all Asciidoctor features such as _icons_, _include directive_ or retrieving content from _URIs_. +Safe mode is set as option when a document is rendered. +For example: + +[source, java] +---- +import static org.asciidoctor.OptionsBuilder.options; + +Map options = options().safe(SafeMode.SAFE) + .asMap(); + +String outfile = asciidoctor.convertFile(new File("sample.adoc"), options); +---- + +We are going to explain in more detail options in <>. + + +You can read more about safe modes in http://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely +==== + === Conversion options Asciidoctor supports numerous options, such as: From ca221eb162b68b73455f7929f1bc3badfa59337c Mon Sep 17 00:00:00 2001 From: lordofthejars Date: Mon, 29 Dec 2014 20:07:34 +0100 Subject: [PATCH 2/4] fixes problem with inner-references in github asciidoctor version. --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index c5fdc849..632aec31 100644 --- a/README.adoc +++ b/README.adoc @@ -324,7 +324,7 @@ Map options = options().safe(SafeMode.SAFE) String outfile = asciidoctor.convertFile(new File("sample.adoc"), options); ---- -We are going to explain in more detail options in <>. +We are going to explain in more detail options in <>. You can read more about safe modes in http://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely From f37034359648b2555be2e970d1184b73a943bf2c Mon Sep 17 00:00:00 2001 From: lordofthejars Date: Mon, 29 Dec 2014 20:10:10 +0100 Subject: [PATCH 3/4] change paragraphs to adapt to github layout --- README.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 632aec31..33403e56 100644 --- a/README.adoc +++ b/README.adoc @@ -310,7 +310,8 @@ Asciidoctor provides security levels that control the read and write access of a 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 rendering AsciiDoc documents using AsciidoctorJ to have almost all Asciidoctor features such as _icons_, _include directive_ or retrieving content from _URIs_. +We recommend you to set `SAFE` safe mode when rendering 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 rendered. For example: From 2c3d9a95db98c0aa3c8889ec6b3db3390c4aca74 Mon Sep 17 00:00:00 2001 From: Alex Soto Date: Tue, 30 Dec 2014 13:15:55 +0100 Subject: [PATCH 4/4] resolves #260 by adding a subsection about safe mode resolves #260 by adding a subsection about safe mode. --- README.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.adoc b/README.adoc index 33403e56..8f620dc2 100644 --- a/README.adoc +++ b/README.adoc @@ -303,8 +303,7 @@ StringBuffer htmlBuffer = writer.getBuffer(); System.out.println(htmlBuffer.toString()); ---- -[IMPORTANT] -==== +==== Safe mode and file system access 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. When Asciidoctor (and AsciidoctorJ) is used as _API_, it uses `SECURE` safe mode by default. @@ -329,7 +328,6 @@ We are going to explain in more detail options in <