开通博客赚积分
发布资源赚积分
分类

源码开发语言/平台
sanitize
文件大小： unknow
源码售价： 5 个金币 积分规则     积分充值
充值1元得10金币   
资源说明：Ruby HTML and CSS sanitizer.
Sanitize
========

Sanitize is an allowlist-based HTML and CSS sanitizer. It removes all HTML
and/or CSS from a string except the elements, attributes, and properties you
choose to allow.

Using a simple configuration syntax, you can tell Sanitize to allow certain HTML
elements, certain attributes within those elements, and even certain URL
protocols within attributes that contain URLs. You can also allow specific CSS
properties, @ rules, and URL protocols in elements or attributes containing CSS.
Any HTML or CSS that you don't explicitly allow will be removed.

Sanitize is based on the [Nokogumbo HTML5 parser][nokogumbo], which parses HTML
exactly the same way modern browsers do, and [Crass][crass], which parses CSS
exactly the same way modern browsers do. As long as your allowlist config only
allows safe markup and CSS, even the most malformed or malicious input will be
transformed into safe output.

[![Gem Version](https://badge.fury.io/rb/sanitize.svg)](http://badge.fury.io/rb/sanitize)
[![Tests](https://github.com/rgrove/sanitize/workflows/Tests/badge.svg)](https://github.com/rgrove/sanitize/actions?query=workflow%3ATests)

[crass]:https://github.com/rgrove/crass
[nokogumbo]:https://github.com/rubys/nokogumbo

Links
-----

* [Home](https://github.com/rgrove/sanitize/)
* [API Docs](http://rubydoc.info/github/rgrove/sanitize/master)
* [Issues](https://github.com/rgrove/sanitize/issues)
* [Release History](https://github.com/rgrove/sanitize/blob/master/HISTORY.md#sanitize-history)
* [Online Demo](https://sanitize.herokuapp.com/)
* [Biased comparison of Ruby HTML sanitization libraries](https://github.com/rgrove/sanitize/blob/master/COMPARISON.md)

Installation
-------------

```
gem install sanitize
```

Quick Start
-----------

```ruby
require 'sanitize'

# Clean up an HTML fragment using Sanitize's permissive but safe Relaxed config.
# This also sanitizes any CSS in `

  

  
hello!

]

Sanitize.fragment(html,
  :elements   => ['div', 'style'],
  :attributes => {'div' => ['style']},

  :css => {
    :properties => ['width']
  }
)
#=> %[
#   
#
#   

#   hello!
# ]
```

### Standalone CSS

Sanitize will happily clean up a standalone CSS stylesheet or property string
without needing to invoke the HTML parser.

```ruby
css = %[
  @import url(evil.css);

  a { text-decoration: none; }

  a:hover {
    left: expression(alert('xss!'));
    text-decoration: underline;
  }
]

Sanitize::CSS.stylesheet(css, Sanitize::Config::RELAXED)
# => %[
#
#
#
#   a { text-decoration: none; }
#
#   a:hover {
#
#     text-decoration: underline;
#   }
# ]

Sanitize::CSS.properties(%[
  left: expression(alert('xss!'));
  text-decoration: underline;
], Sanitize::Config::RELAXED)
# => %[
#
#   text-decoration: underline;
# ]

```

Configuration
-------------

In addition to the ultra-safe default settings, Sanitize comes with three other
built-in configurations that you can use out of the box or adapt to meet your
needs.

### Sanitize::Config::RESTRICTED

Allows only very simple inline markup. No links, images, or block elements.

```ruby
Sanitize.fragment(html, Sanitize::Config::RESTRICTED)
# => 'foo'
```

### Sanitize::Config::BASIC

Allows a variety of markup including formatting elements, links, and lists.

Images and tables are not allowed, links are limited to FTP, HTTP, HTTPS, and
mailto protocols, and a `rel="nofollow"` attribute is added to all links to
mitigate SEO spam.

```ruby
Sanitize.fragment(html, Sanitize::Config::BASIC)
# => 'foo'
```

### Sanitize::Config::RELAXED

Allows an even wider variety of markup, including images and tables, as well as
safe CSS. Links are still limited to FTP, HTTP, HTTPS, and mailto protocols,
while images are limited to HTTP and HTTPS. In this mode, `rel="nofollow"` is
not added to links.

```ruby
Sanitize.fragment(html, Sanitize::Config::RELAXED)
# => 'foo'
```

### Custom Configuration

If the built-in modes don't meet your needs, you can easily specify a custom
configuration:

```ruby
Sanitize.fragment(html,
  :elements => ['a', 'span'],

  :attributes => {
    'a'    => ['href', 'title'],
    'span' => ['class']
  },

  :protocols => {
    'a' => {'href' => ['http', 'https', 'mailto']}
  }
)
```

You can also start with one of Sanitize's built-in configurations and then
customize it to meet your needs.

The built-in configs are deeply frozen to prevent people from modifying them
(either accidentally or maliciously). To customize a built-in config, create a
new copy using `Sanitize::Config.merge()`, like so:

```ruby
# Create a customized copy of the Basic config, adding 
 and  to the
# existing allowlisted elements.
Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
  :elements        => Sanitize::Config::BASIC[:elements] + ['div', 'table'],
  :remove_contents => true
))
```

The example above adds the `
` and `
` elements to a copy of the
existing list of elements in `Sanitize::Config::BASIC`. If you instead want to
completely overwrite the elements array with your own, you can omit the `+`
operation:

```ruby
# Overwrite :elements instead of creating a copy with new entries.
Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
  :elements        => ['div', 'table'],
  :remove_contents => true
))
```

### Config Settings

#### :add_attributes (Hash)

Attributes to add to specific elements. If the attribute already exists, it will
be replaced with the value specified here. Specify all element names and
attributes in lowercase.

```ruby
:add_attributes => {
  'a' => {'rel' => 'nofollow'}
}
```

#### :allow_comments (boolean)

Whether or not to allow HTML comments. Allowing comments is strongly
discouraged, since IE allows script execution within conditional comments. The
default value is `false`.

#### :allow_doctype (boolean)

Whether or not to allow well-formed HTML doctype declarations such as "" when sanitizing a document. This setting is ignored when sanitizing
fragments. The default value is `false`.

#### :attributes (Hash)

Attributes to allow on specific elements. Specify all element names and
attributes in lowercase.

```ruby
:attributes => {
  'a'          => ['href', 'title'],
  'blockquote' => ['cite'],
  'img'        => ['alt', 'src', 'title']
}
```

If you'd like to allow certain attributes on all elements, use the symbol `:all`
instead of an element name.

```ruby
# Allow the class attribute on all elements.
:attributes => {
  :all => ['class'],
  'a'  => ['href', 'title']
}
```

To allow arbitrary HTML5 `data-*` attributes, use the symbol `:data` in place of
an attribute name.

```ruby
# Allow arbitrary HTML5 data-* attributes on 
 elements.
:attributes => {
  'div' => [:data]
}
```

#### :css (Hash)

Hash of the following CSS config settings to be used when sanitizing CSS (either
standalone or embedded in HTML).

##### :css => :allow_comments (boolean)

Whether or not to allow CSS comments. The default value is `false`.

##### :css => :allow_hacks (boolean)

Whether or not to allow browser compatibility hacks such as the IE `*` and `_`
hacks. These are generally harmless, but technically result in invalid CSS. The
default is `false`.

##### :css => :at_rules (Array or Set)

Names of CSS [at-rules][at-rules] to allow that may not have associated blocks,
such as `import` or `charset`. Names should be specified in lowercase.

[at-rules]:https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule

##### :css => :at_rules_with_properties (Array or Set)

Names of CSS [at-rules][at-rules] to allow that may have associated blocks
containing CSS properties. At-rules like `font-face` and `page` fall into this
category. Names should be specified in lowercase.

##### :css => :at_rules_with_styles (Array or Set)

Names of CSS [at-rules][at-rules] to allow that may have associated blocks
containing style rules. At-rules like `media` and `keyframes` fall into this
category. Names should be specified in lowercase.

##### :css => :import_url_validator

This is a `Proc` (or other callable object) that will be called and passed
the URL specified for any `@import` [at-rules][at-rules].

You can use this to limit what can be imported, for example something
like the following to limit `@import` to Google Fonts URLs:

```ruby
Proc.new { |url| url.start_with?("https://fonts.googleapis.com") }
```

##### :css => :properties (Array or Set)

List of CSS property names to allow. Names should be specified in lowercase.

##### :css => :protocols (Array or Set)

URL protocols to allow in CSS URLs. Should be specified in lowercase.

If you'd like to allow the use of relative URLs which don't have a protocol,
include the symbol `:relative` in the protocol array.

#### :elements (Array or Set)

Array of HTML element names to allow. Specify all names in lowercase. Any
elements not in this array will be removed.

```ruby
:elements => %w[
  a abbr b blockquote br cite code dd dfn dl dt em i kbd li mark ol p pre
  q s samp small strike strong sub sup time u ul var
]
```

**Warning:** Sanitize cannot fully sanitize the contents of `` or ``
elements, since these elements don't follow the same parsing rules as the rest
of HTML. If you add `math` or `svg` to the allowlist, you must assume that any
content inside them will be allowed, even if that content would otherwise be
removed by Sanitize.

#### :parser_options (Hash)

[Parsing options](https://github.com/rubys/nokogumbo/tree/master#parsing-options) to be supplied to `nokogumbo`.

```ruby
:parser_options => {
  max_errors: -1,
  max_tree_depth: -1
}
```

#### :protocols (Hash)

URL protocols to allow in specific attributes. If an attribute is listed here
and contains a protocol other than those specified (or if it contains no
protocol at all), it will be removed.

```ruby
:protocols => {
  'a'   => {'href' => ['ftp', 'http', 'https', 'mailto']},
  'img' => {'src'  => ['http', 'https']}
}
```

If you'd like to allow the use of relative URLs which don't have a protocol,
include the symbol `:relative` in the protocol array:

```ruby
:protocols => {
  'a' => {'href' => ['http', 'https', :relative]}
}
```

#### :remove_contents (boolean or Array or Set)

If this is `true`, Sanitize will remove the contents of any non-allowlisted
elements in addition to the elements themselves. By default, Sanitize leaves the
safe parts of an element's contents behind when the element is removed.

If this is an Array or Set of element names, then only the contents of the
specified elements (when filtered) will be removed, and the contents of all
other filtered elements will be left behind.

The default value is `%w[iframe math noembed noframes noscript plaintext script style svg xmp]`.

#### :transformers (Array or callable)

Custom HTML transformer or array of custom transformers. See the Transformers
section below for details.

#### :whitespace_elements (Hash)

Hash of element names which, when removed, should have their contents surrounded
by whitespace to preserve readability.

Each element name is a key pointing to another Hash, which provides the specific
whitespace that should be inserted `:before` and `:after` the removed element's
position. The `:after` value will only be inserted if the removed element has
children, in which case it will be inserted after those children.

```ruby
:whitespace_elements => {
  'br'  => { :before => "\n", :after => "" },
  'div' => { :before => "\n", :after => "\n" },
  'p'   => { :before => "\n", :after => "\n" }
}
```

The default elements with whitespace added before and after are:

```
address article aside blockquote br dd div dl dt
footer h1 h2 h3 h4 h5 h6 header hgroup hr li nav
ol p pre section ul

```

## Transformers

Transformers allow you to filter and modify HTML nodes using your own custom
logic, on top of (or instead of) Sanitize's core filter. A transformer is any
object that responds to `call()` (such as a lambda or proc).

To use one or more transformers, pass them to the `:transformers` config
setting. You may pass a single transformer or an array of transformers.

```ruby
Sanitize.fragment(html, :transformers => [
  transformer_one,
  transformer_two
])
```

### Input

Each transformer's `call()` method will be called once for each node in the HTML
(including elements, text nodes, comments, etc.), and will receive as an
argument a Hash that contains the following items:

  * **:config** - The current Sanitize configuration Hash.

  * **:is_allowlisted** - `true` if the current node has been allowlisted by a
    previous transformer, `false` otherwise. It's generally bad form to remove
    a node that a previous transformer has allowlisted.

  * **:node** - A `Nokogiri::XML::Node` object representing an HTML node. The
    node may be an element, a text node, a comment, a CDATA node, or a document
    fragment. Use Nokogiri's inspection methods (`element?`, `text?`, etc.) to
    selectively ignore node types you aren't interested in.

  * **:node_allowlist** - Set of `Nokogiri::XML::Node` objects in the current
    document that have been allowlisted by previous transformers, if any. It's
    generally bad form to remove a node that a previous transformer has
    allowlisted.

  * **:node_name** - The name of the current HTML node, always lowercase (e.g.
    "div" or "span"). For non-element nodes, the name will be something like
    "text", "comment", "#cdata-section", "#document-fragment", etc.

### Output

A transformer doesn't have to return anything, but may optionally return a Hash,
which may contain the following items:

  * **:node_allowlist** -  Array or Set of specific `Nokogiri::XML::Node`
    objects to add to the document's allowlist, bypassing the current Sanitize
    config. These specific nodes and all their attributes will be allowlisted,
    but their children will not be.

If a transformer returns anything other than a Hash, the return value will be
ignored.

### Processing

Each transformer has full access to the `Nokogiri::XML::Node` that's passed into
it and to the rest of the document via the node's `document()` method. Any
changes made to the current node or to the document will be reflected instantly
in the document and passed on to subsequently called transformers and to
Sanitize itself. A transformer may even call Sanitize internally to perform
custom sanitization if needed.

Nodes are passed into transformers in the order in which they're traversed.
Sanitize performs top-down traversal, meaning that nodes are traversed in the
same order you'd read them in the HTML, starting at the top node, then its first
child, and so on.

```ruby
html = %[
  

    

      foo
    
    
bar

  

  

]

transformer = lambda do |env|
  puts env[:node_name] if env[:node].element?
end

# Prints "header", "span", "strong", "p", "footer".
Sanitize.fragment(html, :transformers => transformer)
```

Transformers have a tremendous amount of power, including the power to
completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
your own hands.

### Example: Transformer to allow image URLs by domain

The following example demonstrates how to remove image elements unless they use
a relative URL or are hosted on a specific domain. It assumes that the ``
element and its `src` attribute are already allowlisted.

```ruby
require 'uri'

image_allowlist_transformer = lambda do |env|
  # Ignore everything except  elements.
  return unless env[:node_name] == 'img'

  node      = env[:node]
  image_uri = URI.parse(node['src'])

  # Only allow relative URLs or URLs with the example.com domain. The
  # image_uri.host.nil? check ensures that protocol-relative URLs like
  # "//evil.com/foo.jpg".
  unless image_uri.host == 'example.com' || (image_uri.host.nil? && image_uri.relative?)
    node.unlink # `Nokogiri::XML::Node#unlink` removes a node from the document
  end
end
```

### Example: Transformer to allow YouTube video embeds

The following example demonstrates how to create a transformer that will safely
allow valid YouTube video embeds without having to allow other kinds of embedded
content, which would be the case if you tried to do this by just allowing all
`
]

Sanitize.fragment(html, :transformers => youtube_transformer)
# => ''
```
  

		
		
		

			
				



				
			
		

			

				

					
部分文件列表（点击文件名可查看文件内容）

			  

			

			
			

					

									本源码包内暂不包含可直接显示的源代码文件，请下载源码包。