一个简单的基于安全列表的HTML清理工具。
项目描述
注意:2023-01-23: Bleach已弃用。 请参阅问题: https://github.com/mozilla/bleach/issues/698
Bleach是一个基于允许列表的HTML清理库,可以转义或删除标记和属性。
Bleach还可以安全地将文本链接化,应用Django的urlize过滤器无法应用的自定义过滤器,并可选择设置rel属性,甚至是在文本中已有的链接上。
Bleach旨在清理来自不受信任源头的文本。如果你发现自己为了允许网站管理员进行大量操作而跳来跳去,你可能超出了使用案例。要么信任这些用户,要么不信任。
因为它依赖于html5lib,所以Bleach在处理奇怪、古怪的HTML片段方面与现代浏览器一样好。Bleach的任何方法都可以修复不平衡或嵌套错误的标签。
GitHub上的版本是最新的,包含最新的错误修复。您可以在ReadTheDocs上找到完整的文档。
- 代码:
- 文档:
- 问题跟踪器:
- 许可证:
Apache许可证v2;请参阅LICENSE文件
报告错误
对于常规错误,请在我们的问题跟踪器中报告。
如果您认为您发现了一个安全漏洞,请在我们的错误跟踪器中提交一个安全的错误报告或发送电子邮件至security AT mozilla DOT org。
有关安全相关错误披露和用于发送加密邮件或验证从该地址收到的响应的PGP密钥的更多信息,请参阅我们的wiki页面。
安全
Bleach是一个以安全为重点的库。
我们有一个负责任的漏洞报告流程。如果您报告的是安全问题,请使用该流程。
安全问题是在私下修复的。在落地这样的修复后,我们将发布版本。
对于每个版本,我们在CHANGES中的安全相关问题部分标记了我们已修复的安全问题。我们包括任何相关的CVE链接。
安装Bleach
Bleach可在PyPI上找到,因此您可以使用pip安装它。
$ pip install bleach
升级Bleach
基本使用
使用Bleach最简单的方法是
>>> import bleach
>>> bleach.clean('an <script>evil()</script> example')
u'an <script>evil()</script> example'
>>> bleach.linkify('an http://example.com url')
u'an <a href="http://example.com" rel="nofollow">http://example.com</a> url'
行为准则
本项目和存储库受Mozilla的行为准则和礼仪指南的管辖。有关更多详细信息,请参阅CODE_OF_CONDUCT.md
Bleach更改
版本6.1.0(2023年10月6日)
向后不兼容的更改
停止支持Python 3.7。(#709)
安全修复
无
错误修复
添加对Python 3.12的支持。(#710)
修复查询字符串中数组导致的linkify问题。(#436)
处理更多以字符数据开始的<情况。(#705)
修复标签内链接化时的实体。(#704)
将tinycss2的cap更新为<1.3。(#702)
更新Sphinx要求
添加github actions的dependabot并更新github actions
版本6.0.0(2023年1月23日)
向后不兼容的更改
bleach.clean、bleach.sanitizer.Cleaner、bleach.html5lib_shim.BleachHTMLParser:将tags和protocols参数从列表更改为集合。
旧版本6.0.0之前
bleach.clean( "some text", tags=["a", "p", "img"], # ^ ^ list protocols=["http", "https"], # ^ ^ list )
新版本6.0.0及以后
bleach.clean( "some text", tags={"a", "p", "img"}, # ^ ^ set protocols={"http", "https"}, # ^ ^ set )
bleach.linkify、bleach.linkifier.Linker:将skip_tags和recognized_tags参数从列表更改为集合。
旧版本6.0.0之前
bleach.linkify( "some text", skip_tags=["pre"], # ^ ^ list ) linker = Linker( skip_tags=["pre"], # ^ ^ list recognized_tags=html5lib_shim.HTML_TAGS + ["custom-element"], # ^ ^ ^ list # | # | list concatenation )
新版本6.0.0及以后
bleach.linkify( "some text", skip_tags={"pre"}, # ^ ^ set ) linker = Linker( skip_tags={"pre"}, # ^ ^ set recognized_tags=html5lib_shim.HTML_TAGS | {"custom-element"}, # ^ ^ ^ set # | # | union operator )
bleach.sanitizer.BleachSanitizerFilter:现在使用strip_allowed_elements而不是strip_allowed_tags。我们现在在所有地方都使用“tags”而不是在某些地方使用“tags”和在其他地方使用“elements”的混合。
安全修复
无
错误修复
添加对Python 3.11的支持。(#675)
修复BleachSanitizerFilter中的API怪异行为。(#649)
我们现在在所有地方都使用“tags”而不是“elements”——不再有“elements”的奇怪重载。
此外,它不再调用超类构造函数。
当未设置 css_sanitizer 但允许 style 属性时添加警告。(#676)
修复字符实体处理。(#501)
重新整理开发依赖,使用 requirements-dev.txt 和 requirements-flake8.txt 而不是附加组件。
修复项目基础设施,使其基于 tox,以便在隔离环境中更容易运行与开发中相同的 CI 任务。
更新 CI 中的操作版本。
尽可能使用 f-strings。使测试参数化,以便更容易阅读/维护。
版本 5.0.1(2022年6月27日)
安全修复
无
错误修复
感谢 @shadchin!为 tinycss2 require 添加缺失的逗号。
基于 wpt url 测试添加 url 解析测试。(#688)
如果 "https" 在允许列表中,支持无方案的 URL。(#662)
处理在不是标签开始处的情况下不逃逸 < 的边缘情况。(#544)
修复文档中的引用警告。(#660)
正确对电子邮件地址部分进行 urlencode。感谢 @larseggert!(#659)
版本 5.0.0(2022年4月7日)
向后不兼容的更改
clean 和 linkify 现在保留 HTML 属性的顺序。感谢 @askoretskly!(#566)
停止支持 Python 3.6。感谢 @hugovk!(#629)
现在样式标签中的 CSS 清洗完全不同。如果您正在使用 Bleach clean 清洗样式标签中的 CSS,则需要更新您的代码,并且需要安装 CSS 附加组件。
pip install 'bleach[css]'
有关如何进行 CSS 清洗的说明,请参阅文档。(#633)
安全修复
无
错误修复
重新整理开发依赖。我们不再有 requirements-dev.in/requirements-dev.txt。相反,我们使用开发附加组件。
有关更多详细信息,请参阅开发文档。(#620)
当删除块级标签时添加换行。感谢 @jvanasco!(#369)
版本 4.1.0(2021年8月25日)
特性
Python 3.9 支持
安全修复
无
错误修复
更新清洗器 clean 以使用 vendored 3.6.14 stdlib urllib.parse,以修复 Python 3.9 上的测试失败。(#536)
版本 4.0.0(2021年8月3日)
向后不兼容的更改
停止支持不支持的 Python 版本 <3.6。(#520)
安全修复
无
特性
修复 linkify 文档中的属性名(感谢 @CheesyFeet!)
版本 3.3.1(2021年7月14日)
安全修复
无
特性
为 CVE-2021-23980 / GHSA-vv2x-vrpj-qqpq 添加更多测试
将 Python 版本提升到 3.8 以用于 tox doc、vendorverify 和 lint 目标
更新错误报告模板标签
更新 vendorverify 脚本来检测和失败,当附加文件被 vendored 时
更新发布过程文档,以检查本地 vendorverify 是否通过
错误修复
从 v3.3.0 whl 中删除多余的 vendored django (#595)
重复修复 h1 标题文档(感谢 Nguyễn Gia Phong / @McSinyx!)
版本 3.3.0(2021年2月1日)
向后不兼容的更改
clean 即使 strip_comments=False 也逃逸 HTML 注释
安全修复
修复 bug 1621692 / GHSA-m6xf-fq7q-8743。请参阅公告以获取详细信息。
特性
无
错误修复
无
版本 3.2.3(2021年1月26日)
安全修复
无
特性
无
错误修复
修复 clean 和 linkify 对某些输入引发 ValueError。感谢 @Google-Autofuzz。
版本 3.2.2(2021年1月20日)
安全修复
无
特性
将 CI 迁移到 Github Actions。感谢 @hugovk。
错误修复
修复 linkify 在某些输入上引发 IndexError。感谢 @Google-Autofuzz。
版本 3.2.1(2020年9月18日)
安全修复
无
特性
无
错误修复
将链接化器更改为添加 rel="nofollow",如文档所述。感谢 @mitar。
抑制 html5lib 清洗器的 DeprecationWarning (#557)
版本 3.2.0(2020年9月16日)
安全修复
无
特性
无
错误修复
将 html5lib 依赖项升级到版本 1.1.0。感谢 Sam Sneddon。
更新 tests_website 术语。感谢 Thomas Grainger。
版本 3.1.5(2020年4月29日)
安全修复
无
特性
无
错误修复
用 packaging 替换缺失的 setuptools 依赖项。感谢 Benjamin Peterson。
版本 3.1.4(2020年3月24日)
安全修复
bleach.clean 解析样式属性的行为可能导致正则表达式拒绝服务(ReDoS)。
当使用允许的标签和带有允许 style 属性的标签调用 bleach.clean 时,容易受到 ReDoS 的影响。例如,bleach.clean(..., attributes={'a': ['style']})。
这个问题在 Bleach 版本 v3.1.3、v3.1.2、v3.1.1、v3.1.0、v3.0.0、v2.1.4 和 v2.1.3 中得到了确认。早期版本使用了类似的正则表达式,也应被视为存在漏洞。
建议所有使用 Bleach <=v3.1.3 的人升级。
向后不兼容的更改
带有破折号、单引号或双引号值的样式属性会被清理而不是传递。
特性
无
错误修复
无
版本 3.1.3(2020年3月17日)
安全修复
无
向后不兼容的更改
停止支持 Python 3.4。感谢,@hugovk!
停止对已弃用的 setup.py test 的支持。感谢,@jdufresne! (#507)
特性
添加对 Python 3.8 的支持。感谢,@jdufresne!
添加对 PyPy 7 的支持。感谢,@hugovk!
将 pypy3 测试添加到 tox 和 travis。感谢,@jdufresne!
错误修复
添加相对链接到行为准则。 (#442)
修复拼写错误:curren -> current 在 tests/test_clean.py 中。感谢,timgates42! (#504)
修复处理非 ASCII 样式属性。感谢,@sekineh! (#426)
简化 tox 配置。感谢,@jdufresne!
使文档可重复。感谢,@lamby!
修复代码注释中的拼写错误。感谢,@zborboa-g!
修复异常值测试。感谢,@mastizada!
修复解析器标签 NoneType 异常。感谢,@bope!
改进 linkify 中的 TLD 支持。感谢,@pc-coholic!
版本 3.1.2(2020年3月11日)
安全修复
bleach.clean 解析内嵌 MathML 和 SVG 内容(带有 RCDATA 标签)的行为与浏览器行为不匹配,可能导致突变 XSS。
当使用 strip=False 和带有 math 或 svg 标签的标签以及允许的标签白名单中包含一个或多个 RCDATA 标签(script、noscript、style、noframes、iframe、noembed 或 xmp)时,调用 bleach.clean 会受到突变 XSS 的影响。
这个安全问题在 Bleach 版本 v3.1.1 中得到了确认。早期版本可能也会受到影响。
建议所有使用 Bleach <=v3.1.1 的人升级。
向后不兼容的更改
无
特性
无
错误修复
无
版本 3.1.1(2020年2月13日)
安全修复
bleach.clean 解析 noscript 标签的行为与浏览器行为不匹配。
当允许 noscript 和一个或多个原始文本标签(title、textarea、script、style、noembed、noframes、iframe 和 xmp)时,调用 bleach.clean 会受到突变 XSS 的影响。
这个安全问题在 Bleach 版本 v2.1.4、v3.0.2 和 v3.1.0 中得到了确认。早期版本可能也会受到影响。
强烈建议所有使用 Bleach <=v3.1.0 的人升级。
向后不兼容的更改
无
特性
无
错误修复
无
版本 3.1.0(2019年1月9日)
安全修复
无
向后不兼容的更改
无
特性
向 Linker 类添加 recognized_tags 参数。这修复了在单独链接化时某些标签被转义的问题。默认为 HTML5 标签列表。感谢,Chad Birch! (#409)
错误修复
将 six>=1.9 添加到要求中。感谢,Dave Shawley (#416)
修复属性名中可能包含无效字符的情况。(#419)
修复了LinkifyFilter无法匹配跨越&的链接的问题。(#422)
修复了在BleachHTMLParser解析meta标签时,InputStreamWithMemory的问题。(#431)
修复了doctests。(#357)
版本 3.0.2(2018年10月11日)
安全修复
无
向后不兼容的更改
无
特性
无
错误修复
在净化后合并Characters标记。这修复了LinkifyFilter中只链接化url部分的问题。(#374)
版本 3.0.1(2018年10月9日)
安全修复
无
向后不兼容的更改
无
特性
支持Python 3.7。它对Python 3.7的支持很好,但我们将其添加到我们测试的Python环境列表中,因此现在正式支持。(#377)
错误修复
修复了在clean中list对象没有属性lower的问题。(#398)
修复了在linkify中abbr被转义的问题。(#400)
版本 3.0.0(2018年10月3日)
安全修复
无
向后不兼容的更改
许多函数从一个模块移动到另一个模块。
这些函数和类从bleach.sanitizer移动到了bleach.html5lib_shim
convert_entity
convert_entities
match_entity
next_possible_entity
BleachHTMLSerializer
BleachHTMLTokenizer
BleachHTMLParser
这些函数和类没有文档,也不是公共API的一部分,但人们可能会阅读代码并使用它们,所以我们将其视为不兼容的API更改。
如果您正在使用它们,您需要更新您的代码。
特性
Bleach不再依赖于html5lib。html5lib==1.0.1现在已包含在Bleach中。如果您没有其他需求需要html5lib,则可以将其从需求文件中删除。
这意味着Bleach现在可以与依赖于html5lib的其他库正常工作,而不管它们需要html5lib的哪个版本。(#386)
错误修复
修复了使用clean或linkify时添加的标签。这是Bleach 2.0重写中的一个长期回归问题。(#280,#392)
修复了使用clean或linkify时,<isindex>被替换为一个字符串的问题。现在它将根据是否在允许的标签中而被转义或删除。(#279)
版本 2.1.4(2018年8月16日)
安全修复
无
向后不兼容的更改
取消了对Python 3.3的支持。(#328)
特性
无
错误修复
正确处理模糊的ampersands。(#359)
版本 2.1.3(2018年3月5日)
安全修复
如果值包含字符实体,具有URI值的属性没有得到适当的净化。使用字符实体,可以构造一个具有不允许的方案的URI值,该值将未经净化地通过。
此安全问题是在Bleach 2.1中引入的。强烈建议使用Bleach 2.1的用户升级。
向后不兼容的更改
无
特性
无
错误修复
修复了属性URI值净化的其他边缘案例,并改进了对此代码的测试。
版本 2.1.2(2017年12月7日)
安全修复
无
向后不兼容的更改
无
特性
无
错误修复
支持html5lib-python 1.0.1。(#337)
为支持html5lib-python < 1.0添加了弃用警告。
切换到semver。
版本 2.1.1(2017年10月2日)
安全修复
无
向后不兼容的更改
无
特性
无
错误修复
修复了在LANG=时setup.py打开文件的问题。(#324)
版本 2.1(2017年9月28日)
安全修复
将控制字符(尤其是退格)转换为“?”,防止恶意复制粘贴情况。(#298)
有关详细信息,请参阅https://github.com/mozilla/bleach/issues/298。
这影响了Bleach的所有早期版本。如果您无法升级到Bleach 2.1,请查看该问题上的评论以减轻问题。
向后不兼容的更改
重新执行了版本控制。现在bleach.VERSION不再可用。请使用bleach.__version__中的字符串版本,并使用pkg_resources.parse_version进行解析。(#307)
清洁,链接化:清洁和链接化只应接受文本类型;感谢,Janusz!(#292)
清洁,链接化:只接受Unicode或UTF-8编码的字符串(#176)
特性
错误修复
bleach.clean()不再对实体进行转义,包括那些在结尾缺少;的实体,这在URL和其他地方可能会发生。(#143)
链接化:修复mailto链接内的http链接;感谢,sedrubal!(#300)
在文档中明确安全策略(#303)
修复对html5lib 1.0b8、1.0b9和1.0b10的依赖性指定;感谢,Zoltán!(#268)
在README中添加Bleach与html5lib的比较;感谢,Stu Cox!(#278)
修复没有href属性的标签上的KeyError异常;感谢,Alex Defsen!(#273)
添加测试网站和脚本,用于在浏览器中测试bleach.clean()输出;感谢,Greg Guthe!
版本 2.0 (2017年3月8日)
安全修复
无
向后不兼容的更改
移除了对Python 2.6的支持。(#206)
移除了对Python 3.2的支持。(#224)
Bleach不再支持html5lib < 0.99999999 (8 9s)。
本版本是一个重写,以使用新的清理API,因为旧的API在html5lib 0.99999999 (8 9s)中被弃用。
如果你使用的是0.9999999 (7 9s),请升级到0.99999999 (8 9s)或更高版本。
如果你使用的是1.0b8(相当于0.9999999 (7 9s)),请升级到1.0b9(相当于0.99999999 (8 9s))或更高版本。
bleach.clean及其朋友被重写
clean被重新实现为html5lib过滤器,并在HTML解析 -> 遍历 -> 序列化过程中发生在一个不同的步骤。因此,与之前的版本相比,clean的输出有一些差异。
在本版本中,即使要转义的标签也需要添加结束标签。
bleach.clean及其朋友现在接受三个参数:标签、属性名和属性值。之前它们只接受属性名和属性值。
所有属性调用都需要更新。
bleach.linkify被重写
linkify被重新实现为html5lib过滤器。因此,它不再接受一个tokenizer参数。
用于调整链接属性的回调函数现在接受一个命名空间属性。
之前你可能这样做
def check_protocol(attrs, is_new): if not attrs.get('href', '').startswith('http:', 'https:')): return None return attrs
现在更像这样
def check_protocol(attrs, is_new): if not attrs.get((None, u'href'), u'').startswith(('http:', 'https:')): # ^^^^^^^^^^^^^^^ return None return attrs
此外,你需要确保始终使用Unicode值。如果不这样做,html5lib将引发一个断言错误,指出值不是Unicode。
所有链接化过滤器都需要更新。
bleach.linkify及其朋友有一个skip_pre参数–这已被更通用的skip_tags参数所取代。
以前,你可能这样做
bleach.linkify(some_text, skip_pre=True)
在Bleach 2.0中,等效的做法是
bleach.linkify(some_text, skip_tags=['pre'])
你可以跳过其他标签,例如style或script或你不想进行链接化的其他地方。
使用skip_pre的所有链接化调用都需要更新。
变更
支持Python 3.6。
支持html5lib >= 0.99999999 (8 9s)。
有一个可以实例化为你喜欢的清洁设置的bleach.sanitizer.Cleaner类,以便于重用。
有一个可以实例化为你喜欢的链接化设置的bleach.linkifier.Linker类,以便于重用。
有一个可以传递给bleach.sanitizer.Cleaner作为过滤器的bleach.linkifier.LinkifyFilter,允许你在一趟操作中清理和链接化。
bleach.clean及其朋友现在可以接受一个可调用作为属性arg值。
大量错误修复。
清理了测试。
修复了文档。
版本 1.5(2016年11月4日)
安全修复
无
向后不兼容的更改
clean:现在ALLOWED_PROTOCOLS的列表默认为http、https和mailto。
之前是一个很长的协议列表,类似于ed2k、ftp、http、https、irc、mailto、news、gopher、nntp、telnet、webcal、xmpp、callto、feed、urn、aim、rsync、tag、ssh、sftp、rtsp、afs、data。(#149)
变更
clean:已将protocols添加到参数列表中,以便您可以覆盖允许的协议列表。感谢,Andreas Malecki! (#149)
linkify:修复了涉及电子邮件地址末尾句点的bug。感谢,Lorenz Schori! (#219)
linkify:修复了非ASCII端口的链接化问题。感谢,Alexandre,Macabies! (#207)
linkify:修复了在删除节点时不当删除节点尾部的bug。(#132)
修复了一个偶尔失败的测试。(#161)
从nose切换到py.test。(#204)
添加了所有支持的Python和html5lib版本的测试矩阵。(#230)
限制html5lib >=0.999,!=0.9999,!=0.99999,<0.99999999,因为0.9999和0.99999有bug。
添加了对python setup.py test的支持。(#97)
版本 1.4.3(2016年5月23日)
安全修复
无
变更
限制为html5lib >=0.999,<0.99999999,因为即将更改sanitizer api。(#195)
版本 1.4.2(2015年9月11日)
变更
linkify:修复了在parse_email=True时linkify导致的挂起。(#124)
linkify:修复了删除第一个子链接时linkify崩溃的问题。(#136)
更新了TLDs。
linkify:在链接化时不要删除外部括号。(#146)
版本 1.4.1(2014年12月15日)
变更
输出属性的一致顺序。
支持Python 3.4。
版本 1.4(2014年1月12日)
变更
linkify:更新linkify以使用etree类型的Treewalker代替simpletree。
更新html5lib到版本>=0.999。
使用six更新所有代码以兼容Python 3和2。
切换到Apache License。
版本 1.3
仅供Python 3分支使用。
版本 1.2.2(2013年5月18日)
由于API的重大更改,暂时将html5lib固定在版本0.95。(#32)
版本 1.2.1(2013年2月19日)
clean()不再将feed:视为可接受的协议,因为浏览器行为不一致。(#34)
版本 1.2(2013年1月28日)
linkify()已发生很大变化。许多关键字参数已被单个回调列表所取代。请参阅文档以获取更多信息。(#36)
Bleach在链接化时将不再考虑不可接受的协议。
linkify()现在接受一个tokenizer参数,允许它跳过清理。
delinkify()已删除。
从_render中删除了异常处理。clean()和linkify()现在可能抛出异常。
linkify()正确地忽略了协议和域名的大小写。
linkify()正确地处理了标签内的标记。
版本 1.1.5
版本 1.1.4
版本 1.1.3(2012年7月10日)
修复了当parse_email=True时解析裸URL的问题。
版本 1.1.2(2012年6月1日)
修复了样式属性清理器中的挂起。(#48)
允许样式属性值中的/。
版本 1.1.1(2012年2月17日)
修复了html5lib 0.9.5的tokenizer。
版本 1.1.0(2011年10月24日)
linkify()现在理解端口号。(#38)
记录了字符编码行为。(#41)
向linkify()添加一个可选的目标参数。
添加delinkify()方法。(#56)
为delinkify()支持子域名白名单。(#57,#48)
版本 1.0.4(2011年9月2日)
切换到SemVer git标签。
使 linkify() 在尾随标点符号方面更智能。 (#30)
在渲染问题时将 exc_info 传递给日志记录器。
为属性添加通配符键。 (#19)
使 linkify() 使用 HTMLSanitizer 分词器。 (#36)
修复括号中的 URL。 (#23)
使 linkify() UTF-8 安全。 (#33)
版本 1.0.3 (2011 年 6 月 14 日)
linkify() 与第三级域名兼容。 (#24)
clean() 支持样式值中的供应商前缀。 (#31, #32)
修复 linkify() 电子邮件转义。
版本 1.0.2 (2011 年 6 月 6 日)
linkify() 支持电子邮件地址。
clean() 在属性过滤器中支持可调用对象。
版本 1.0.1 (2011 年 4 月 12 日)
linkify() 不会丢弃尾随斜杠。 (#21)
linkify() 不会将 'libgl.so.1' 转换为链接。 (#22)
项目详情
下载文件
下载适用于您平台的文件。如果您不确定选择哪个,请了解更多关于 安装包 的信息。
源分布
构建分布
bleach-6.1.0.tar.gz 的哈希值
算法 | 哈希摘要 | |
---|---|---|
SHA256 | 0a31f1837963c41d46bbf1331b8778e1308ea0791db03cc4e7357b97cf42a8fe |
|
MD5 | fc95673643f4e0e81f443cb15fc15937 |
|
BLAKE2b-256 | 6d1077f32b088738f40d4f5be801daa5f327879eadd4562f36a2b5ab975ae571 |