From a89b7f9335b2d77fc2e639eb3ed07e0f71bc5cd5 Mon Sep 17 00:00:00 2001 From: DJ Ramones <50655786+djramones@users.noreply.github.com> Date: Mon, 3 Jul 2023 16:34:31 +0800 Subject: [PATCH 1/3] Clarify docs regarding security configuration This includes a small edit to the project README. --- README.md | 2 +- docs/index.md | 2 +- docs/security.md | 39 ++++++++++++++++++++++++--------------- 3 files changed, 26 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9bebca33..43a5da23 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ - Configurable syntax: you can add new rules and even replace existing ones. - Pluggable: Adds syntax extensions to extend the parser (see the [plugin list][md-plugins]). - High speed (see our [benchmarking tests][md-performance]) -- [Safe by default][md-security] +- Easy to configure for [security][md-security] - Member of [Google's Assured Open Source Software](https://cloud.google.com/assured-open-source-software/docs/supported-packages) This is a Python port of [markdown-it], and some of its associated plugins. diff --git a/docs/index.md b/docs/index.md index 96827f74..a5484518 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ - {fa}`check,text-success mr-1` Configurable syntax: you can add new rules and even replace existing ones. - {fa}`check,text-success mr-1` Pluggable: Adds syntax extensions to extend the parser (see the [plugin list](md/plugins)) - {fa}`check,text-success mr-1` High speed (see our [benchmarking tests](md/performance)) -- {fa}`check,text-success mr-1` [Safe by default](md/security) +- {fa}`check,text-success mr-1` Easy to configure for [security](md/security) - {fa}`check,text-success mr-1` Member of [Google's Assured Open Source Software](https://cloud.google.com/assured-open-source-software/docs/supported-packages) For a good introduction to [markdown-it] see the __[Live demo](https://markdown-it.github.io)__. diff --git a/docs/security.md b/docs/security.md index 3770d35a..8510d7e2 100644 --- a/docs/security.md +++ b/docs/security.md @@ -2,27 +2,36 @@ # Security -Many people don't understand that markdown format does not care much about security. -In many cases you have to pass output to sanitizers. -`markdown-it` provides 2 possible strategies to produce safe output: +Contrary to some expectations, the Markdown format, by default, is not particularly concerned about security. +This is fine for many use cases, for example when writing articles for one's own blog or composing technical documentation for a software package. -1. Don't enable HTML. Extend markup features with [plugins](md/plugins). - We think it's the best choice and use it by default. - - That's ok for 99% of user needs. - - Output will be safe without sanitizer. -2. Enable HTML and use external sanitizer package(s). +However, extra precautions are needed when parsing content from untrusted sources. +Generally, the output should be run through sanitizers to ensure safety and prevent vulnerabilities like cross-site scripting (XSS). +With `markdown-it`/`markdown-it-py`, there are two strategies for doing this: -Also by default `markdown-it` prohibits some kind of links, which could be used -for XSS: +1. Enable HTML (as is needed for full CommonMark compliance), and then use external sanitizer package(s). +2. Disable HTML, and then use [plugins](md/plugins) to selectively enable markup features. + This removes the need for further sanitizing. + +```{warning} +Unlike the original `markdown-it` JavaScript project, which uses the second, safe-by-default strategy, `markdown-it-py` enables less-secure (but more convenient) CommonMark-compliant settings by default. + +This is not safe when using `markdown-it-py` in web applications that parse user-submitted content. +In such cases, [using the `js-default` preset](using.md) is strongly recommended. +For example: + +```python +from markdown_it import MarkdownIt +MarkdownIt("js-default").render("*user-submitted* text") +``` + +Note that even with the default configuration, `markdown-it-py` prohibits some kind of links which could be used for XSS: - `javascript:`, `vbscript:` - `file:` -- `data:`, except some images (gif/png/jpeg/webp). - -So, by default `markdown-it` should be safe. We care about it. +- `data:` (except some images: gif/png/jpeg/webp) -If you find a security problem - contact us via . -Such reports are fixed with top priority. +If you find a security problem, please report it to . ## Plugins From 1d924d6c87513bb922a1358e500882834403a179 Mon Sep 17 00:00:00 2001 From: DJ Ramones <50655786+djramones@users.noreply.github.com> Date: Wed, 5 Jul 2023 20:18:47 +0800 Subject: [PATCH 2/3] Update docs/security.md Co-authored-by: Chris Sewell --- docs/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security.md b/docs/security.md index 8510d7e2..6075baaf 100644 --- a/docs/security.md +++ b/docs/security.md @@ -2,8 +2,8 @@ # Security -Contrary to some expectations, the Markdown format, by default, is not particularly concerned about security. -This is fine for many use cases, for example when writing articles for one's own blog or composing technical documentation for a software package. +By default, the `MardownIt` parser is initialised to comply with the [CommonMark spec](https://spec.commonmark.org/), which allows for parsing aritrary HTML tags. +This can be useful for many use cases, for example when writing articles for one's own blog or composing technical documentation for a software package. However, extra precautions are needed when parsing content from untrusted sources. Generally, the output should be run through sanitizers to ensure safety and prevent vulnerabilities like cross-site scripting (XSS). From b2d571146843129ec94fc55064a844cee9d78d10 Mon Sep 17 00:00:00 2001 From: DJ Ramones <50655786+djramones@users.noreply.github.com> Date: Wed, 5 Jul 2023 20:20:13 +0800 Subject: [PATCH 3/3] Tweak security.md wording --- docs/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security.md b/docs/security.md index 6075baaf..7cbf765f 100644 --- a/docs/security.md +++ b/docs/security.md @@ -2,7 +2,7 @@ # Security -By default, the `MardownIt` parser is initialised to comply with the [CommonMark spec](https://spec.commonmark.org/), which allows for parsing aritrary HTML tags. +By default, the `MarkdownIt` parser is initialised to comply with the [CommonMark spec](https://spec.commonmark.org/), which allows for parsing arbitrary HTML tags. This can be useful for many use cases, for example when writing articles for one's own blog or composing technical documentation for a software package. However, extra precautions are needed when parsing content from untrusted sources. @@ -14,7 +14,7 @@ With `markdown-it`/`markdown-it-py`, there are two strategies for doing this: This removes the need for further sanitizing. ```{warning} -Unlike the original `markdown-it` JavaScript project, which uses the second, safe-by-default strategy, `markdown-it-py` enables less-secure (but more convenient) CommonMark-compliant settings by default. +Unlike the original `markdown-it` JavaScript project, which uses the second, safe-by-default strategy, `markdown-it-py` enables the more convenient, but less secure, CommonMark-compliant settings by default. This is not safe when using `markdown-it-py` in web applications that parse user-submitted content. In such cases, [using the `js-default` preset](using.md) is strongly recommended.