loofah 2.10.0 → 2.21.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +139 -0
- data/README.md +107 -114
- data/lib/loofah/concerns.rb +207 -0
- data/lib/loofah/elements.rb +83 -78
- data/lib/loofah/helpers.rb +21 -15
- data/lib/loofah/{html → html4}/document.rb +5 -7
- data/lib/loofah/html4/document_fragment.rb +15 -0
- data/lib/loofah/html5/document.rb +17 -0
- data/lib/loofah/html5/document_fragment.rb +15 -0
- data/lib/loofah/html5/libxml2_workarounds.rb +7 -6
- data/lib/loofah/html5/safelist.rb +949 -715
- data/lib/loofah/html5/scrub.rb +104 -31
- data/lib/loofah/metahelpers.rb +10 -6
- data/lib/loofah/scrubber.rb +14 -8
- data/lib/loofah/scrubbers.rb +59 -49
- data/lib/loofah/version.rb +2 -1
- data/lib/loofah/xml/document.rb +1 -0
- data/lib/loofah/xml/document_fragment.rb +2 -6
- data/lib/loofah.rb +116 -43
- metadata +19 -135
- data/lib/loofah/html/document_fragment.rb +0 -42
- data/lib/loofah/instance_methods.rb +0 -129
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: '00569b28a0bc6307a0a8eb8704ad374f10269008dada5d09470c1a2a87da0a6f'
|
4
|
+
data.tar.gz: eff12a44f1152dc377ac0a6859be97f85b5a0a031a0b7688387c73f7130351d3
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fbcf412c0105203fe3d9ee057dc146cc7f8e9f29587c0f97b9c03a5206eacd31f7170042c74050d40093875b8109f524434a0960ef9305269fdda536e3049e3b
|
7
|
+
data.tar.gz: 48c3f2c0f4a0b2316c46ad1826c61ded9c3438ace28c477d7b67cc345847a00bb5747bab5b22cf5d774e82c90bedd085a9878c40609f93abda49f6aa01257f7c
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,144 @@
|
|
1
1
|
# Changelog
|
2
2
|
|
3
|
+
## 2.21.3 / 2023-05-15
|
4
|
+
|
5
|
+
* Quash "instance variable not initialized" warning in Ruby < 3.0. [[#268](https://github.com/flavorjones/loofah/issues/268)] (Thanks, [@dharamgollapudi](https://github.com/dharamgollapudi)!)
|
6
|
+
|
7
|
+
|
8
|
+
## 2.21.2 / 2023-05-11
|
9
|
+
|
10
|
+
### Dependencies
|
11
|
+
|
12
|
+
* Update the dependency on Nokogiri to be `>= 1.12.0`. The dependency in 2.21.0 and 2.21.1 was left at `>= 1.5.9` but versions before 1.12 would result in a `NameError` exception. [[#266](https://github.com/flavorjones/loofah/issues/266)]
|
13
|
+
|
14
|
+
|
15
|
+
## 2.21.1 / 2023-05-10
|
16
|
+
|
17
|
+
### Fixed
|
18
|
+
|
19
|
+
* Don't define `HTML5::Document` and `HTML5::DocumentFragment` when Nokogiri is `< 1.14`. In 2.21.0 these classes were defined whenever `Nokogiri::HTML5` was defined, but Nokogiri v1.12 and v1.13 do not support Loofah subclassing properly.
|
20
|
+
|
21
|
+
|
22
|
+
## 2.21.0 / 2023-05-10
|
23
|
+
|
24
|
+
### HTML5 Support
|
25
|
+
|
26
|
+
Classes `Loofah::HTML5::Document` and `Loofah::HTML5::DocumentFragment` are introduced, along with helper methods:
|
27
|
+
|
28
|
+
- `Loofah.html5_document`
|
29
|
+
- `Loofah.html5_fragment`
|
30
|
+
- `Loofah.scrub_html5_document`
|
31
|
+
- `Loofah.scrub_html5_fragment`
|
32
|
+
|
33
|
+
These classes and methods use Nokogiri's HTML5 parser to ensure modern web standards are used.
|
34
|
+
|
35
|
+
⚠ HTML5 functionality is only available with Nokogiri v1.14.0 and higher.
|
36
|
+
|
37
|
+
⚠ HTML5 functionality is not available for JRuby. Please see [this upstream Nokogiri issue](https://github.com/sparklemotion/nokogiri/issues/2227) if you're interested in helping implement and support HTML5 support.
|
38
|
+
|
39
|
+
|
40
|
+
### `Loofah::HTML4` module and namespace
|
41
|
+
|
42
|
+
`Loofah::HTML` has been renamed to `Loofah::HTML4`, and `Loofah::HTML` is aliased to preserve backwards-compatibility. `Nokogiri::HTML` and `Nokogiri::HTML4` parse methods still use libxml2's (or NekoHTML's) HTML4 parser.
|
43
|
+
|
44
|
+
Take special note that if you rely on the class name of an object in your code, objects will now report a class of `Loofah::HTML4::Foo` where they previously reported `Loofah::HTML::Foo`. Instead of relying on the string returned by `Object#class`, prefer `Class#===` or `Object#is_a?` or `Object#instance_of?`.
|
45
|
+
|
46
|
+
Future releases of Nokogiri may deprecate `HTML` classes and methods or otherwise change this behavior, so please start using `HTML4` in place of `HTML`.
|
47
|
+
|
48
|
+
|
49
|
+
### Official support for JRuby
|
50
|
+
|
51
|
+
This version introduces official support for JRuby. Previously, the test suite had never been green due to differences in behavior in the underlying HTML parser used by Nokogiri. We've updated the test suite to accommodate those differences, and have added JRuby to the CI suite.
|
52
|
+
|
53
|
+
|
54
|
+
## 2.20.0 / 2023-04-01
|
55
|
+
|
56
|
+
### Features
|
57
|
+
|
58
|
+
* Allow SVG attributes `color-profile`, `cursor`, `filter`, `marker`, and `mask`. [[#246](https://github.com/flavorjones/loofah/issues/246)]
|
59
|
+
* Allow SVG elements `altGlyph`, `cursor`, `feImage`, `pattern`, and `tref`. [[#246](https://github.com/flavorjones/loofah/issues/246)]
|
60
|
+
* Allow protocols `fax` and `modem`. [[#255](https://github.com/flavorjones/loofah/issues/255)] (Thanks, [@cjba7](https://github.com/cjba7)!)
|
61
|
+
|
62
|
+
|
63
|
+
## 2.19.1 / 2022-12-13
|
64
|
+
|
65
|
+
### Security
|
66
|
+
|
67
|
+
* Address CVE-2022-23514, inefficient regular expression complexity. See [GHSA-486f-hjj9-9vhh](https://github.com/flavorjones/loofah/security/advisories/GHSA-486f-hjj9-9vhh) for more information.
|
68
|
+
* Address CVE-2022-23515, improper neutralization of data URIs. See [GHSA-228g-948r-83gx](https://github.com/flavorjones/loofah/security/advisories/GHSA-228g-948r-83gx) for more information.
|
69
|
+
* Address CVE-2022-23516, uncontrolled recursion. See [GHSA-3x8r-x6xp-q4vm](https://github.com/flavorjones/loofah/security/advisories/GHSA-3x8r-x6xp-q4vm) for more information.
|
70
|
+
|
71
|
+
|
72
|
+
## 2.19.0 / 2022-09-14
|
73
|
+
|
74
|
+
### Features
|
75
|
+
|
76
|
+
* Allow SVG 1.0 color keyword names in CSS attributes. These colors are part of the [CSS Color Module Level 3](https://www.w3.org/TR/css-color-3/#svg-color) recommendation released 2022-01-18. [[#243](https://github.com/flavorjones/loofah/issues/243)]
|
77
|
+
|
78
|
+
|
79
|
+
## 2.18.0 / 2022-05-11
|
80
|
+
|
81
|
+
### Features
|
82
|
+
|
83
|
+
* Allow CSS property `aspect-ratio`. [[#236](https://github.com/flavorjones/loofah/issues/236)] (Thanks, [@louim](https://github.com/louim)!)
|
84
|
+
|
85
|
+
|
86
|
+
## 2.17.0 / 2022-04-28
|
87
|
+
|
88
|
+
### Features
|
89
|
+
|
90
|
+
* Allow ARIA attributes. [[#232](https://github.com/flavorjones/loofah/issues/232), [#233](https://github.com/flavorjones/loofah/issues/233)] (Thanks, [@nick-desteffen](https://github.com/nick-desteffen)!)
|
91
|
+
|
92
|
+
|
93
|
+
## 2.16.0 / 2022-04-01
|
94
|
+
|
95
|
+
### Features
|
96
|
+
|
97
|
+
* Allow MathML elements `menclose` and `ms`, and MathML attributes `dir`, `href`, `lquote`, `mathsize`, `notation`, and `rquote`. [[#231](https://github.com/flavorjones/loofah/issues/231)] (Thanks, [@nick-desteffen](https://github.com/nick-desteffen)!)
|
98
|
+
|
99
|
+
|
100
|
+
## 2.15.0 / 2022-03-14
|
101
|
+
|
102
|
+
### Features
|
103
|
+
|
104
|
+
* Expand set of allowed protocols to include `sms:`. [[#228](https://github.com/flavorjones/loofah/issues/228)] (Thanks, [@brendon](https://github.com/brendon)!)
|
105
|
+
|
106
|
+
|
107
|
+
## 2.14.0 / 2022-02-11
|
108
|
+
|
109
|
+
### Features
|
110
|
+
|
111
|
+
* The `#to_text` method on `Loofah::HTML::{Document,DocumentFragment}` replaces `<br>` line break elements with a newline. [[#225](https://github.com/flavorjones/loofah/issues/225)]
|
112
|
+
|
113
|
+
|
114
|
+
## 2.13.0 / 2021-12-10
|
115
|
+
|
116
|
+
### Bug fixes
|
117
|
+
|
118
|
+
* Loofah::HTML::DocumentFragment#text no longer serializes top-level comment children. [[#221](https://github.com/flavorjones/loofah/issues/221)]
|
119
|
+
|
120
|
+
|
121
|
+
## 2.12.0 / 2021-08-11
|
122
|
+
|
123
|
+
### Features
|
124
|
+
|
125
|
+
* Support empty HTML5 data attributes. [[#215](https://github.com/flavorjones/loofah/issues/215)]
|
126
|
+
|
127
|
+
|
128
|
+
## 2.11.0 / 2021-07-31
|
129
|
+
|
130
|
+
### Features
|
131
|
+
|
132
|
+
* Allow HTML5 element `wbr`.
|
133
|
+
* Allow all CSS property values for `border-collapse`. [[#201](https://github.com/flavorjones/loofah/issues/201)]
|
134
|
+
|
135
|
+
|
136
|
+
### Changes
|
137
|
+
|
138
|
+
* Deprecating `Loofah::HTML5::SafeList::VOID_ELEMENTS` which is not a canonical list of void HTML4 or HTML5 elements.
|
139
|
+
* Removed some elements from `Loofah::HTML5::SafeList::VOID_ELEMENTS` that either are not acceptable elements or aren't considered "void" by libxml2.
|
140
|
+
|
141
|
+
|
3
142
|
## 2.10.0 / 2021-06-06
|
4
143
|
|
5
144
|
### Features
|
data/README.md
CHANGED
@@ -6,8 +6,7 @@
|
|
6
6
|
|
7
7
|
## Status
|
8
8
|
|
9
|
-
[![
|
10
|
-
[![Code Climate](https://codeclimate.com/github/flavorjones/loofah.svg)](https://codeclimate.com/github/flavorjones/loofah)
|
9
|
+
[![ci](https://github.com/flavorjones/loofah/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/flavorjones/loofah/actions/workflows/ci.yml)
|
11
10
|
[![Tidelift dependencies](https://tidelift.com/badges/package/rubygems/loofah)](https://tidelift.com/subscription/pkg/rubygems-loofah?utm_source=rubygems-loofah&utm_medium=referral&utm_campaign=readme)
|
12
11
|
|
13
12
|
|
@@ -15,59 +14,61 @@
|
|
15
14
|
|
16
15
|
Loofah is a general library for manipulating and transforming HTML/XML documents and fragments, built on top of Nokogiri.
|
17
16
|
|
18
|
-
Loofah
|
17
|
+
Loofah also includes some HTML sanitizers based on `html5lib`'s safelist, which are a specific application of the general transformation functionality.
|
19
18
|
|
20
|
-
|
19
|
+
Active Record extensions for HTML sanitization are available in the [`loofah-activerecord` gem](https://github.com/flavorjones/loofah-activerecord).
|
21
20
|
|
22
21
|
|
23
22
|
## Features
|
24
23
|
|
25
|
-
* Easily write custom
|
26
|
-
* Common HTML sanitizing
|
24
|
+
* Easily write custom transformations for HTML and XML
|
25
|
+
* Common HTML sanitizing transformations are built-in:
|
27
26
|
* _Strip_ unsafe tags, leaving behind only the inner text.
|
28
27
|
* _Prune_ unsafe tags and their subtrees, removing all traces that they ever existed.
|
29
28
|
* _Escape_ unsafe tags and their subtrees, leaving behind lots of <tt><</tt> and <tt>></tt> entities.
|
30
29
|
* _Whitewash_ the markup, removing all attributes and namespaced nodes.
|
31
|
-
*
|
30
|
+
* Other common HTML transformations are built-in:
|
32
31
|
* Add the _nofollow_ attribute to all hyperlinks.
|
33
|
-
*
|
32
|
+
* Remove _unprintable_ characters from text nodes.
|
33
|
+
* Format markup as plain text, with (or without) sensible whitespace handling around block elements.
|
34
34
|
* Replace Rails's `strip_tags` and `sanitize` view helper methods.
|
35
35
|
|
36
36
|
|
37
37
|
## Compare and Contrast
|
38
38
|
|
39
|
-
Loofah is
|
40
|
-
guarantees well-formed and valid markup (the other is Sanitize, which
|
41
|
-
also uses Nokogiri).
|
39
|
+
Loofah is both:
|
42
40
|
|
43
|
-
|
41
|
+
- a general framework for transforming XML, XHTML, and HTML documents
|
42
|
+
- a specific toolkit for HTML sanitization
|
44
43
|
|
45
|
-
|
46
|
-
commonly-used libraries (ActionView, Sanitize, HTML5lib and HTMLfilter):
|
44
|
+
### General document transformation
|
47
45
|
|
48
|
-
|
46
|
+
Loofah tries to make it easy to write your own custom scrubbers for whatever document transformation you need. You don't like the built-in scrubbers? Build your own, like a boss.
|
49
47
|
|
50
|
-
|
51
|
-
|
52
|
-
|
48
|
+
|
49
|
+
### HTML sanitization
|
50
|
+
|
51
|
+
Another Ruby library that provides HTML sanitization is [`rgrove/sanitize`](https://github.com/rgrove/sanitize), another library built on top of Nokogiri, which provides a bit more flexibility on the tags and attributes being scrubbed.
|
52
|
+
|
53
|
+
You may also want to look at [`rails/rails-html-sanitizer`](https://github.com/rails/rails-html-sanitizer) which is built on top of Loofah and provides some useful extensions and additional flexibility in the HTML sanitization.
|
53
54
|
|
54
55
|
|
55
56
|
## The Basics
|
56
57
|
|
57
|
-
Loofah wraps [Nokogiri](http://nokogiri.org) in a loving
|
58
|
-
embrace. Nokogiri is an excellent HTML/XML parser. If you don't know
|
59
|
-
how Nokogiri works, you might want to pause for a moment and go check
|
60
|
-
it out. I'll wait.
|
58
|
+
Loofah wraps [Nokogiri](http://nokogiri.org) in a loving embrace. Nokogiri is a stable, well-maintained parser for XML, HTML4, and HTML5.
|
61
59
|
|
62
|
-
Loofah
|
60
|
+
Loofah implements the following classes:
|
63
61
|
|
64
|
-
* `Loofah::
|
65
|
-
* `Loofah::
|
66
|
-
* `Loofah::
|
62
|
+
* `Loofah::HTML5::Document`
|
63
|
+
* `Loofah::HTML5::DocumentFragment`
|
64
|
+
* `Loofah::HTML4::Document` (aliased as `Loofah::HTML::Document` for now)
|
65
|
+
* `Loofah::HTML4::DocumentFragment` (aliased as `Loofah::HTML::DocumentFragment` for now)
|
66
|
+
* `Loofah::XML::Document`
|
67
|
+
* `Loofah::XML::DocumentFragment`
|
67
68
|
|
68
|
-
|
69
|
+
These document and fragment classes are subclasses of the similarly-named Nokogiri classes `Nokogiri::HTML5::Document` et al.
|
69
70
|
|
70
|
-
|
71
|
+
Loofah also implements `Loofah::Scrubber`, which represents the document transformation, either by wrapping
|
71
72
|
a block,
|
72
73
|
|
73
74
|
``` ruby
|
@@ -81,50 +82,49 @@ or by implementing a method.
|
|
81
82
|
|
82
83
|
### Side Note: Fragments vs Documents
|
83
84
|
|
84
|
-
Generally speaking, unless you expect to have a DOCTYPE and a single
|
85
|
-
|
86
|
-
HTML
|
87
|
-
|
85
|
+
Generally speaking, unless you expect to have a DOCTYPE and a single root node, you don't have a *document*, you have a *fragment*. For HTML, another rule of thumb is that *documents* have `html` and `body` tags, and *fragments* usually do not.
|
86
|
+
|
87
|
+
**HTML fragments** should be parsed with `Loofah.html5_fragment` or `Loofah.html4_fragment`. The result won't be wrapped in `html` or `body` tags, won't have a DOCTYPE declaration, `head` elements will be silently ignored, and multiple root nodes are allowed.
|
88
|
+
|
89
|
+
**HTML documents** should be parsed with `Loofah.html5_document` or `Loofah.html4_document`. The result will have a DOCTYPE declaration, along with `html`, `head` and `body` tags.
|
90
|
+
|
91
|
+
**XML fragments** should be parsed with `Loofah.xml_fragment`. The result won't have a DOCTYPE declaration, and multiple root nodes are allowed.
|
92
|
+
|
93
|
+
**XML documents** should be parsed with `Loofah.xml_document`. The result will have a DOCTYPE declaration and a single root node.
|
88
94
|
|
89
|
-
HTML fragments should be parsed with Loofah.fragment. The result won't
|
90
|
-
be wrapped in `html` or `body` tags, won't have a DOCTYPE declaration,
|
91
|
-
`head` elements will be silently ignored, and multiple root nodes are
|
92
|
-
allowed.
|
93
95
|
|
94
|
-
|
95
|
-
won't have a DOCTYPE declaration, and multiple root nodes are allowed.
|
96
|
+
### Side Note: HTML4 vs HTML5
|
96
97
|
|
97
|
-
|
98
|
-
have a DOCTYPE declaration, along with `html`, `head` and `body` tags.
|
98
|
+
⚠ _HTML5 functionality is not available on JRuby, or with versions of Nokogiri `< 1.14.0`._
|
99
99
|
|
100
|
-
|
101
|
-
will have a DOCTYPE declaration and a single root node.
|
100
|
+
Currently, Loofah's methods `Loofah.document` and `Loofah.fragment` are aliases to `.html4_document` and `.html4_fragment`, which use Nokogiri's HTML4 parser. (Similarly, `Loofah::HTML::Document` and `Loofah::HTML::DocumentFragment` are aliased to `Loofah::HTML4::Document` and `Loofah::HTML4::DocumentFragment`.)
|
102
101
|
|
102
|
+
**Please note** that in a future version of Loofah, these methods and classes may switch to using Nokogiri's HTML5 parser and classes on platforms that support it [1].
|
103
103
|
|
104
|
-
|
104
|
+
**We strongly recommend that you explicitly use `.html5_document` or `.html5_fragment`** unless you know of a compelling reason not to. If you are sure that you need to use the HTML4 parser, you should explicitly call `.html4_document` or `.html4_fragment` to avoid breakage in a future version.
|
105
105
|
|
106
|
-
|
107
|
-
Nokogiri::HTML::DocumentFragment, so you get all the markup
|
108
|
-
fixer-uppery and API goodness of Nokogiri.
|
106
|
+
[1]: [[feature request] HTML5 parser for JRuby implementation · Issue #2227 · sparklemotion/nokogiri](https://github.com/sparklemotion/nokogiri/issues/2227)
|
109
107
|
|
110
|
-
|
111
|
-
|
108
|
+
|
109
|
+
### `Loofah::HTML5::Document` and `Loofah::HTML5::DocumentFragment`
|
110
|
+
|
111
|
+
These classes are subclasses of `Nokogiri::HTML5::Document` and `Nokogiri::HTML5::DocumentFragment`.
|
112
|
+
|
113
|
+
The module methods `Loofah.html5_document` and `Loofah.html5_fragment` will parse either an HTML document and an HTML fragment, respectively.
|
112
114
|
|
113
115
|
``` ruby
|
114
|
-
Loofah.
|
115
|
-
Loofah.
|
116
|
+
Loofah.html5_document(unsafe_html).is_a?(Nokogiri::HTML5::Document) # => true
|
117
|
+
Loofah.html5_fragment(unsafe_html).is_a?(Nokogiri::HTML5::DocumentFragment) # => true
|
116
118
|
```
|
117
119
|
|
118
|
-
Loofah injects a `scrub!` method, which takes either a symbol (for
|
119
|
-
built-in scrubbers) or a Loofah::Scrubber object (for custom
|
120
|
-
scrubbers), and modifies the document in-place.
|
120
|
+
Loofah injects a `scrub!` method, which takes either a symbol (for built-in scrubbers) or a `Loofah::Scrubber` object (for custom scrubbers), and modifies the document in-place.
|
121
121
|
|
122
122
|
Loofah overrides `to_s` to return HTML:
|
123
123
|
|
124
124
|
``` ruby
|
125
125
|
unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"
|
126
126
|
|
127
|
-
doc = Loofah.
|
127
|
+
doc = Loofah.html5_fragment(unsafe_html).scrub!(:prune)
|
128
128
|
doc.to_s # => "ohai! <div>div is safe</div> "
|
129
129
|
```
|
130
130
|
|
@@ -134,36 +134,41 @@ and `text` to return plain text:
|
|
134
134
|
doc.text # => "ohai! div is safe "
|
135
135
|
```
|
136
136
|
|
137
|
-
Also, `to_text` is available, which does the right thing with
|
138
|
-
|
137
|
+
Also, `to_text` is available, which does the right thing with whitespace around block-level and line break elements.
|
138
|
+
|
139
|
+
``` ruby
|
140
|
+
doc = Loofah.html5_fragment("<h1>Title</h1><div>Content<br>Next line</div>")
|
141
|
+
doc.text # => "TitleContentNext line" # probably not what you want
|
142
|
+
doc.to_text # => "\nTitle\n\nContent\nNext line\n" # better
|
143
|
+
```
|
144
|
+
|
145
|
+
### `Loofah::HTML4::Document` and `Loofah::HTML4::DocumentFragment`
|
146
|
+
|
147
|
+
These classes are subclasses of `Nokogiri::HTML4::Document` and `Nokogiri::HTML4::DocumentFragment`.
|
148
|
+
|
149
|
+
The module methods `Loofah.html4_document` and `Loofah.html4_fragment` will parse either an HTML document and an HTML fragment, respectively.
|
139
150
|
|
140
151
|
``` ruby
|
141
|
-
|
142
|
-
|
143
|
-
doc.to_text # => "\nTitle\n\nContent\n" # better
|
152
|
+
Loofah.html4_document(unsafe_html).is_a?(Nokogiri::HTML4::Document) # => true
|
153
|
+
Loofah.html4_fragment(unsafe_html).is_a?(Nokogiri::HTML4::DocumentFragment) # => true
|
144
154
|
```
|
145
155
|
|
146
|
-
### Loofah::XML::Document and Loofah::XML::DocumentFragment
|
156
|
+
### `Loofah::XML::Document` and `Loofah::XML::DocumentFragment`
|
147
157
|
|
148
|
-
These classes are subclasses of Nokogiri::XML::Document and
|
149
|
-
Nokogiri::XML::DocumentFragment, so you get all the markup
|
150
|
-
fixer-uppery and API goodness of Nokogiri.
|
158
|
+
These classes are subclasses of `Nokogiri::XML::Document` and `Nokogiri::XML::DocumentFragment`.
|
151
159
|
|
152
|
-
The module methods Loofah.xml_document and Loofah.xml_fragment will
|
153
|
-
parse an XML document and an XML fragment, respectively.
|
160
|
+
The module methods `Loofah.xml_document` and `Loofah.xml_fragment` will parse an XML document and an XML fragment, respectively.
|
154
161
|
|
155
162
|
``` ruby
|
156
163
|
Loofah.xml_document(bad_xml).is_a?(Nokogiri::XML::Document) # => true
|
157
164
|
Loofah.xml_fragment(bad_xml).is_a?(Nokogiri::XML::DocumentFragment) # => true
|
158
165
|
```
|
159
166
|
|
160
|
-
### Nodes and
|
167
|
+
### Nodes and Node Sets
|
161
168
|
|
162
|
-
Nokogiri
|
163
|
-
method, which makes it easy to scrub subtrees.
|
169
|
+
Nokogiri's `Node` and `NodeSet` classes also get a `scrub!` method, which makes it easy to scrub subtrees.
|
164
170
|
|
165
|
-
The following code will apply the `employee_scrubber` only to the
|
166
|
-
`employee` nodes (and their subtrees) in the document:
|
171
|
+
The following code will apply the `employee_scrubber` only to the `employee` nodes (and their subtrees) in the document:
|
167
172
|
|
168
173
|
``` ruby
|
169
174
|
Loofah.xml_document(bad_xml).xpath("//employee").scrub!(employee_scrubber)
|
@@ -175,7 +180,7 @@ And this code will only scrub the first `employee` node and its subtree:
|
|
175
180
|
Loofah.xml_document(bad_xml).at_xpath("//employee").scrub!(employee_scrubber)
|
176
181
|
```
|
177
182
|
|
178
|
-
### Loofah::Scrubber
|
183
|
+
### `Loofah::Scrubber`
|
179
184
|
|
180
185
|
A Scrubber wraps up a block (or method) that is run on a document node:
|
181
186
|
|
@@ -189,14 +194,11 @@ end
|
|
189
194
|
This can then be run on a document:
|
190
195
|
|
191
196
|
``` ruby
|
192
|
-
Loofah.
|
197
|
+
Loofah.html5_fragment("<span>foo</span><p>bar</p>").scrub!(span2div).to_s
|
193
198
|
# => "<div>foo</div><p>bar</p>"
|
194
199
|
```
|
195
200
|
|
196
|
-
Scrubbers can be run on a document in either a top-down traversal (the
|
197
|
-
default) or bottom-up. Top-down scrubbers can optionally return
|
198
|
-
Scrubber::STOP to terminate the traversal of a subtree. Read below and
|
199
|
-
in the Loofah::Scrubber class for more detailed usage.
|
201
|
+
Scrubbers can be run on a document in either a top-down traversal (the default) or bottom-up. Top-down scrubbers can optionally return `Scrubber::STOP` to terminate the traversal of a subtree. Read below and in the `Loofah::Scrubber` class for more detailed usage.
|
200
202
|
|
201
203
|
Here's an XML example:
|
202
204
|
|
@@ -213,10 +215,10 @@ Loofah.xml_document(File.read('plague.xml')).scrub!(bring_out_your_dead)
|
|
213
215
|
|
214
216
|
### Built-In HTML Scrubbers
|
215
217
|
|
216
|
-
Loofah comes with a set of sanitizing scrubbers that use
|
217
|
-
safelist algorithm:
|
218
|
+
Loofah comes with a set of sanitizing scrubbers that use `html5lib`'s safelist algorithm:
|
218
219
|
|
219
220
|
``` ruby
|
221
|
+
doc = Loofah.html5_document(input)
|
220
222
|
doc.scrub!(:strip) # replaces unknown/unsafe tags with their inner text
|
221
223
|
doc.scrub!(:prune) # removes unknown/unsafe tags and their children
|
222
224
|
doc.scrub!(:escape) # escapes unknown/unsafe tags, like this: <script>
|
@@ -224,14 +226,14 @@ doc.scrub!(:whitewash) # removes unknown/unsafe/namespaced tags and their chi
|
|
224
226
|
# and strips all node attributes
|
225
227
|
```
|
226
228
|
|
227
|
-
Loofah also comes with some common transformation tasks:
|
229
|
+
Loofah also comes with some common transformation tasks:
|
228
230
|
|
229
231
|
``` ruby
|
230
232
|
doc.scrub!(:nofollow) # adds rel="nofollow" attribute to links
|
231
233
|
doc.scrub!(:unprintable) # removes unprintable characters from text nodes
|
232
234
|
```
|
233
235
|
|
234
|
-
See Loofah::Scrubbers for more details and example usage.
|
236
|
+
See `Loofah::Scrubbers` for more details and example usage.
|
235
237
|
|
236
238
|
|
237
239
|
### Chaining Scrubbers
|
@@ -239,7 +241,7 @@ See Loofah::Scrubbers for more details and example usage.
|
|
239
241
|
You can chain scrubbers:
|
240
242
|
|
241
243
|
``` ruby
|
242
|
-
Loofah.
|
244
|
+
Loofah.html5_fragment("<span>hello</span> <script>alert('OHAI')</script>") \
|
243
245
|
.scrub!(:prune) \
|
244
246
|
.scrub!(span2div).to_s
|
245
247
|
# => "<div>hello</div> "
|
@@ -247,21 +249,26 @@ Loofah.fragment("<span>hello</span> <script>alert('OHAI')</script>") \
|
|
247
249
|
|
248
250
|
### Shorthand
|
249
251
|
|
250
|
-
The class methods Loofah.
|
251
|
-
|
252
|
+
The class methods `Loofah.scrub_html5_fragment` and `Loofah.scrub_html5_document` (and the corresponding HTML4 methods) are shorthand.
|
253
|
+
|
254
|
+
These methods:
|
252
255
|
|
253
256
|
``` ruby
|
254
|
-
Loofah.
|
255
|
-
Loofah.
|
257
|
+
Loofah.scrub_html5_fragment(unsafe_html, :prune)
|
258
|
+
Loofah.scrub_html5_document(unsafe_html, :prune)
|
259
|
+
Loofah.scrub_html4_fragment(unsafe_html, :prune)
|
260
|
+
Loofah.scrub_html4_document(unsafe_html, :prune)
|
256
261
|
Loofah.scrub_xml_fragment(bad_xml, custom_scrubber)
|
257
262
|
Loofah.scrub_xml_document(bad_xml, custom_scrubber)
|
258
263
|
```
|
259
264
|
|
260
|
-
|
265
|
+
do the same thing as (and arguably semantically clearer than):
|
261
266
|
|
262
267
|
``` ruby
|
263
|
-
Loofah.
|
264
|
-
Loofah.
|
268
|
+
Loofah.html5_fragment(unsafe_html).scrub!(:prune)
|
269
|
+
Loofah.html5_document(unsafe_html).scrub!(:prune)
|
270
|
+
Loofah.html4_fragment(unsafe_html).scrub!(:prune)
|
271
|
+
Loofah.html4_document(unsafe_html).scrub!(:prune)
|
265
272
|
Loofah.xml_fragment(bad_xml).scrub!(custom_scrubber)
|
266
273
|
Loofah.xml_document(bad_xml).scrub!(custom_scrubber)
|
267
274
|
```
|
@@ -269,10 +276,9 @@ Loofah.xml_document(bad_xml).scrub!(custom_scrubber)
|
|
269
276
|
|
270
277
|
### View Helpers
|
271
278
|
|
272
|
-
Loofah has two "view helpers": Loofah::Helpers.sanitize and
|
273
|
-
|
274
|
-
|
275
|
-
These are no longer required automatically. You must require `loofah/helpers`.
|
279
|
+
Loofah has two "view helpers": `Loofah::Helpers.sanitize` and `Loofah::Helpers.strip_tags`, both of which are drop-in replacements for the Rails Action View helpers of the same name.
|
280
|
+
|
281
|
+
These are not required automatically. You must require `loofah/helpers` to use them.
|
276
282
|
|
277
283
|
|
278
284
|
## Requirements
|
@@ -284,7 +290,11 @@ These are no longer required automatically. You must require `loofah/helpers`.
|
|
284
290
|
|
285
291
|
Unsurprisingly:
|
286
292
|
|
287
|
-
|
293
|
+
> gem install loofah
|
294
|
+
|
295
|
+
Requirements:
|
296
|
+
|
297
|
+
* Ruby >= 2.5
|
288
298
|
|
289
299
|
|
290
300
|
## Support
|
@@ -298,8 +308,6 @@ And the mailing list is on Google Groups:
|
|
298
308
|
* Mail: loofah-talk@googlegroups.com
|
299
309
|
* Archive: https://groups.google.com/forum/#!forum/loofah-talk
|
300
310
|
|
301
|
-
And the IRC channel is \#loofah on freenode.
|
302
|
-
|
303
311
|
Consider subscribing to [Tidelift][tidelift] which provides license assurances and timely security notifications for your open source dependencies, including Loofah. [Tidelift][tidelift] subscriptions also help the Loofah maintainers fund our [automated testing](https://ci.nokogiri.org) which in turn allows us to ship releases, bugfixes, and security updates more often.
|
304
312
|
|
305
313
|
[tidelift]: https://tidelift.com/subscription/pkg/rubygems-loofah?utm_source=undefined&utm_medium=referral&utm_campaign=enterprise
|
@@ -310,26 +318,12 @@ Consider subscribing to [Tidelift][tidelift] which provides license assurances a
|
|
310
318
|
See [`SECURITY.md`](SECURITY.md) for vulnerability reporting details.
|
311
319
|
|
312
320
|
|
313
|
-
### "Secure by Default"
|
314
|
-
|
315
|
-
Some tools may incorrectly report Loofah as a potential security
|
316
|
-
vulnerability.
|
317
|
-
|
318
|
-
Loofah depends on Nokogiri, and it's _possible_ to use Nokogiri in a
|
319
|
-
dangerous way (by enabling its DTDLOAD option and disabling its NONET
|
320
|
-
option). This specifically allows the opportunity for an XML External
|
321
|
-
Entity (XXE) vulnerability if the XML data is untrusted.
|
322
|
-
|
323
|
-
However, Loofah __never enables this Nokogiri configuration__; Loofah
|
324
|
-
never enables DTDLOAD, and it never disables NONET, thereby protecting
|
325
|
-
you by default from this XXE vulnerability.
|
326
|
-
|
327
|
-
|
328
321
|
## Related Links
|
329
322
|
|
323
|
+
* loofah-activerecord: https://github.com/flavorjones/loofah-activerecord
|
330
324
|
* Nokogiri: http://nokogiri.org
|
331
325
|
* libxml2: http://xmlsoft.org
|
332
|
-
* html5lib: https://
|
326
|
+
* html5lib: https://github.com/html5lib/
|
333
327
|
|
334
328
|
|
335
329
|
## Authors
|
@@ -350,15 +344,14 @@ And a big shout-out to Corey Innis for the name, and feedback on the API.
|
|
350
344
|
|
351
345
|
## Thank You
|
352
346
|
|
353
|
-
The following people have generously
|
347
|
+
The following people have generously funded Loofah:
|
354
348
|
|
355
349
|
* Bill Harding
|
356
350
|
|
357
351
|
|
358
352
|
## Historical Note
|
359
353
|
|
360
|
-
This library was
|
361
|
-
name that nobody could spell properly.
|
354
|
+
This library was once named "Dryopteris", which was a very bad name that nobody could spell properly.
|
362
355
|
|
363
356
|
|
364
357
|
## License
|