Docblock update
[htmlpurifier.git] / docs / proposal-filter-levels.txt
2 Filter Levels
3     When one size *does not* fit all
5 It makes little sense to constrain users to one set of HTML elements and
6 attributes and tell them that they are not allowed to mold this in
7 any fashion.  Many users demand to be able to custom-select which elements
8 and attributes they want.  This is fine: because HTML Purifier keeps close
9 track of what elements are safe to use, there is no way for them to
10 accidently allow an XSS-able tag.
12 However, combing through the HTML spec to make your own whitelist can
13 be a daunting task.  HTML Purifier ought to offer pre-canned filter levels
14 that amateur users can select based on what they think is their use-case.
16 Here are some fuzzy levels you could set:
18 1. Comments - Wordpress recommends a, abbr, acronym, b, blockquote, cite,
19     code, em, i, strike, strong; however, you could get away with only a, em and
20     p; also having blockquote and pre tags would be helpful.
21 2. BBCode - Emulate the usual tagset for forums: b, i, img, a, blockquote,
22     pre, div, span and h[2-6] (the last three are for specially formatted
23     posts, div and span require associated classes or inline styling enabled
24     to be useful)
25 3. Pages - As permissive as possible without allowing XSS.  No protection
26     against bad design sense, unfortunantely.  Suitable for wiki and page
27     environments. (probably what we have now)
28 4. Lint - Accept everything in the spec, a Tidy wannabe. (This probably won't
29     get implemented as it would require routines for things like <object>
30     and friends to be implemented, which is a lot of work for not a lot of
31     benefit)
33 One final note: when you start axing tags that are more commonly used, you
34 run the risk of accidentally destroying user data, especially if the data
35 is incoming from a WYSIWYG editor that hasn't been synced accordingly. This may
36 make forbidden element to text transformations desirable (for example, images).
40 == Element Risk Analysis ==
42 Although none of the currently supported elements presents a security
43 threat per-say, some can cause problems for page layouts or be
44 extremely complicated.
46 Legend:
47     [danger level] - regular tags / uncommon tags ~ deprecated tags
48     [danger level]* - rare tags
50 1 - blockquote, code, em, i, p, tt / strong, sub, sup
51 1* - abbr, acronym, bdo, cite, dfn, kbd, q, samp
52 2 - b, br, del, div, pre, span / ins, s, strike ~ u
53 3 - h2, h3, h4, h5, h6 ~ center
54 4 - h1, big ~ font
55 5 - a
56 7 - area, map
58 These are special use tags, they should be enabled on a blanket basis.
60 Lists - dd, dl, dt, li, ol, ul ~ menu, dir
61 Tables - caption, table, td, th, tr / col, colgroup, tbody, tfoot, thead
63 Forms - fieldset, form, input, lable, legend, optgroup, option, select, textarea
64 XSS - noscript, object, script ~ applet
65 Meta - base, basefont, body, head, html, link, meta, style, title
66 Frames - frame, frameset, iframe
68 And tag specific notes:
70 a   - general problems involving linkspam
71 b   - too much bold is bad, typographically speaking bold is discouraged
72 br  - often misused
73 center - CSS, usually no legit use
74 del - only useful in editing context
75 div - little meaning in certain contexts i.e. blog comment
76 h1  - usually no legit use, as header is already set by application
77 h*  - not needed in blog comments
78 hr  - usually not necessary in blog comments
79 img - could be extremely undesirable if linking to external pics (CSRF, goatse)
80 pre - could use formatting, only useful in code contexts
81 q   - very little support
82 s   - transform into span with styling or del?
83 small - technically presentational
84 span - depends on attribute allowances
85 sub, sup - specialized
86 u   - little legit use, prefer class with text-decoration
88 Based on the riskiness of the items, we may want to offer %HTML.DisableImages
89 attribute and put URI filtering higher up on the priority list.
92 == Attribute Risk Analysis ==
94 We actually have a suprisingly small assortment of allowed attributes (the
95 rest are deprecated in strict, and thus we opted not to allow them, even
96 though our output is XHTML Transitional by default.)
98 Required URI - img.alt, img.src, a.href
99 Medium risk - *.class, *.dir
100 High risk - img.height, img.width, *.id, *.style
102 Table - colgroup/col.span, td/th.rowspan, td/th.colspan
103 Uncommon - *.title, *.lang, *.xml:lang
104 Rare - td/th.abbr, table.summary, {table}.charoff
105 Rare URI - del.cite, ins.cite, blockquote.cite, q.cite, img.longdesc
106 Presentational - {table}.align, {table}.valign, table.frame, table.rules,
107     table.border
108 Partially presentational - table.cellpadding, table.cellspacing,
109     table.width, col.width, colgroup.width
112 == CSS Risk Analysis ==
114 Currently, there is no support for fine-grained "allowed CSS" specification,
115 mainly because I'm lazy, partially because no one has asked for it. However,
116 this will be added eventually.
118 There are certain CSS elements that are extremely useful inline, but then
119 as you get to more presentation oriented styling it may not always be
120 appropriate to inline them.
122 Useful - clear, float, border-collapse, caption-side
124 These CSS properties can break layouts if used improperly. We have excluded
125 any CSS properties that are not currently implemented (such as position).
127 Dangerous, can go outside container - float
128 Easy to abuse - font-size, font-family (font), width
129 Colored - background-color (background), border-color (border), color
130     (see proposal-colors.html)
131 Dramatic - border, list-style-position (list-style), margin, padding,
132     text-align, text-indent, text-transform, vertical-align, line-height
134 Dramatic elements substantially change the look of text in ways that should
135 probably have been reserved to other areas.
137     vim: et sw=4 sts=4