all2md.utils.html_sanitizer

HTML sanitization utilities for security.

This module provides utilities for sanitizing HTML content to prevent XSS and other security vulnerabilities. It supports both string-based sanitization (for renderers) and BeautifulSoup element validation (for parsers).

The module supports multiple sanitization strategies: - pass-through: No sanitization (use only with trusted content) - escape: HTML-escape all content - drop: Remove HTML nodes entirely - sanitize: Remove dangerous elements/attributes but preserve safe HTML

all2md.utils.html_sanitizer.sanitize_html_content(content: str, mode: Literal['pass-through', 'escape', 'drop', 'sanitize'] = 'escape') → str

Sanitize HTML content string according to the specified mode.

This function is designed for use in renderers when processing HTMLBlock and HTMLInline AST nodes.

Parameters:

content (str) – HTML content to sanitize
mode ({"pass-through", "escape", "drop", "sanitize"}, default "pass-through") – Sanitization mode: - “pass-through”: Return content unchanged (for trusted sources) - “escape”: HTML-escape all content - “drop”: Return empty string (remove all HTML) - “sanitize”: Remove dangerous elements and attributes

Returns:

Sanitized HTML content

Return type:

str

Examples

>>> sanitize_html_content("<script>alert('xss')</script>", mode="escape")
'&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;'

>>> sanitize_html_content("<script>alert('xss')</script>", mode="drop")
''

>>> sanitize_html_content("<p>Hello <strong>world</strong></p>", mode="sanitize")
'<p>Hello <strong>world</strong></p>'

>>> sanitize_html_content("<script>alert('xss')</script>", mode="sanitize")
''

all2md.utils.html_sanitizer.strip_html_tags(content: str) → str

Remove all HTML tags from content, leaving only text.

This is useful for extracting plain text from HTML (e.g., for TOC entries).

Parameters:: content (str) – HTML content
Returns:: Plain text with HTML tags removed
Return type:: str

Examples

>>> strip_html_tags("<p>Hello <strong>world</strong>!</p>")
'Hello world!'

>>> strip_html_tags("Plain text")
'Plain text'

all2md.utils.html_sanitizer.is_element_safe(element: Any, *, strip_framework_attributes: bool = False) → bool

Check if a BeautifulSoup element is safe (no dangerous tags/attributes).

This function is designed for use in the HTML parser (HtmlToAstConverter) to validate elements during parsing.

Parameters:

element (Any) – BeautifulSoup element to check
strip_framework_attributes (bool, default False) – If True, also check for JavaScript framework attributes (Alpine.js, Vue.js, Angular, HTMX, etc.) which can execute code in framework contexts. These are only dangerous if the HTML will be re-rendered in a browser with these frameworks present.

Returns:

True if element is safe, False if it contains dangerous content

Return type:

bool

Examples

>>> from bs4 import BeautifulSoup
>>> soup = BeautifulSoup("<p>Safe content</p>", "html.parser")
>>> is_element_safe(soup.p)
True

>>> soup = BeautifulSoup("<script>alert('xss')</script>", "html.parser")
>>> is_element_safe(soup.script)
False

>>> soup = BeautifulSoup('<div onclick="alert()">Click</div>', "html.parser")
>>> is_element_safe(soup.div)
False

>>> soup = BeautifulSoup('<div x-data="{open: false}">Alpine</div>', "html.parser")
>>> is_element_safe(soup.div)  # Without framework stripping
True
>>> is_element_safe(soup.div, strip_framework_attributes=True)  # With framework stripping
False

all2md.utils.html_sanitizer.is_url_safe(url: str) → bool

Check if a URL is safe (no dangerous schemes).

Parameters:: url (str) – URL to validate
Returns:: True if URL is safe, False if it uses a dangerous scheme
Return type:: bool

Examples

>>> is_url_safe("https://example.com")
True

>>> is_url_safe("javascript:alert('xss')")
False

>>> is_url_safe("data:text/html,<script>alert('xss')</script>")
False

all2md.utils.html_sanitizer.sanitize_url(url: str) → str

Sanitize a URL by removing dangerous schemes.

Parameters:: url (str) – URL to sanitize
Returns:: Sanitized URL, or empty string if the URL is dangerous
Return type:: str

Examples

>>> sanitize_url("https://example.com")
'https://example.com'

>>> sanitize_url("javascript:alert('xss')")
''

>>> sanitize_url("/relative/path")
'/relative/path'

all2md.utils.html_sanitizer.sanitize_html_string(content: str) → str

Sanitize HTML string by removing dangerous elements and attributes.

This is a basic string-based sanitizer. For more robust sanitization, consider using the bleach library if available.

Parameters:: content (str) – HTML content to sanitize
Returns:: Sanitized HTML with dangerous elements/attributes removed
Return type:: str