sanitize 5.0.0 → 5.2.3
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of sanitize might be problematic. Click here for more details.
- checksums.yaml +4 -4
- data/HISTORY.md +111 -18
- data/README.md +60 -40
- data/lib/sanitize.rb +37 -19
- data/lib/sanitize/config/default.rb +5 -1
- data/lib/sanitize/config/relaxed.rb +1 -1
- data/lib/sanitize/css.rb +2 -2
- data/lib/sanitize/transformers/clean_comment.rb +1 -1
- data/lib/sanitize/transformers/clean_css.rb +3 -3
- data/lib/sanitize/transformers/clean_doctype.rb +1 -1
- data/lib/sanitize/transformers/clean_element.rb +17 -20
- data/lib/sanitize/version.rb +1 -1
- data/test/common.rb +0 -31
- data/test/test_clean_element.rb +40 -14
- data/test/test_malicious_html.rb +40 -6
- data/test/test_parser.rb +1 -1
- data/test/test_sanitize.rb +99 -14
- data/test/test_sanitize_css.rb +43 -16
- data/test/test_transformers.rb +25 -19
- metadata +10 -12
- data/test/test_unicode.rb +0 -95
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6ca971107ac89b0f3ce8523e5377c9f476d117a954c5a56af4b92dc926fc6ad8
|
4
|
+
data.tar.gz: ce25b03a97cd03958ec2a9698154a01b8b2b6f21e9e9bf3f118ba2bcee414f77
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0b6f4f1b6ea5bc243f6246d8490dfae58508058e7f16c3a78c12fd1b6edeee2a468e877f93bc7e2a868f6af151c2cf039ea1cc46e10b3404a7433bca3367b16b
|
7
|
+
data.tar.gz: 1abcace0d5409a63b815330b7e3533ac2e08b09a8a8dfef70d07296a898e51c7f9303d1f5218c55fe93651414f867f1bbc3725f87fbfe0acfa68910fbff7b399
|
data/HISTORY.md
CHANGED
@@ -1,5 +1,98 @@
|
|
1
1
|
# Sanitize History
|
2
2
|
|
3
|
+
## 5.2.3 (2021-01-11)
|
4
|
+
|
5
|
+
### Bug Fixes
|
6
|
+
|
7
|
+
* Ensure protocol sanitization is applied to data attributes.
|
8
|
+
[@ccutrer - #207][207]
|
9
|
+
|
10
|
+
[207]:https://github.com/rgrove/sanitize/pull/207
|
11
|
+
|
12
|
+
## 5.2.2 (2021-01-06)
|
13
|
+
|
14
|
+
### Bug Fixes
|
15
|
+
|
16
|
+
* Fixed a deprecation warning in Ruby 2.7+ when using keyword arguments in a
|
17
|
+
custom transformer. [@mscrivo - #206][206]
|
18
|
+
|
19
|
+
[206]:https://github.com/rgrove/sanitize/pull/206
|
20
|
+
|
21
|
+
## 5.2.1 (2020-06-16)
|
22
|
+
|
23
|
+
### Bug Fixes
|
24
|
+
|
25
|
+
* Fixed an HTML sanitization bypass that could allow XSS. This issue affects
|
26
|
+
Sanitize versions 3.0.0 through 5.2.0.
|
27
|
+
|
28
|
+
When HTML was sanitized using the "relaxed" config or a custom config that
|
29
|
+
allows certain elements, some content in a `<math>` or `<svg>` element may not
|
30
|
+
have beeen sanitized correctly even if `math` and `svg` were not in the
|
31
|
+
allowlist. This could allow carefully crafted input to sneak arbitrary HTML
|
32
|
+
through Sanitize, potentially enabling an XSS (cross-site scripting) attack.
|
33
|
+
|
34
|
+
You are likely to be vulnerable to this issue if you use Sanitize's relaxed
|
35
|
+
config or a custom config that allows one or more of the following HTML
|
36
|
+
elements:
|
37
|
+
|
38
|
+
- `iframe`
|
39
|
+
- `math`
|
40
|
+
- `noembed`
|
41
|
+
- `noframes`
|
42
|
+
- `noscript`
|
43
|
+
- `plaintext`
|
44
|
+
- `script`
|
45
|
+
- `style`
|
46
|
+
- `svg`
|
47
|
+
- `xmp`
|
48
|
+
|
49
|
+
See the security advisory for more details, including a workaround if you're
|
50
|
+
not able to upgrade: [GHSA-p4x4-rw2p-8j8m]
|
51
|
+
|
52
|
+
Many thanks to Michał Bentkowski of Securitum for reporting this issue and
|
53
|
+
helping to verify the fix.
|
54
|
+
|
55
|
+
[GHSA-p4x4-rw2p-8j8m]:https://github.com/rgrove/sanitize/security/advisories/GHSA-p4x4-rw2p-8j8m
|
56
|
+
|
57
|
+
## 5.2.0 (2020-06-06)
|
58
|
+
|
59
|
+
### Changes
|
60
|
+
|
61
|
+
* The term "whitelist" has been replaced with "allowlist" throughout Sanitize's
|
62
|
+
source and documentation.
|
63
|
+
|
64
|
+
While the etymology of "whitelist" may not be explicitly racist in origin or
|
65
|
+
intent, there are inherent racial connotations in the implication that white
|
66
|
+
is good and black (as in "blacklist") is not.
|
67
|
+
|
68
|
+
This is a change I should have made long ago, and I apologize for not making
|
69
|
+
it sooner.
|
70
|
+
|
71
|
+
* In transformer input, the `:is_whitelisted` and `:node_whitelist` keys are now
|
72
|
+
deprecated. New `:is_allowlisted` and `:node_allowlist` keys have been added.
|
73
|
+
The old keys will continue to work in order to avoid breaking existing code,
|
74
|
+
but they are no longer documented and may be removed in a future semver major
|
75
|
+
release.
|
76
|
+
|
77
|
+
## 5.1.0 (2019-09-07)
|
78
|
+
|
79
|
+
### Features
|
80
|
+
|
81
|
+
* Added a `:parser_options` config hash, which makes it possible to pass custom
|
82
|
+
parsing options to Nokogumbo. [@austin-wang - #194][194]
|
83
|
+
|
84
|
+
### Bug Fixes
|
85
|
+
|
86
|
+
* Non-characters and non-whitespace control characters are now stripped from
|
87
|
+
HTML input before parsing to comply with the HTML Standard's [preprocessing
|
88
|
+
guidelines][html-preprocessing]. Prior to this Sanitize had adhered to [older
|
89
|
+
W3C guidelines][unicode-xml] that have since been withdrawn. [#179][179]
|
90
|
+
|
91
|
+
[179]:https://github.com/rgrove/sanitize/issues/179
|
92
|
+
[194]:https://github.com/rgrove/sanitize/pull/194
|
93
|
+
[html-preprocessing]:https://html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream
|
94
|
+
[unicode-xml]:https://www.w3.org/TR/unicode-xml/
|
95
|
+
|
3
96
|
## 5.0.0 (2018-10-14)
|
4
97
|
|
5
98
|
For most users, upgrading from 4.x shouldn't require any changes. However, the
|
@@ -26,7 +119,7 @@ review the changes below carefully.
|
|
26
119
|
- `script`
|
27
120
|
- `style`
|
28
121
|
|
29
|
-
* Children of
|
122
|
+
* Children of allowlisted `iframe` elements are now always removed. In modern
|
30
123
|
HTML, `iframe` elements should never have children. In HTML 4 and earlier
|
31
124
|
`iframe` elements were allowed to contain fallback content for legacy
|
32
125
|
browsers, but it's been almost two decades since that was useful.
|
@@ -65,7 +158,7 @@ review the changes below carefully.
|
|
65
158
|
|
66
159
|
When Sanitize <= 4.6.2 is used in combination with libxml2 >= 2.9.2, a
|
67
160
|
specially crafted HTML fragment can cause libxml2 to generate improperly
|
68
|
-
escaped output, allowing non-
|
161
|
+
escaped output, allowing non-allowlisted attributes to be used on allowlisted
|
69
162
|
elements.
|
70
163
|
|
71
164
|
Sanitize now performs additional escaping on affected attributes to prevent
|
@@ -109,7 +202,7 @@ review the changes below carefully.
|
|
109
202
|
|
110
203
|
## 4.4.0 (2016-09-29)
|
111
204
|
|
112
|
-
* Added `srcset` to the attribute
|
205
|
+
* Added `srcset` to the attribute allowlist for `img` elements in the relaxed
|
113
206
|
config. [@ejtttje - #156][156]
|
114
207
|
|
115
208
|
[156]:https://github.com/rgrove/sanitize/pull/156
|
@@ -230,7 +323,7 @@ review the changes below carefully.
|
|
230
323
|
## 3.0.4 (2014-12-12)
|
231
324
|
|
232
325
|
* Fixed: Harmless whitespace preceding a URL protocol (such as " http://")
|
233
|
-
caused the URL to be removed even when the protocol was
|
326
|
+
caused the URL to be removed even when the protocol was allowlisted.
|
234
327
|
[@benubois - #126][126]
|
235
328
|
|
236
329
|
[126]:https://github.com/rgrove/sanitize/pull/126
|
@@ -239,7 +332,7 @@ review the changes below carefully.
|
|
239
332
|
## 3.0.3 (2014-10-29)
|
240
333
|
|
241
334
|
* Fixed: Some CSS selectors weren't parsed correctly inside the body of a
|
242
|
-
`@media` block, causing them to be removed even when
|
335
|
+
`@media` block, causing them to be removed even when allowlist rules should
|
243
336
|
have allowed them to remain. [#121][121]
|
244
337
|
|
245
338
|
[121]:https://github.com/rgrove/sanitize/issues/121
|
@@ -304,7 +397,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
304
397
|
* The `clean_node!` method was renamed to `node!`.
|
305
398
|
|
306
399
|
* The `document` method now raises a `Sanitize::Error` if the `<html>` element
|
307
|
-
isn't
|
400
|
+
isn't allowlisted, rather than a `RuntimeError`. This error is also now raised
|
308
401
|
regardless of the `:remove_contents` config setting.
|
309
402
|
|
310
403
|
* The `:output` config has been removed. Output is now always HTML, not XHTML.
|
@@ -315,7 +408,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
315
408
|
|
316
409
|
* Added advanced CSS sanitization support using [Crass][crass], which is fully
|
317
410
|
compliant with the CSS Syntax Module Level 3 parsing spec. The contents of
|
318
|
-
|
411
|
+
allowlisted `<style>` elements and `style` attributes in HTML will be
|
319
412
|
sanitized as CSS, or you can use the `Sanitize::CSS` class to manually
|
320
413
|
sanitize CSS stylesheets or properties.
|
321
414
|
|
@@ -367,7 +460,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
367
460
|
|
368
461
|
When Sanitize <= 2.1.0 is used in combination with libxml2 >= 2.9.2, a
|
369
462
|
specially crafted HTML fragment can cause libxml2 to generate improperly
|
370
|
-
escaped output, allowing non-
|
463
|
+
escaped output, allowing non-allowlisted attributes to be used on allowlisted
|
371
464
|
elements.
|
372
465
|
|
373
466
|
Sanitize now performs additional escaping on affected attributes to prevent
|
@@ -382,7 +475,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
382
475
|
|
383
476
|
## 2.1.0 (2014-01-13)
|
384
477
|
|
385
|
-
* Added support for
|
478
|
+
* Added support for allowlisting arbitrary HTML5 `data-*` attributes. Use the
|
386
479
|
symbol `:data` instead of an attribute name in the `:attributes` config to
|
387
480
|
indicate that arbitrary data attributes should be allowed on an element.
|
388
481
|
|
@@ -463,12 +556,12 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
463
556
|
the default depth-first mode.
|
464
557
|
|
465
558
|
* Added the `abbr`, `dfn`, `kbd`, `mark`, `s`, `samp`, `time`, and `var`
|
466
|
-
elements to the
|
559
|
+
elements to the allowlists for the basic and relaxed configs.
|
467
560
|
|
468
561
|
* Added the `bdo`, `del`, `figcaption`, `figure`, `hgroup`, `ins`, `rp`, `rt`,
|
469
|
-
`ruby`, and `wbr` elements to the
|
562
|
+
`ruby`, and `wbr` elements to the allowlist for the relaxed config.
|
470
563
|
|
471
|
-
* The `dir`, `lang`, and `title` attributes are now
|
564
|
+
* The `dir`, `lang`, and `title` attributes are now allowlisted for all
|
472
565
|
elements in the relaxed config.
|
473
566
|
|
474
567
|
* Bumped minimum Nokogiri version to 1.4.4 to avoid a bug in 1.4.2+
|
@@ -479,7 +572,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
479
572
|
## 1.2.1 (2010-04-20)
|
480
573
|
|
481
574
|
* Added a `:remove_contents` config setting. If set to `true`, Sanitize will
|
482
|
-
remove the contents of all non-
|
575
|
+
remove the contents of all non-allowlisted elements in addition to the
|
483
576
|
elements themselves. If set to an array of element names, Sanitize will
|
484
577
|
remove the contents of only those elements (when filtered), and leave the
|
485
578
|
contents of other filtered elements. [Thanks to Rafael Souza for the array
|
@@ -507,7 +600,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
507
600
|
* Added `Sanitize.clean_node!`, which sanitizes a `Nokogiri::XML::Node` and
|
508
601
|
all its children.
|
509
602
|
|
510
|
-
* Added elements `<h1>` through `<h6>` to the Relaxed
|
603
|
+
* Added elements `<h1>` through `<h6>` to the Relaxed allowlist. [Suggested by
|
511
604
|
David Reese]
|
512
605
|
|
513
606
|
|
@@ -527,7 +620,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
527
620
|
|
528
621
|
* Added a workaround for an Hpricot bug that prevents attribute names from
|
529
622
|
being downcased in recent versions of Hpricot. This was exploitable to
|
530
|
-
prevent non-
|
623
|
+
prevent non-allowlisted protocols from being cleaned. [Reported by Ben
|
531
624
|
Wanicur]
|
532
625
|
|
533
626
|
|
@@ -557,7 +650,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
557
650
|
|
558
651
|
## 1.0.5 (2009-02-05)
|
559
652
|
|
560
|
-
* Fixed a bug introduced in version 1.0.3 that prevented non-
|
653
|
+
* Fixed a bug introduced in version 1.0.3 that prevented non-allowlisted
|
561
654
|
protocols from being cleaned when relative URLs were allowed. [Reported by
|
562
655
|
Dev Purkayastha]
|
563
656
|
|
@@ -567,7 +660,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
567
660
|
|
568
661
|
## 1.0.4 (2009-01-16)
|
569
662
|
|
570
|
-
* Fixed a bug that made it possible to sneak a non-
|
663
|
+
* Fixed a bug that made it possible to sneak a non-allowlisted element through
|
571
664
|
by repeating it several times in a row. All versions of Sanitize prior to
|
572
665
|
1.0.4 are vulnerable. [Reported by Cristobal]
|
573
666
|
|
@@ -575,7 +668,7 @@ Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
|
575
668
|
## 1.0.3 (2009-01-15)
|
576
669
|
|
577
670
|
* Fixed a bug whereby incomplete Unicode or hex entities could be used to
|
578
|
-
prevent non-
|
671
|
+
prevent non-allowlisted protocols from being cleaned. Since IE6 and Opera
|
579
672
|
still decode the incomplete entities, users of those browsers may be
|
580
673
|
vulnerable to malicious script injection on websites using versions of
|
581
674
|
Sanitize prior to 1.0.3.
|
data/README.md
CHANGED
@@ -1,25 +1,24 @@
|
|
1
1
|
Sanitize
|
2
2
|
========
|
3
3
|
|
4
|
-
Sanitize is
|
5
|
-
elements, attributes, and
|
6
|
-
|
4
|
+
Sanitize is an allowlist-based HTML and CSS sanitizer. It removes all HTML
|
5
|
+
and/or CSS from a string except the elements, attributes, and properties you
|
6
|
+
choose to allow.
|
7
7
|
|
8
8
|
Using a simple configuration syntax, you can tell Sanitize to allow certain HTML
|
9
9
|
elements, certain attributes within those elements, and even certain URL
|
10
|
-
protocols within attributes that contain URLs. You can also
|
11
|
-
properties, @ rules, and URL protocols
|
12
|
-
|
13
|
-
be removed.
|
10
|
+
protocols within attributes that contain URLs. You can also allow specific CSS
|
11
|
+
properties, @ rules, and URL protocols in elements or attributes containing CSS.
|
12
|
+
Any HTML or CSS that you don't explicitly allow will be removed.
|
14
13
|
|
15
14
|
Sanitize is based on [Google's Gumbo HTML5 parser][gumbo], which parses HTML
|
16
15
|
exactly the same way modern browsers do, and [Crass][crass], which parses CSS
|
17
|
-
exactly the same way modern browsers do. As long as your
|
16
|
+
exactly the same way modern browsers do. As long as your allowlist config only
|
18
17
|
allows safe markup and CSS, even the most malformed or malicious input will be
|
19
18
|
transformed into safe output.
|
20
19
|
|
21
|
-
[![Build Status](https://travis-ci.org/rgrove/sanitize.svg?branch=master)](https://travis-ci.org/rgrove/sanitize)
|
22
20
|
[![Gem Version](https://badge.fury.io/rb/sanitize.svg)](http://badge.fury.io/rb/sanitize)
|
21
|
+
[![Tests](https://github.com/rgrove/sanitize/workflows/Tests/badge.svg)](https://github.com/rgrove/sanitize/actions?query=workflow%3ATests)
|
23
22
|
|
24
23
|
[crass]:https://github.com/rgrove/crass
|
25
24
|
[gumbo]:https://github.com/google/gumbo-parser
|
@@ -73,6 +72,11 @@ Sanitize can sanitize the following types of input:
|
|
73
72
|
* Standalone CSS stylesheets
|
74
73
|
* Standalone CSS properties
|
75
74
|
|
75
|
+
However, please note that Sanitize _cannot_ fully sanitize the contents of
|
76
|
+
`<math>` or `<svg>` elements, since these elements don't follow the same parsing
|
77
|
+
rules as the rest of HTML. If this is something you need, you may want to look
|
78
|
+
for another solution.
|
79
|
+
|
76
80
|
### HTML Fragments
|
77
81
|
|
78
82
|
A fragment is a snippet of HTML that doesn't contain a root-level `<html>`
|
@@ -88,7 +92,7 @@ Sanitize.fragment(html)
|
|
88
92
|
# => 'foo'
|
89
93
|
```
|
90
94
|
|
91
|
-
To keep certain elements, add them to the element
|
95
|
+
To keep certain elements, add them to the element allowlist.
|
92
96
|
|
93
97
|
```ruby
|
94
98
|
Sanitize.fragment(html, :elements => ['b'])
|
@@ -97,7 +101,7 @@ Sanitize.fragment(html, :elements => ['b'])
|
|
97
101
|
|
98
102
|
### HTML Documents
|
99
103
|
|
100
|
-
When sanitizing a document, the `<html>` element must be
|
104
|
+
When sanitizing a document, the `<html>` element must be allowlisted. You can
|
101
105
|
also set `:allow_doctype` to `true` to allow well-formed document type
|
102
106
|
definitions.
|
103
107
|
|
@@ -123,8 +127,8 @@ Sanitize.document(html,
|
|
123
127
|
|
124
128
|
### CSS in HTML
|
125
129
|
|
126
|
-
To sanitize CSS in an HTML fragment or document, first
|
127
|
-
element and/or the `style` attribute. Then
|
130
|
+
To sanitize CSS in an HTML fragment or document, first allowlist the `<style>`
|
131
|
+
element and/or the `style` attribute. Then allowlist the CSS properties,
|
128
132
|
@ rules, and URL protocols you wish to allow. You can also choose whether to
|
129
133
|
allow CSS comments or browser compatibility hacks.
|
130
134
|
|
@@ -267,7 +271,7 @@ new copy using `Sanitize::Config.merge()`, like so:
|
|
267
271
|
|
268
272
|
```ruby
|
269
273
|
# Create a customized copy of the Basic config, adding <div> and <table> to the
|
270
|
-
# existing
|
274
|
+
# existing allowlisted elements.
|
271
275
|
Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
|
272
276
|
:elements => Sanitize::Config::BASIC[:elements] + ['div', 'table'],
|
273
277
|
:remove_contents => true
|
@@ -395,8 +399,7 @@ Proc.new { |url| url.start_with?("https://fonts.googleapis.com") }
|
|
395
399
|
|
396
400
|
##### :css => :properties (Array or Set)
|
397
401
|
|
398
|
-
|
399
|
-
lowercase.
|
402
|
+
List of CSS property names to allow. Names should be specified in lowercase.
|
400
403
|
|
401
404
|
##### :css => :protocols (Array or Set)
|
402
405
|
|
@@ -417,6 +420,23 @@ elements not in this array will be removed.
|
|
417
420
|
]
|
418
421
|
```
|
419
422
|
|
423
|
+
**Warning:** Sanitize cannot fully sanitize the contents of `<math>` or `<svg>`
|
424
|
+
elements, since these elements don't follow the same parsing rules as the rest
|
425
|
+
of HTML. If you add `math` or `svg` to the allowlist, you must assume that any
|
426
|
+
content inside them will be allowed, even if that content would otherwise be
|
427
|
+
removed by Sanitize.
|
428
|
+
|
429
|
+
#### :parser_options (Hash)
|
430
|
+
|
431
|
+
[Parsing options](https://github.com/rubys/nokogumbo/tree/v2.0.1#parsing-options) supplied to `nokogumbo`.
|
432
|
+
|
433
|
+
```ruby
|
434
|
+
:parser_options => {
|
435
|
+
max_errors: -1,
|
436
|
+
max_tree_depth: -1
|
437
|
+
}
|
438
|
+
```
|
439
|
+
|
420
440
|
#### :protocols (Hash)
|
421
441
|
|
422
442
|
URL protocols to allow in specific attributes. If an attribute is listed here
|
@@ -441,7 +461,7 @@ include the symbol `:relative` in the protocol array:
|
|
441
461
|
|
442
462
|
#### :remove_contents (boolean or Array or Set)
|
443
463
|
|
444
|
-
If this is `true`, Sanitize will remove the contents of any non-
|
464
|
+
If this is `true`, Sanitize will remove the contents of any non-allowlisted
|
445
465
|
elements in addition to the elements themselves. By default, Sanitize leaves the
|
446
466
|
safe parts of an element's contents behind when the element is removed.
|
447
467
|
|
@@ -449,7 +469,7 @@ If this is an Array or Set of element names, then only the contents of the
|
|
449
469
|
specified elements (when filtered) will be removed, and the contents of all
|
450
470
|
other filtered elements will be left behind.
|
451
471
|
|
452
|
-
The default value is
|
472
|
+
The default value is `%w[iframe math noembed noframes noscript plaintext script style svg xmp]`.
|
453
473
|
|
454
474
|
#### :transformers (Array or callable)
|
455
475
|
|
@@ -507,33 +527,33 @@ argument a Hash that contains the following items:
|
|
507
527
|
|
508
528
|
* **:config** - The current Sanitize configuration Hash.
|
509
529
|
|
510
|
-
* **:
|
530
|
+
* **:is_allowlisted** - `true` if the current node has been allowlisted by a
|
511
531
|
previous transformer, `false` otherwise. It's generally bad form to remove
|
512
|
-
a node that a previous transformer has
|
532
|
+
a node that a previous transformer has allowlisted.
|
513
533
|
|
514
534
|
* **:node** - A `Nokogiri::XML::Node` object representing an HTML node. The
|
515
535
|
node may be an element, a text node, a comment, a CDATA node, or a document
|
516
536
|
fragment. Use Nokogiri's inspection methods (`element?`, `text?`, etc.) to
|
517
537
|
selectively ignore node types you aren't interested in.
|
518
538
|
|
539
|
+
* **:node_allowlist** - Set of `Nokogiri::XML::Node` objects in the current
|
540
|
+
document that have been allowlisted by previous transformers, if any. It's
|
541
|
+
generally bad form to remove a node that a previous transformer has
|
542
|
+
allowlisted.
|
543
|
+
|
519
544
|
* **:node_name** - The name of the current HTML node, always lowercase (e.g.
|
520
545
|
"div" or "span"). For non-element nodes, the name will be something like
|
521
546
|
"text", "comment", "#cdata-section", "#document-fragment", etc.
|
522
547
|
|
523
|
-
* **:node_whitelist** - Set of `Nokogiri::XML::Node` objects in the current
|
524
|
-
document that have been whitelisted by previous transformers, if any. It's
|
525
|
-
generally bad form to remove a node that a previous transformer has
|
526
|
-
whitelisted.
|
527
|
-
|
528
548
|
### Output
|
529
549
|
|
530
550
|
A transformer doesn't have to return anything, but may optionally return a Hash,
|
531
551
|
which may contain the following items:
|
532
552
|
|
533
|
-
* **:
|
534
|
-
to add to the document's
|
535
|
-
These specific nodes and all their attributes will be
|
536
|
-
their children will not be.
|
553
|
+
* **:node_allowlist** - Array or Set of specific `Nokogiri::XML::Node`
|
554
|
+
objects to add to the document's allowlist, bypassing the current Sanitize
|
555
|
+
config. These specific nodes and all their attributes will be allowlisted,
|
556
|
+
but their children will not be.
|
537
557
|
|
538
558
|
If a transformer returns anything other than a Hash, the return value will be
|
539
559
|
ignored.
|
@@ -576,16 +596,16 @@ Transformers have a tremendous amount of power, including the power to
|
|
576
596
|
completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
|
577
597
|
your own hands.
|
578
598
|
|
579
|
-
### Example: Transformer to
|
599
|
+
### Example: Transformer to allow image URLs by domain
|
580
600
|
|
581
601
|
The following example demonstrates how to remove image elements unless they use
|
582
602
|
a relative URL or are hosted on a specific domain. It assumes that the `<img>`
|
583
|
-
element and its `src` attribute are already
|
603
|
+
element and its `src` attribute are already allowlisted.
|
584
604
|
|
585
605
|
```ruby
|
586
606
|
require 'uri'
|
587
607
|
|
588
|
-
|
608
|
+
image_allowlist_transformer = lambda do |env|
|
589
609
|
# Ignore everything except <img> elements.
|
590
610
|
return unless env[:node_name] == 'img'
|
591
611
|
|
@@ -601,20 +621,20 @@ image_whitelist_transformer = lambda do |env|
|
|
601
621
|
end
|
602
622
|
```
|
603
623
|
|
604
|
-
### Example: Transformer to
|
624
|
+
### Example: Transformer to allow YouTube video embeds
|
605
625
|
|
606
626
|
The following example demonstrates how to create a transformer that will safely
|
607
|
-
|
608
|
-
|
609
|
-
|
627
|
+
allow valid YouTube video embeds without having to allow other kinds of embedded
|
628
|
+
content, which would be the case if you tried to do this by just allowing all
|
629
|
+
`<iframe>` elements:
|
610
630
|
|
611
631
|
```ruby
|
612
632
|
youtube_transformer = lambda do |env|
|
613
633
|
node = env[:node]
|
614
634
|
node_name = env[:node_name]
|
615
635
|
|
616
|
-
# Don't continue if this node is already
|
617
|
-
return if env[:
|
636
|
+
# Don't continue if this node is already allowlisted or is not an element.
|
637
|
+
return if env[:is_allowlisted] || !node.element?
|
618
638
|
|
619
639
|
# Don't continue unless the node is an iframe.
|
620
640
|
return unless node_name == 'iframe'
|
@@ -635,8 +655,8 @@ youtube_transformer = lambda do |env|
|
|
635
655
|
|
636
656
|
# Now that we're sure that this is a valid YouTube embed and that there are
|
637
657
|
# no unwanted elements or attributes hidden inside it, we can tell Sanitize
|
638
|
-
# to
|
639
|
-
{:
|
658
|
+
# to allowlist the current node.
|
659
|
+
{:node_allowlist => [node]}
|
640
660
|
end
|
641
661
|
|
642
662
|
html = %[
|