183 lines
6.5 KiB
Plaintext
183 lines
6.5 KiB
Plaintext
= sfXssSafePlugin - Output Rich Text With Cross Site Scripting Protection =
|
|
|
|
== Overview ==
|
|
|
|
Between the `ESC_RAW` and `ESC_HTMLENTITIES`, symfony lacks one escaping level allowing to strip dangerous HTML code but leave the tags that just structure a content or apply a format to it.
|
|
|
|
The `sfXssSafePlugin` allows to clean a string to prevent XSS attacks. It provides a new escaping strategy, `ESC_XSSSAFE`, to escape tainted HTML strings entered by users. This escaping strategy removes all "dangerous" tags and attributes but keeps the safe ones. The plugin embarks the [http://htmlpurifier.org/ HTML Putifier] library and is fully unit-tested.
|
|
|
|
== Installation ==
|
|
|
|
* Install the plugin
|
|
{{{
|
|
> symfony plugin-install http://plugins.symfony-project.com/sfXssSafePlugin
|
|
}}}
|
|
|
|
* Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's `plugins/` directory
|
|
|
|
== Usage ==
|
|
|
|
First of all, your application escaping strategy must be set to `both` or `on` to use this plugin. Check your `settings.yml` for the `escaping_strategy` parameter.
|
|
|
|
Include the helper in the templates where you want to use the new escaping strategy:
|
|
{{{
|
|
<?php use_helper('XssSafe') ?>
|
|
}}}
|
|
|
|
As explained in the [http://www.symfony-project.org/book/1_0/07-Inside-the-View-Layer#Escaping%20Arrays%20and%20Objects symfony book], the methods of escaped objects accept an additionnal parameter for the escaping strategy. In addition to the core `ESC_HTMLENTITIES` and `ESC_RAW`, you can now use the `ESC_XSSSAFE` strategy.
|
|
|
|
{{{
|
|
// In the action
|
|
$this->post->setContent('this is not nice <script>alert("XSS");</script>');
|
|
|
|
// In the template
|
|
<?php echo $post->getContent(ESC_XSSSAFE); ?>
|
|
=> 'this is not nice'
|
|
}}}
|
|
|
|
== Configuration ==
|
|
|
|
You can change the HTML Purifier configuration in your application's `app.yml` file, under the `sfXssSafePlugin` section. Refer to the plugin's `app.sample.yml` and to the [http://htmlpurifier.org/live/configdoc/plain.html HTML Purifier documentation] for further information.
|
|
|
|
Here is the default configuration used by the plugin if you don't add anything to your `app.yml`:
|
|
|
|
{{{
|
|
all:
|
|
sfXssSafePlugin:
|
|
definition:
|
|
|
|
HTML:
|
|
TidyLevel: medium # Values : "none", "light", "medium", "heavy"
|
|
Doctype: null # Accepts valid Doctypes, like 'XHTML 1.0 Transitional'
|
|
Trusted: false
|
|
|
|
Core:
|
|
Encoding: UTF-8 # This directive only accepts ISO-8859-1 if iconv is not enabled
|
|
RemoveInvalidImg: true
|
|
EscapeInvalidChildren: false
|
|
EscapeInvalidTags: false
|
|
|
|
CSS:
|
|
AllowImportant: false
|
|
|
|
Filter:
|
|
YouTube: false # Allow YouTube video embeded
|
|
|
|
AutoFormat:
|
|
AutoParagraph: false
|
|
|
|
URI:
|
|
Disable: false
|
|
DisableExternal: false
|
|
|
|
Output:
|
|
TidyFormat: false
|
|
}}}
|
|
|
|
== More configuration ==
|
|
|
|
Although HTML Purifier contains a large set of elements and attributes, you can customize others elements or attributes.
|
|
|
|
The plugin contains a sample which show how to allow to display flash movies :
|
|
|
|
- First add the following configuration in `app.yml` file :
|
|
|
|
{{{
|
|
all:
|
|
sfXssSafePlugin:
|
|
definition:
|
|
|
|
HTML:
|
|
DefinitionID: 'allow flash movies'
|
|
DefinitionRev: 1
|
|
|
|
AutoFormat:
|
|
Custom: AddParam # injector : call class "HTMLPurifier_Injector_AddParam"
|
|
Element:
|
|
- param:
|
|
type: false
|
|
contents: Empty
|
|
attr_includes: false
|
|
attr:
|
|
'name': Text
|
|
'value': Text
|
|
|
|
- object:
|
|
type: Inline
|
|
contents: 'Optional: param | Flow | #PCDATA'
|
|
attr_includes: false
|
|
attr:
|
|
'type*': 'Enum#application/x-shockwave-flash'
|
|
'width*': Pixels
|
|
'height*': Pixels
|
|
'data': Text
|
|
'bgcolor*': Text
|
|
'quality*': Text
|
|
|
|
- embed:
|
|
type: Block
|
|
contents: Empty
|
|
attr_includes: false
|
|
attr:
|
|
'type*': 'Enum#application/x-shockwave-flash'
|
|
'width*': Pixels
|
|
'height*': Pixels
|
|
'src*': URI
|
|
'flashvars': Text
|
|
'allowscriptaccess': 'Enum#never'
|
|
'enablejsurls': 'Enum#false'
|
|
'enablehref': 'Enum#false'
|
|
'bgcolor': Text
|
|
'align': Text
|
|
'quality': Text
|
|
'wmode': Text
|
|
'pluginspage': URI
|
|
'saveembedtags': Text
|
|
'salign': Text
|
|
'scale': Text
|
|
'name': Text
|
|
}}}
|
|
|
|
`HTML.DefinitionID` is set to a unique identifier for your custom HTML definition. This prevents it from clobbering other custom definitions on the same installation.
|
|
`HTML.DefinitionRev` is a revision integer of your HTML definition.
|
|
`AutoFormat.Element` adds `param`, `object` and `embed` elements, with theirs allowed attributes.
|
|
|
|
- The same way you can add an attribute to an element with `AutoFormat.Attribute` :
|
|
|
|
{{{
|
|
all:
|
|
sfXssSafePlugin:
|
|
definition:
|
|
AutoFormat:
|
|
Attribute:
|
|
- a:
|
|
attr_name: target
|
|
def: 'Enum#_blank,_self,_target,_top'
|
|
}}}
|
|
|
|
- Then you can clean more the added element overloading HTML Purifier.
|
|
For this, move the sample file `sfXssSafeObject.class.php` in the an autoloaded directory (`lib` of your project for instance).
|
|
|
|
The file contains the classes of transformation for each element.
|
|
There is also an auto-format injector that we called `AddParam` in our example.
|
|
|
|
Finally, clear your cache to enable the autoloading Symfony feature to find the new classes.
|
|
|
|
== Changelog ==
|
|
|
|
=== 2008-11-08 | 0.8 ===
|
|
|
|
* heristop : Migration to HTML Purifier 3.2
|
|
|
|
=== 2008-06-27 | 0.6.1 Beta ===
|
|
|
|
* heristop : Migration to HTML Purifier 3.1.1
|
|
|
|
=== 2008-06-20 | 0.6.0 Beta ===
|
|
|
|
* heristop : Adding customizable elements
|
|
|
|
=== 2008-05-19 | 0.5.0 Beta ===
|
|
|
|
* heristop: Initial version
|