diff options
| -rw-r--r-- | NEWS | 3 | ||||
| -rw-r--r-- | README.md | 10 | ||||
| -rw-r--r-- | src/main/java/org/zwobble/mammoth/DocumentConverter.java | 8 | ||||
| -rw-r--r-- | src/main/java/org/zwobble/mammoth/internal/conversion/DocumentToHtmlOptions.java | 24 | ||||
| -rw-r--r-- | src/test/java/org/zwobble/mammoth/tests/MammothTests.java | 24 |
5 files changed, 39 insertions, 30 deletions
@@ -2,7 +2,8 @@ * Ignore style definitions using a style ID that has already been used. -* Support disabling external file accesses using the external_file_access argument. +* Disable external file accesses by default. External file access can be enabled + using enableExternalFileAccess(). * Handle numbering levels defined without an index. @@ -255,9 +255,9 @@ Methods: if the document contains an embedded style map, then it is combined with the default style map. Call this to ignore any embedded style maps. -* `DocumentConvert disableExternalFileAccess()`: Source documents may reference files outside of the source document. - Call this to disable access to any such external files during the conversion process. - This is highly recommended when converting untrusted user input. +* `DocumentConverter enableExternalFileAccess()`: Source documents may reference files outside of the source document. + Access to any such external files is disabled by default. + Call this to enable access when converting trusted source documents. * `DocumentConverter preserveEmptyParagraphs()`: by default, empty paragraphs are ignored. Call this to preserve empty paragraphs in the output. @@ -330,6 +330,10 @@ For instance: automatically convert the document into HTML on the server, and embed the HTML into your website, this may allow arbitrary files on the server to be read and exfiltrated. +* + To avoid this issue, access to any such external files is disabled by default. + To enable access when converting trusted source documents, + call `enableExternalFileAccess()`. ## Writing style maps diff --git a/src/main/java/org/zwobble/mammoth/DocumentConverter.java b/src/main/java/org/zwobble/mammoth/DocumentConverter.java index c7dca20..2d4ee4a 100644 --- a/src/main/java/org/zwobble/mammoth/DocumentConverter.java +++ b/src/main/java/org/zwobble/mammoth/DocumentConverter.java @@ -62,11 +62,11 @@ public class DocumentConverter { /** * Source documents may reference files outside of the source document. - * Call this to disable access to any such external files during the conversion process. - * This is highly recommended when converting untrusted user input. + * Access to any such external files is disabled by default. + * Call this to enable access when converting trusted source documents. */ - public DocumentConverter disableExternalFileAccess() { - return new DocumentConverter(options.disableExternalFileAccess()); + public DocumentConverter enableExternalFileAccess() { + return new DocumentConverter(options.enableExternalFileAccess()); } /** diff --git a/src/main/java/org/zwobble/mammoth/internal/conversion/DocumentToHtmlOptions.java b/src/main/java/org/zwobble/mammoth/internal/conversion/DocumentToHtmlOptions.java index d12bbd4..706eec4 100644 --- a/src/main/java/org/zwobble/mammoth/internal/conversion/DocumentToHtmlOptions.java +++ b/src/main/java/org/zwobble/mammoth/internal/conversion/DocumentToHtmlOptions.java @@ -31,7 +31,7 @@ public class DocumentToHtmlOptions { private final StyleMap embeddedStyleMap; private final boolean disableDefaultStyleMap; private final boolean disableEmbeddedStyleMap; - private final boolean disableExternalFileAccess; + private final boolean enableExternalFileAccess; private final InternalImageConverter imageConverter; public DocumentToHtmlOptions( @@ -41,7 +41,7 @@ public class DocumentToHtmlOptions { StyleMap embeddedStyleMap, boolean disableDefaultStyleMap, boolean disableEmbeddedStyleMap, - boolean disableExternalFileAccess, + boolean enableExternalFileAccess, InternalImageConverter imageConverter ) { this.idPrefix = idPrefix; @@ -50,7 +50,7 @@ public class DocumentToHtmlOptions { this.embeddedStyleMap = embeddedStyleMap; this.disableDefaultStyleMap = disableDefaultStyleMap; this.disableEmbeddedStyleMap = disableEmbeddedStyleMap; - this.disableExternalFileAccess = disableExternalFileAccess; + this.enableExternalFileAccess = enableExternalFileAccess; this.imageConverter = imageConverter; } @@ -62,7 +62,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } @@ -75,7 +75,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } @@ -92,7 +92,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } @@ -105,7 +105,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, true, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } @@ -118,12 +118,12 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, true, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } - public DocumentToHtmlOptions disableExternalFileAccess() { + public DocumentToHtmlOptions enableExternalFileAccess() { return new DocumentToHtmlOptions( idPrefix, preserveEmptyParagraphs, @@ -144,7 +144,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, imageConverter ); } @@ -157,7 +157,7 @@ public class DocumentToHtmlOptions { embeddedStyleMap, disableDefaultStyleMap, disableEmbeddedStyleMap, - disableExternalFileAccess, + enableExternalFileAccess, InternalImageConverter.imgElement(imageConverter) ); } @@ -183,7 +183,7 @@ public class DocumentToHtmlOptions { } public boolean externalFileAccess() { - return !this.disableExternalFileAccess; + return this.enableExternalFileAccess; } public InternalImageConverter imageConverter() { diff --git a/src/test/java/org/zwobble/mammoth/tests/MammothTests.java b/src/test/java/org/zwobble/mammoth/tests/MammothTests.java index a072185..9058162 100644 --- a/src/test/java/org/zwobble/mammoth/tests/MammothTests.java +++ b/src/test/java/org/zwobble/mammoth/tests/MammothTests.java @@ -89,14 +89,16 @@ public class MammothTests { } @Test - public void imagesStoredOutsideOfDocumentAreIncludedInOutput() throws IOException { + public void whenExternalFileAccessIsEnabledThenImagesStoredOutsideOfDocumentAreIncludedInOutput() throws IOException { Path tempDirectory = Files.createTempDirectory("mammoth-"); try { Path documentPath = tempDirectory.resolve("external-picture.docx"); Files.copy(TestData.file("external-picture.docx").toPath(), documentPath); Files.copy(TestData.file("tiny-picture.png").toPath(), tempDirectory.resolve("tiny-picture.png")); assertThat( - new DocumentConverter().convertToHtml(documentPath.toFile()), + new DocumentConverter() + .enableExternalFileAccess() + .convertToHtml(documentPath.toFile()), isSuccess("<p><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAIAAAACUFjqAAAAAXNSR0IArs4c6QAAAAlwSFlzAAAOvgAADr4B6kKxwAAAABNJREFUKFNj/M+ADzDhlWUYqdIAQSwBE8U+X40AAAAASUVORK5CYII=\" /></p>")); } finally { tempDirectory.toFile().delete(); @@ -104,13 +106,15 @@ public class MammothTests { } @Test - public void warnIfDocumentHasImagesStoredOutsideOfDocumentWhenPathOfDocumentIsUnknown() throws IOException { + public void whenExternalFileAccessIsEnabledThenWarnIfDocumentHasImagesStoredOutsideOfDocumentWhenPathOfDocumentIsUnknown() throws IOException { Path tempDirectory = Files.createTempDirectory("mammoth-"); try { Path documentPath = tempDirectory.resolve("external-picture.docx"); Files.copy(TestData.file("external-picture.docx").toPath(), documentPath); assertThat( - new DocumentConverter().convertToHtml(documentPath.toUri().toURL().openStream()), + new DocumentConverter() + .enableExternalFileAccess() + .convertToHtml(documentPath.toUri().toURL().openStream()), allOf( hasProperty("value", equalTo("")), hasProperty("warnings", contains( @@ -121,16 +125,14 @@ public class MammothTests { } @Test - public void warnIfDocumentHasImagesStoredOutsideOfDocumentWhenExternalFileAccessIsDisabled() throws IOException { + public void givenExternalFileAccessIsDisabledByDefaultThenWarnIfDocumentHasImagesStoredOutsideOfDocument() throws IOException { Path tempDirectory = Files.createTempDirectory("mammoth-"); try { Path documentPath = tempDirectory.resolve("external-picture.docx"); Files.copy(TestData.file("external-picture.docx").toPath(), documentPath); Files.copy(TestData.file("tiny-picture.png").toPath(), tempDirectory.resolve("tiny-picture.png")); assertThat( - new DocumentConverter() - .disableExternalFileAccess() - .convertToHtml(documentPath.toFile()), + new DocumentConverter().convertToHtml(documentPath.toFile()), allOf( hasProperty("value", equalTo("")), hasProperty("warnings", contains( @@ -144,13 +146,15 @@ public class MammothTests { } @Test - public void warnIfImagesStoredOutsideOfDocumentAreNotFound() throws IOException { + public void whenExternalFileAccessIsEnabledWarnIfImagesStoredOutsideOfDocumentAreNotFound() throws IOException { Path tempDirectory = Files.createTempDirectory("mammoth-"); try { Path documentPath = tempDirectory.resolve("external-picture.docx"); Files.copy(TestData.file("external-picture.docx").toPath(), documentPath); assertThat( - new DocumentConverter().convertToHtml(documentPath.toFile()), + new DocumentConverter() + .enableExternalFileAccess() + .convertToHtml(documentPath.toFile()), allOf( hasProperty("value", equalTo("")), hasProperty("warnings", contains( |