OWASP - User contributions [en]

IOS Developer Cheat Sheet

2016-06-29T12:08:01Z

Yozo: "IP number" changed to "IP address", aligned to "Mac address" (-:

DOM based XSS Prevention Cheat Sheet

2016-06-29T10:13:53Z

Yozo: should be typo...

__NOTOC__
<div style="width:100%;height:160px;border:0,margin:0;overflow: hidden;">[[File:Cheatsheets-header.jpg|link=]]</div>

{| style="padding: 0;margin:0;margin-top:10px;text-align:left;" |-
| valign="top" style="border-right: 1px dotted gray;padding-right:25px;" |
Last revision (mm/dd/yy): '''{{REVISIONMONTH}}/{{REVISIONDAY}}/{{REVISIONYEAR}}'''
= Introduction =
__TOC__{{TOC hidden}}

When looking at XSS (Cross-Site Scripting), there are three generally recognized forms of [[XSS]]. [[XSS#Stored_and_Reflected_XSS_Attacks | Reflected, Stored]], and [[DOM Based XSS]]. The [[XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet | XSS Prevention Cheatsheet]] does an excellent job of addressing Reflected and Stored XSS. This cheatsheet addresses DOM (Document Object Model) based XSS and is an extension (and assumes comprehension of) the [[XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet | XSS Prevention Cheatsheet]].

In order to understand DOM based XSS, one needs to see the fundamental difference between Reflected and Stored XSS when compared to DOM based XSS. The primary difference is where the attack is injected into the application. Reflected and Stored XSS are server side injection issues while DOM based XSS is a client (browser) side injection issue. All of this code originates on the server, which means it is the application owner's responsibility to make it safe from XSS, regardless of the type of XSS flaw it is. Also, XSS attacks always <b>execute</b> in the browser. The difference between Reflected/Stored XSS is where the attack is added or injected into the application. With Reflected/Stored the attack is injected into the application during server-side processing of requests where untrusted input is dynamically added to HTML. For DOM XSS, the attack is injected into the application during runtime in the client directly.

When a browser is rendering HTML and any other associated content like CSS, JavaScript, etc. it identifies various rendering contexts for the different kinds of input and follows different rules for each context. A rendering context is associated with the parsing of HTML tags and their attributes. The HTML parser of the rendering context dictates how data is presented and laid out on the page and can be further broken down into the standard contexts of HTML, HTML attribute, URL, and CSS. The JavaScript or VBScript parser of an execution context is associated with the parsing and execution of script code. Each parser has distinct and separate semantics in the way they can possibly execute script code which make creating consistent rules for mitigating vulnerabilities in various contexts difficult. The complication is compounded by the differing meanings and treatment of encoded values within each subcontext (HTML, HTML attribute, URL, and CSS) within the execution context.

For the purposes of this article, we refer to the HTML, HTML attribute, URL, and CSS contexts as subcontexts because each of these contexts can be reached and set within a JavaScript execution context. In JavaScript code, the main context is JavaScript but with the right tags and context closing characters, an attacker can try to attack the other 4 contexts using equivalent JavaScript DOM methods.<br/>

The following is an example vulnerability which occurs in the JavaScript context and HTML subcontext:<br/>

<code>
<script>
var x = '<%= taintedVar %>';
var d = document.createElement('div');
d.innerHTML = x;
document.body.appendChild(d);
</script>
</code>

Let’s look at the individual subcontexts of the execution context in turn.

==RULE #1 - HTML Escape then JavaScript Escape Before Inserting Untrusted Data into HTML Subcontext within the Execution Context==

There are several methods and attributes which can be used to directly render HTML content within JavaScript. These methods constitute the HTML Subcontext within the Execution Context. If these methods are provided with untrusted input, then an XSS vulnerability could result. For example:

===Example Dangerous HTML Methods===
====Attributes====
<code>
element.innerHTML = "<HTML> Tags and markup";
element.outerHTML = "<HTML> Tags and markup";
</code>

====Methods====
<code>
document.write("<HTML> Tags and markup");
document.writeln("<HTML> Tags and markup");
</code>

===Guideline===
To make dynamic updates to HTML in the DOM safe, we recommend a) HTML encoding, and then b) JavaScript encoding all untrusted input, as shown in these examples:

<code>
element.innerHTML = "<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>";
element.outerHTML = "<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>";
</code>

<code>
document.write("<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>");
document.writeln("<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>");
</code>

Note: The Encoder.encodeForHTML() and Encoder.encodeForJS() are just notional encoders. Various options for actual encoders are listed later in this document.

== RULE #2 - JavaScript Escape Before Inserting Untrusted Data into HTML Attribute Subcontext within the Execution Context ==

The HTML attribute *subcontext* within the *execution* context is divergent from the standard encoding rules. This is because the rule to HTML attribute encode in an HTML attribute rendering context is necessary in order to mitigate attacks which try to exit out of an HTML attributes or try to add additional attributes which could lead to XSS. When you are in a DOM execution context you only need to JavaScript encode HTML attributes which do not execute code (attributes other than event handler, CSS, and URL attributes).

For example, the general rule is to HTML Attribute encode untrusted data (data from the database, HTTP request, user, back-end system, etc.) placed in an HTML Attribute. This is the appropriate step to take when outputting data in a rendering context, however using HTML Attribute encoding in an execution context will break the application display of data.

=== SAFE but BROKEN example===
<code>
var x = document.createElement("input");
x.setAttribute("name", "company_name");
// In the following line of code, companyName represents untrusted user input
// The Encoder.encodeForHTMLAttr() is unnecessary and causes double-encoding
x.setAttribute("value", '<%=Encoder.encodeForJS(Encoder.encodeForHTMLAttr(companyName))%>');
var form1 = document.forms[0];
form1.appendChild(x);
</code>

The problem is that if companyName had the value “Johnson & Johnson”. What would be displayed in the input text field would be “Johnson &amp; Johnson”. The appropriate encoding to use in the above case would be only JavaScript encoding to disallow an attacker from closing out the single quotes and in-lining code, or escaping to HTML and opening a new script tag.

===SAFE and FUNCTIONALLY CORRECT example===
<code>
var x = document.createElement("input");
x.setAttribute("name", "company_name");
x.setAttribute("value", '<%=Encoder.encodeForJS(companyName)%>');
var form1 = document.forms[0];
form1.appendChild(x);
</code>

It is important to note that when setting an HTML attribute which does not execute code, the value is set directly within the object attribute of the HTML element so there is no concerns with injecting up.

==RULE #3 - Be Careful when Inserting Untrusted Data into the Event Handler and JavaScript code Subcontexts within an Execution Context==

Putting dynamic data within JavaScript code is especially dangerous because JavaScript encoding has different semantics for JavaScript encoded data when compared to other encodings. In many cases, JavaScript encoding does not stop attacks within an execution context. For example, a JavaScript encoded string will execute even though it is JavaScript encoded.

Therefore, the primary recommendation is to <u>avoid including untrusted data in this context</u>. If you must, the following examples describe some approaches that do and do not work.

<code>
var x = document.createElement("a");
x.href="#";
// In the line of code below, the encoded data on the right (the second argument to setAttribute)
// is an example of untrusted data that was properly JavaScript encoded but still executes.
x.setAttribute("onclick", "\u0061\u006c\u0065\u0072\u0074\u0028\u0032\u0032\u0029");
var y = document.createTextNode("Click To Test");
x.appendChild(y);
document.body.appendChild(x);
</code>

The setAttribute(<i>name_string</i>,<i>value_string</i>) method is dangerous because it implicitly coerces the <i>value_string</i> into the DOM attribute datatype of <i>name_string</i>. In the case above, the attribute name is an JavaScript event handler, so the attribute value is implicitly converted to JavaScript code and evaluated. In the case above, JavaScript encoding does not mitigate against DOM based XSS. Other JavaScript methods which take code as a string types will have a similar problem as outline above (setTimeout, setInterval, new Function, etc.). This is in stark contrast to JavaScript encoding in the event handler attribute of a HTML tag (HTML parser) where JavaScript encoding mitigates against XSS.<br/>

<code>

<a id="bb" href="#" onclick="\u0061\u006c\u0065\u0072\u0074\u0028\u0031\u0029"> Test Me</a>
</code>

An alternative to using Element.setAttribute(...) to set DOM attributes is to set the attribute directly. Directly setting event handler attributes will allow JavaScript encoding to mitigate against DOM based XSS. Please note, it is always dangerous design to put untrusted data directly into a command execution context.<br/>

<code>
<a id="bb" href="#"> Test Me</a>
</code>
<code>
//The following does NOT work because the event handler is being set to a string. "alert(7)" is JavaScript encoded.
document.getElementById("bb").onclick = "\u0061\u006c\u0065\u0072\u0074\u0028\u0037\u0029";

//The following does NOT work because the event handler is being set to a string.
document.getElementById("bb").onmouseover = "testIt";

//The following does NOT work because of the encoded "(" and ")". "alert(77)" is JavaScript encoded.
document.getElementById("bb").onmouseover = \u0061\u006c\u0065\u0072\u0074\u0028\u0037\u0037\u0029;

//The following does NOT work because of the encoded ";". "testIt;testIt" is JavaScript encoded.
document.getElementById("bb").onmouseover = \u0074\u0065\u0073\u0074\u0049\u0074\u003b\u0074\u0065\u0073\u0074\u0049\u0074;

//The following DOES WORK because the encoded value is a valid variable name or function reference. "testIt" is JavaScript encoded
document.getElementById("bb").onmouseover = \u0074\u0065\u0073\u0074\u0049\u0074;

function testIt() {

alert("I was called.");
}

</code>

There are other places in JavaScript where JavaScript encoding is accepted as valid executable code.<br/>

<code>
for ( var \u0062=0; \u0062 < 10; \u0062++){
\u0064\u006f\u0063\u0075\u006d\u0065\u006e\u0074
.\u0077\u0072\u0069\u0074\u0065\u006c\u006e
("\u0048\u0065\u006c\u006c\u006f\u0020\u0057\u006f\u0072\u006c\u0064");
}
\u0077\u0069\u006e\u0064\u006f\u0077
.\u0065\u0076\u0061\u006c
\u0064\u006f\u0063\u0075\u006d\u0065\u006e\u0074
.\u0077\u0072\u0069\u0074\u0065(111111111);
</code>

or

<code>
var s = "\u0065\u0076\u0061\u006c";
var t = "\u0061\u006c\u0065\u0072\u0074\u0028\u0031\u0031\u0029";
window[s](t);
</code>

Because JavaScript is based on an international standard (ECMAScript), JavaScript encoding enables the support of international characters in programming constructs and variables in addition to alternate string representations (string escapes).

However the opposite is the case with HTML encoding. HTML tag elements are well defined and do not support alternate representations of the same tag. So HTML encoding cannot be used to allow the developer to have alternate representations of the <code><a></code> tag for example.

===HTML Encoding’s Disarming Nature===

In general, HTML encoding serves to castrate HTML tags which are placed in HTML and HTML attribute contexts.
Working example (no HTML encoding):

<code>
<a href="..." >
</code>

Normally encoded example (Does Not Work – DNW):

<code>
&#x3c;a href=... &#x3e;
</code>

HTML encoded example to highlight a fundamental difference with JavaScript encoded values (DNW):

<code>
<&#x61; href=...>
</code>

If HTML encoding followed the same semantics as JavaScript encoding. The line above could have possibily worked to render a link. This difference makes JavaScript encoding a less viable weapon in our fight against XSS.

==RULE #4 - JavaScript Escape Before Inserting Untrusted Data into the CSS Attribute Subcontext within the Execution Context==

Normally executing JavaScript from a CSS context required either passing <code>javascript:attackCode()</code> to the CSS url() method or invoking the CSS expression() method passing JavaScript code to be directly executed. From my experience, calling the expression() function from an execution context (JavaScript) has been disabled. In order to mitigate against the CSS url() method, ensure that you are URL encoding the data passed to the CSS url() method.

<code>
document.body.style.backgroundImage = "url(<%=Encoder.encodeForJS(Encoder.encodeForURL(companyName))%>)";
</code>

TODO: We have not been able to get the expression() function working from DOM JavaScript code. Need some help.

== RULE #5 - URL Escape then JavaScript Escape Before Inserting Untrusted Data into URL Attribute Subcontext within the Execution Context ==

The logic which parses URLs in both execution and rendering contexts looks to be the same. Therefore there is little change in the encoding rules for URL attributes in an execution (DOM) context.

var x = document.createElement("a");
x.setAttribute("href", '<%=Encoder.encodeForJS(Encoder.encodeForURL(userRelativePath))%>');
var y = document.createTextElement("Click Me To Test");
x.appendChild(y);
document.body.appendChild(x);

If you utilize fully qualified URLs then this will break the links as the colon in the protocol identifier (“http:” or “javascript:”) will be URL encoded preventing the “http” and “javascript” protocols from being invoked.

== RULE #6 - Populate the DOM using safe JavaScript functions or properties ==

The most fundamental safe way to populate the DOM with untrusted data is to use the safe assignment property, textContent. Here is an example of safe usage.

<code>
<script>
element.textContent = "<%=untrustedData%>"; //does not executes code
</script>
</code>

=Guidelines for Developing Secure Applications Utilizing JavaScript=

DOM based XSS is extremely difficult to mitigate against because of its large attack surface and lack of standardization across browsers. The guidelines below are an attempt to provide guidelines for developers when developing Web based JavaScript applications (Web 2.0) such that they can avoid XSS.

1. Untrusted data should only be treated as displayable text. Never treat untrusted data as code or markup within JavaScript code. <br/>
2. Always JavaScript encode and delimit untrusted data as quoted strings when entering the application (Jim Manico and Robert Hansen) <br/>
<code>
var x = "<%=encodedJavaScriptData%>";
</code>
3. Use <code>document.createElement("..."), element.setAttribute("...","value"), element.appendChild(...)</code>, etc. to build dynamic interfaces. Please note, element.setAttribute is only safe for a limited number of attributes. Dangerous attributes include any attribute that is a command execution context, such as onclick or onblur. Examples of safe attributes includes align, alink, alt, bgcolor, border, cellpadding, cellspacing, class, color, cols, colspan, coords, dir, face, height, hspace, ismap, lang, marginheight, marginwidth, multiple, nohref, noresize, noshade, nowrap, ref, rel, rev, rows, rowspan, scrolling, shape, span, summary, tabindex, title, usemap, valign, value, vlink, vspace, width.<br/>
4. Avoid use of HTML rendering methods:<br/>
#<code>element.innerHTML = "..."; </code>
#<code>element.outerHTML = "..."; </code>
#<code>document.write(...); </code>
#<code>document.writeln(...); </code><br/>
5. Understand the dataflow of untrusted data through your JavaScript code. If you do have to use the methods above remember to HTML and then JavaScript encode the untrusted data (Stefano Di Paola).<br/>
6. There are numerous methods which implicitly eval() data passed to it. Make sure that any untrusted data passed to these methods is delimited with string delimiters and enclosed within a closure or JavaScript encoded to N-levels based on usage, and wrapped in a custom function. Ensure to follow step 4 above to make sure that the untrusted data is not sent to dangerous methods within the custom function or handle it by adding an extra layer of encoding.<br/>

<b>Utilizing an Enclosure (as suggested by Gaz)</b>

The example that follows illustrates using closures to avoid double JavaScript encoding.

<code>
setTimeout((function(param) { return function() {
customFunction(param);
}
})("<%=Encoder.encodeForJS(untrustedData)%>"), y);
</code>

The other alternative is using N-levels of encoding.<br/>

<b>N-Levels of Encoding</b><br/>

If your code looked like the following, you would need to only double JavaScript encode input data.

<code>
setTimeout("customFunction('<%=doubleJavaScriptEncodedData%>', y)");
function customFunction (firstName, lastName)
alert("Hello" + firstName + " " + lastNam);
}
</code>

The <code>doubleJavaScriptEncodedData</code> has its first layer of JavaScript encoding reversed (upon execution) in the single quotes. Then the implicit <code>eval()</code> of <code>setTimeout()</code> reverses another layer of JavaScript encoding to pass the correct value to <code>customFunction</code>. The reason why you only need to double JavaScript encode is that the <code>customFunction</code> function did not itself pass the input to another method which implicitly or explicitly called <code>eval()</code>. If "firstName" was passed to another JavaScript method which implicitly or explicitly called eval() then <code><%=doubleJavaScriptEncodedData%></code> above would need to be changed to <code><%=tripleJavaScriptEncodedData%></code>.<br/>

An important implementation note is that if the JavaScript code tries to utilize the double or triple encoded data in string comparisons, the value may be interpreted as different values based on the number of evals() the data has passed through before being passed to the if comparison and the number of times the value was JavaScript encoded.<br/>

If "A" is double JavaScript encoded then the following if check will return false.<br/>

<code>
var x = "doubleJavaScriptEncodedA"; //\u005c\u0075\u0030\u0030\u0034\u0031
if (x == "A") {
alert("x is A");
} else if (x == "\u0041") {
alert("This is what pops");
}
</code>

This brings up an interesting design point. Ideally, the correct way to apply encoding and avoid the problem stated above is to server-side encode for the output context where data is introduced into the application. Then client-side encode (using a JavaScript encoding library such as ESAPI4JS) for the individual subcontext (DOM methods) which untrusted data is passed to. ESAPI4JS (located at http://bit.ly/9hRTLH) and jQuery Encoder (located at https://github.com/chrisisbeef/jquery-encoder/blob/master/src/main/javascript/org/owasp/esapi/jquery/encoder.js) are two client side encoding libraries developed by Chris Schmidt.<br/>
Here are some examples of how they are used:<br/>
<code>
var input = "<%=Encoder.encodeForJS(untrustedData)%>"; //server-side encoding
</code>
<code>
window.location = ESAPI4JS.encodeForURL(input); //URL encoding is happening in JavaScript
</code>
<code>
document.writeln(ESAPI4JS.encodeForHTML(input)); //HTML encoding is happening in JavaScript
</code>

It has been well noted by the group that any kind of reliance on a JavaScript library for encoding would be problematic as the JavaScript library could be subverted by attackers. One option is to wait till ECMAScript 5 so the JavaScript library could support immutable properties.<br/>
Another option provided by Gaz (Gareth) was to use a specific code construct to limit mutability with anonymous clousures.<br/>

An example follows:<br/>

<code>
function escapeHTML(str) {
str = str + "''";
var out = "''";
for(var i=0; i<str.length; i++) {
if(str[i] === '<') {
out += '&lt;';
} else if(str[i] === '>') {
out += '&gt;';
} else if(str[i] === "'") {
out += '&#39;';
} else if(str[i] === '"') {
out += '&quot;';
} else {
out += str[i];
}
}
return out;
}
</code>

<br/>Chris Schmidt has put together another implementation of a JavaScript encoder at http://yet-another-dev.blogspot.com/2011/02/client-side-contextual-encoding-for.html. <br/>

6. Limit the usage of dynamic untrusted data to right side operations. And be aware of data which may be passed to the application which look like code (eg. <code>location</code>, <code>eval()</code>). (Achim)<br/>
<code>
var x = "<%=properly encoded data for flow%>";
</code>

If you want to change different object attributes based on user input use a level of indirection.<br/>

Instead of: <br/>

<code>
window[userData] = "moreUserData";
</code>

Do the following instead:<br/>
<code>
if (userData==="location") {
window.location = "static/path/or/properly/url/encoded/value";
}
</code>

7. When URL encoding in DOM be aware of character set issues as the character set in JavaScript DOM is not clearly defined (Mike Samuel).<br/>

8. Limit access to properties objects when using object[x] accessors. (Mike Samuel). In other words use a level of indirection between untrusted input and specified object properties.<br/>
Here is an example of the problem when using map types:<br/>
<code>
var myMapType = {};
myMapType[<%=untrustedData%>] = "moreUntrustedData";
</code>

Although the developer writing the code above was trying to add additional keyed elements to the <code>myMapType</code> object. This could be used by an attacker to subvert internal and external attributes of the <code>myMapType</code> object.<br/>

9. Run your JavaScript in a ECMAScript 5 canopy or sand box to make it harder for your JavaScript API to be compromised (Gareth Heyes and John Stevens).<br/>

10. Don’t <code>eval()</code> JSON to convert it to native JavaScript objects. Instead use <code>JSON.toJSON()</code> and <code>JSON.parse()</code> (Chris Schmidt).

= Common Problems Associated with Mitigating DOM Based XSS =
==Complex Contexts==
In many cases the context isn’t always straightforward to discern.<br/>
<code>
<a href="javascript:myFunction('<%=untrustedData%>', 'test');">Click Me</a>
...
<script>
Function myFunction (url,name) {
window.location = url;
}
</script>
</code>

In the above example, untrusted data started in the rendering URL context (<code>href</code> attribute of an <code><a></code> tag) then changed to a JavaScript execution context (<code>javascript:</code> protocol handler) which passed the untrusted data to an execution URL subcontext (<code>window.location</code> of myFunction). Because the data was introduced in JavaScript code and passed to a URL subcontext the appropriate server-side encoding would be the following:<br/>

<code>
<a href="javascript:myFunction('<%=Encoder.encodeForJS( ↩
Encoder.encodeForURL(untrustedData))%>', 'test');">Click Me</a>
...
</code>

Or if you were using ECMAScript 5 with an immutable JavaScript client-side encoding libraries you could do the following:<br/>

<code>

<a href="javascript:myFunction('<%=Encoder.encodeForJS(untrustedData)%>', 'test');">Click Me</a>
...
<script>
Function myFunction (url,name) {
var encodedURL = ESAPI4JS.encodeForURL(url); //URL encoding using client-side scripts
window.location = encodedURL;
}
</script>
</code>

== Inconsistencies of Encoding Libraries ==
There are a number of open source encoding libraries out there:<br/>

#[[ESAPI]]
#Apache Commons String Utils
#Jtidy
#Your company’s custom implementation.

Some work on a black list while others ignore important characters like “<” and “>”. ESAPI is one of the few which works on a whitelist and encodes all non-alphanumeric characters.
It is important to use an encoding library that understands which characters can be used to exploit vulnerabilies in their respective contexts. Misconceptions abound related to the proper encoding that is required.

==Encoding Misconceptions==
Many security training curriculums and papers advocate the blind usage of HTML encoding to resolve XSS. This logically seems to be prudent advice as the JavaScript parser does not understand HTML encoding. However, if the pages returned from your web application utilize a content type of “text/xhtml” or the file type extension of “*.xhtml” then HTML encoding may not work to mitigate against XSS.<br/>

For example: <br/>

<code>
<script>
&#x61;lert(1);
</script>
</code>

The HTML encoded value above is still executable. If that isn’t enough to keep in mind, you have to remember that encodings are lost when you retrieve them using the value attribute of a DOM element. <br/>

Let’s look at the sample page and script:<br/>

<code>
<form name="myForm" ...>
<input type="text" name="lName" value="<%=Encoder.encodeForHTML(last_name)%>">
...
</form>
<script>
var x = document.myForm.lName.value; //when the value is retrieved the encoding is reversed
document.writeln(x); //any code passed into lName is now executable.
</script>
</code>

Finally there is the problem that certain methods in JavaScript which are usually safe can be unsafe in certain contexts.<br/>

==Usually Safe Methods==

One example of an attribute which is thought to be safe is innerText. Some papers or guides advocate its use as an alternative to innerHTML to mitigate against XSS in innerHTML. However, depending on the tag which innerText is applied, code can be executed. Also note, innerText is non standard and is not supported in FireFox<br/>

<code>
<script>
var tag = document.createElement("script");
tag.innerText = "<%=untrustedData%>"; //executes code
</script>
</code>

= Authors and Contributing Editors =

Jim Manico - jim[at]owasp.org<br/>
Abraham Kang - abraham.kang[at]owasp.org<br/>
Gareth (Gaz) Heyes<br/>
Stefano Di Paola<br/>
Achim Hoffmann - achim[at]owasp.org<br/>
Robert (RSnake) Hansen<br/>
Mario Heiderich<br/>
John Steven<br/>
Chris (Chris BEEF) Schmidt<br/>
Mike Samuel<br/>
Jeremy Long<br/>
Eduardo (SirDarkCat) Alberto Vela Nava<br/>
Jeff Williams - jeff.williams[at]owasp.org <br/>
Erlend Oftedal
| valign="top" style="padding-left:25px;width:300px;border-right: 1px dotted gray;padding-right:25px;" |

== Other Cheatsheets ==

{{Cheatsheet_Navigation_Body}}

|}

[[Category:Cheatsheets]]

DOM based XSS Prevention Cheat Sheet

2016-06-29T10:06:08Z

Yozo: garbage removed.

__NOTOC__
<div style="width:100%;height:160px;border:0,margin:0;overflow: hidden;">[[File:Cheatsheets-header.jpg|link=]]</div>

{| style="padding: 0;margin:0;margin-top:10px;text-align:left;" |-
| valign="top" style="border-right: 1px dotted gray;padding-right:25px;" |
Last revision (mm/dd/yy): '''{{REVISIONMONTH}}/{{REVISIONDAY}}/{{REVISIONYEAR}}'''
= Introduction =
__TOC__{{TOC hidden}}

When looking at XSS (Cross-Site Scripting), there are three generally recognized forms of [[XSS]]. [[XSS#Stored_and_Reflected_XSS_Attacks | Reflected, Stored]], and [[DOM Based XSS]]. The [[XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet | XSS Prevention Cheatsheet]] does an excellent job of addressing Reflected and Stored XSS. This cheatsheet addresses DOM (Document Object Model) based XSS and is an extension (and assumes comprehension of) the [[XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet | XSS Prevention Cheatsheet]].

In order to understand DOM based XSS, one needs to see the fundamental difference between Reflected and Stored XSS when compared to DOM based XSS. The primary difference is where the attack is injected into the application. Reflected and Stored XSS are server side injection issues while DOM based XSS is a client (browser) side injection issue. All of this code originates on the server, which means it is the application owner's responsibility to make it safe from XSS, regardless of the type of XSS flaw it is. Also, XSS attacks always <b>execute</b> in the browser. The difference between Reflected/Stored XSS is where the attack is added or injected into the application. With Reflected/Stored the attack is injected into the application during server-side processing of requests where untrusted input is dynamically added to HTML. For DOM XSS, the attack is injected into the application during runtime in the client directly.

When a browser is rendering HTML and any other associated content like CSS, JavaScript, etc. it identifies various rendering contexts for the different kinds of input and follows different rules for each context. A rendering context is associated with the parsing of HTML tags and their attributes. The HTML parser of the rendering context dictates how data is presented and laid out on the page and can be further broken down into the standard contexts of HTML, HTML attribute, URL, and CSS. The JavaScript or VBScript parser of an execution context is associated with the parsing and execution of script code. Each parser has distinct and separate semantics in the way they can possibly execute script code which make creating consistent rules for mitigating vulnerabilities in various contexts difficult. The complication is compounded by the differing meanings and treatment of encoded values within each subcontext (HTML, HTML attribute, URL, and CSS) within the execution context.

For the purposes of this article, we refer to the HTML, HTML attribute, URL, and CSS contexts as subcontexts because each of these contexts can be reached and set within a JavaScript execution context. In JavaScript code, the main context is JavaScript but with the right tags and context closing characters, an attacker can try to attack the other 4 contexts using equivalent JavaScript DOM methods.<br/>

The following is an example vulnerability which occurs in the JavaScript context and HTML subcontext:<br/>

<code>
<script>
var x = '<%= taintedVar %>';
var d = document.createElement('div');
d.innerHTML = x;
document.body.appendChild(d);
</script>
</code>

Let’s look at the individual subcontexts of the execution context in turn.

==RULE #1 - HTML Escape then JavaScript Escape Before Inserting Untrusted Data into HTML Subcontext within the Execution Context==

There are several methods and attributes which can be used to directly render HTML content within JavaScript. These methods constitute the HTML Subcontext within the Execution Context. If these methods are provided with untrusted input, then an XSS vulnerability could result. For example:

===Example Dangerous HTML Methods===
====Attributes====
<code>
element.innerHTML = "<HTML> Tags and markup";
element.outerHTML = "<HTML> Tags and markup";
</code>

====Methods====
<code>
document.write("<HTML> Tags and markup");
document.writeln("<HTML> Tags and markup");
</code>

===Guideline===
To make dynamic updates to HTML in the DOM safe, we recommend a) HTML encoding, and then b) JavaScript encoding all untrusted input, as shown in these examples:

<code>
element.innerHTML = "<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>";
element.outerHTML = "<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>";
</code>

<code>
document.write("<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>");
document.writeln("<%=Encoder.encodeForJS(Encoder.encodeForHTML(untrustedData))%>");
</code>

Note: The Encoder.encodeForHTML() and Encoder.encodeForJS() are just notional encoders. Various options for actual encoders are listed later in this document.

== RULE #2 - JavaScript Escape Before Inserting Untrusted Data into HTML Attribute Subcontext within the Execution Context ==

The HTML attribute *subcontext* within the *execution* context is divergent from the standard encoding rules. This is because the rule to HTML attribute encode in an HTML attribute rendering context is necessary in order to mitigate attacks which try to exit out of an HTML attributes or try to add additional attributes which could lead to XSS. When you are in a DOM execution context you only need to JavaScript encode HTML attributes which do not execute code (attributes other than event handler, CSS, and URL attributes).

For example, the general rule is to HTML Attribute encode untrusted data (data from the database, HTTP request, user, back-end system, etc.) placed in an HTML Attribute. This is the appropriate step to take when outputting data in a rendering context, however using HTML Attribute encoding in an execution context will break the application display of data.

=== SAFE but BROKEN example===
<code>
var x = document.createElement("input");
x.setAttribute("name", "company_name");
// In the following line of code, companyName represents untrusted user input
// The Encoder.encodeForHTMLAttr() is unnecessary and causes double-encoding
x.setAttribute("value", '<%=Encoder.encodeForJS(Encoder.encodeForHTMLAttr(companyName))%>');
var form1 = document.forms[0];
form1.appendChild(x);
</code>

The problem is that if companyName had the value “Johnson & Johnson”. What would be displayed in the input text field would be “Johnson &amp; Johnson”. The appropriate encoding to use in the above case would be only JavaScript encoding to disallow an attacker from closing out the single quotes and in-lining code, or escaping to HTML and opening a new script tag.

===SAFE and FUNCTIONALLY CORRECT example===
<code>
var x = document.createElement("input");
x.setAttribute("name", "company_name");
x.setAttribute("value", '<%=Encoder.encodeForJS(companyName)%>');
var form1 = document.forms[0];
form1.appendChild(x);
</code>

It is important to note that when setting an HTML attribute which does not execute code, the value is set directly within the object attribute of the HTML element so there is no concerns with injecting up.

==RULE #3 - Be Careful when Inserting Untrusted Data into the Event Handler and JavaScript code Subcontexts within an Execution Context==

Putting dynamic data within JavaScript code is especially dangerous because JavaScript encoding has different semantics for JavaScript encoded data when compared to other encodings. In many cases, JavaScript encoding does not stop attacks within an execution context. For example, a JavaScript encoded string will execute even though it is JavaScript encoded.

Therefore, the primary recommendation is to <u>avoid including untrusted data in this context</u>. If you must, the following examples describe some approaches that do and do not work.

<code>
var x = document.createElement("a");
x.href="#";
// In the line of code below, the encoded data on the right (the second argument to setAttribute)
// is an example of untrusted data that was properly JavaScript encoded but still executes.
x.setAttribute("onclick", "\u0061\u006c\u0065\u0072\u0074\u0028\u0032\u0032\u0029");
var y = document.createTextNode("Click To Test");
x.appendChild(y);
document.body.appendChild(x);
</code>

The setAttribute(<i>name_string</i>,<i>value_string</i>) method is dangerous because it implicitly coerces the <i>string_value</i> into the DOM attribute datatype of <i>name_string</i>. In the case above, the attribute name is an JavaScript event handler, so the attribute value is implicitly converted to JavaScript code and evaluated. In the case above, JavaScript encoding does not mitigate against DOM based XSS. Other JavaScript methods which take code as a string types will have a similar problem as outline above (setTimeout, setInterval, new Function, etc.). This is in stark contrast to JavaScript encoding in the event handler attribute of a HTML tag (HTML parser) where JavaScript encoding mitigates against XSS.<br/>

<code>

<a id="bb" href="#" onclick="\u0061\u006c\u0065\u0072\u0074\u0028\u0031\u0029"> Test Me</a>
</code>

An alternative to using Element.setAttribute(...) to set DOM attributes is to set the attribute directly. Directly setting event handler attributes will allow JavaScript encoding to mitigate against DOM based XSS. Please note, it is always dangerous design to put untrusted data directly into a command execution context.<br/>

<code>
<a id="bb" href="#"> Test Me</a>
</code>
<code>
//The following does NOT work because the event handler is being set to a string. "alert(7)" is JavaScript encoded.
document.getElementById("bb").onclick = "\u0061\u006c\u0065\u0072\u0074\u0028\u0037\u0029";

//The following does NOT work because the event handler is being set to a string.
document.getElementById("bb").onmouseover = "testIt";

//The following does NOT work because of the encoded "(" and ")". "alert(77)" is JavaScript encoded.
document.getElementById("bb").onmouseover = \u0061\u006c\u0065\u0072\u0074\u0028\u0037\u0037\u0029;

//The following does NOT work because of the encoded ";". "testIt;testIt" is JavaScript encoded.
document.getElementById("bb").onmouseover = \u0074\u0065\u0073\u0074\u0049\u0074\u003b\u0074\u0065\u0073\u0074\u0049\u0074;

//The following DOES WORK because the encoded value is a valid variable name or function reference. "testIt" is JavaScript encoded
document.getElementById("bb").onmouseover = \u0074\u0065\u0073\u0074\u0049\u0074;

function testIt() {

alert("I was called.");
}

</code>

There are other places in JavaScript where JavaScript encoding is accepted as valid executable code.<br/>

<code>
for ( var \u0062=0; \u0062 < 10; \u0062++){
\u0064\u006f\u0063\u0075\u006d\u0065\u006e\u0074
.\u0077\u0072\u0069\u0074\u0065\u006c\u006e
("\u0048\u0065\u006c\u006c\u006f\u0020\u0057\u006f\u0072\u006c\u0064");
}
\u0077\u0069\u006e\u0064\u006f\u0077
.\u0065\u0076\u0061\u006c
\u0064\u006f\u0063\u0075\u006d\u0065\u006e\u0074
.\u0077\u0072\u0069\u0074\u0065(111111111);
</code>

or

<code>
var s = "\u0065\u0076\u0061\u006c";
var t = "\u0061\u006c\u0065\u0072\u0074\u0028\u0031\u0031\u0029";
window[s](t);
</code>

Because JavaScript is based on an international standard (ECMAScript), JavaScript encoding enables the support of international characters in programming constructs and variables in addition to alternate string representations (string escapes).

However the opposite is the case with HTML encoding. HTML tag elements are well defined and do not support alternate representations of the same tag. So HTML encoding cannot be used to allow the developer to have alternate representations of the <code><a></code> tag for example.

===HTML Encoding’s Disarming Nature===

In general, HTML encoding serves to castrate HTML tags which are placed in HTML and HTML attribute contexts.
Working example (no HTML encoding):

<code>
<a href="..." >
</code>

Normally encoded example (Does Not Work – DNW):

<code>
&#x3c;a href=... &#x3e;
</code>

HTML encoded example to highlight a fundamental difference with JavaScript encoded values (DNW):

<code>
<&#x61; href=...>
</code>

If HTML encoding followed the same semantics as JavaScript encoding. The line above could have possibily worked to render a link. This difference makes JavaScript encoding a less viable weapon in our fight against XSS.

==RULE #4 - JavaScript Escape Before Inserting Untrusted Data into the CSS Attribute Subcontext within the Execution Context==

Normally executing JavaScript from a CSS context required either passing <code>javascript:attackCode()</code> to the CSS url() method or invoking the CSS expression() method passing JavaScript code to be directly executed. From my experience, calling the expression() function from an execution context (JavaScript) has been disabled. In order to mitigate against the CSS url() method, ensure that you are URL encoding the data passed to the CSS url() method.

<code>
document.body.style.backgroundImage = "url(<%=Encoder.encodeForJS(Encoder.encodeForURL(companyName))%>)";
</code>

TODO: We have not been able to get the expression() function working from DOM JavaScript code. Need some help.

== RULE #5 - URL Escape then JavaScript Escape Before Inserting Untrusted Data into URL Attribute Subcontext within the Execution Context ==

The logic which parses URLs in both execution and rendering contexts looks to be the same. Therefore there is little change in the encoding rules for URL attributes in an execution (DOM) context.

var x = document.createElement("a");
x.setAttribute("href", '<%=Encoder.encodeForJS(Encoder.encodeForURL(userRelativePath))%>');
var y = document.createTextElement("Click Me To Test");
x.appendChild(y);
document.body.appendChild(x);

If you utilize fully qualified URLs then this will break the links as the colon in the protocol identifier (“http:” or “javascript:”) will be URL encoded preventing the “http” and “javascript” protocols from being invoked.

== RULE #6 - Populate the DOM using safe JavaScript functions or properties ==

The most fundamental safe way to populate the DOM with untrusted data is to use the safe assignment property, textContent. Here is an example of safe usage.

<code>
<script>
element.textContent = "<%=untrustedData%>"; //does not executes code
</script>
</code>

=Guidelines for Developing Secure Applications Utilizing JavaScript=

DOM based XSS is extremely difficult to mitigate against because of its large attack surface and lack of standardization across browsers. The guidelines below are an attempt to provide guidelines for developers when developing Web based JavaScript applications (Web 2.0) such that they can avoid XSS.

1. Untrusted data should only be treated as displayable text. Never treat untrusted data as code or markup within JavaScript code. <br/>
2. Always JavaScript encode and delimit untrusted data as quoted strings when entering the application (Jim Manico and Robert Hansen) <br/>
<code>
var x = "<%=encodedJavaScriptData%>";
</code>
3. Use <code>document.createElement("..."), element.setAttribute("...","value"), element.appendChild(...)</code>, etc. to build dynamic interfaces. Please note, element.setAttribute is only safe for a limited number of attributes. Dangerous attributes include any attribute that is a command execution context, such as onclick or onblur. Examples of safe attributes includes align, alink, alt, bgcolor, border, cellpadding, cellspacing, class, color, cols, colspan, coords, dir, face, height, hspace, ismap, lang, marginheight, marginwidth, multiple, nohref, noresize, noshade, nowrap, ref, rel, rev, rows, rowspan, scrolling, shape, span, summary, tabindex, title, usemap, valign, value, vlink, vspace, width.<br/>
4. Avoid use of HTML rendering methods:<br/>
#<code>element.innerHTML = "..."; </code>
#<code>element.outerHTML = "..."; </code>
#<code>document.write(...); </code>
#<code>document.writeln(...); </code><br/>
5. Understand the dataflow of untrusted data through your JavaScript code. If you do have to use the methods above remember to HTML and then JavaScript encode the untrusted data (Stefano Di Paola).<br/>
6. There are numerous methods which implicitly eval() data passed to it. Make sure that any untrusted data passed to these methods is delimited with string delimiters and enclosed within a closure or JavaScript encoded to N-levels based on usage, and wrapped in a custom function. Ensure to follow step 4 above to make sure that the untrusted data is not sent to dangerous methods within the custom function or handle it by adding an extra layer of encoding.<br/>

<b>Utilizing an Enclosure (as suggested by Gaz)</b>

The example that follows illustrates using closures to avoid double JavaScript encoding.

<code>
setTimeout((function(param) { return function() {
customFunction(param);
}
})("<%=Encoder.encodeForJS(untrustedData)%>"), y);
</code>

The other alternative is using N-levels of encoding.<br/>

<b>N-Levels of Encoding</b><br/>

If your code looked like the following, you would need to only double JavaScript encode input data.

<code>
setTimeout("customFunction('<%=doubleJavaScriptEncodedData%>', y)");
function customFunction (firstName, lastName)
alert("Hello" + firstName + " " + lastNam);
}
</code>

The <code>doubleJavaScriptEncodedData</code> has its first layer of JavaScript encoding reversed (upon execution) in the single quotes. Then the implicit <code>eval()</code> of <code>setTimeout()</code> reverses another layer of JavaScript encoding to pass the correct value to <code>customFunction</code>. The reason why you only need to double JavaScript encode is that the <code>customFunction</code> function did not itself pass the input to another method which implicitly or explicitly called <code>eval()</code>. If "firstName" was passed to another JavaScript method which implicitly or explicitly called eval() then <code><%=doubleJavaScriptEncodedData%></code> above would need to be changed to <code><%=tripleJavaScriptEncodedData%></code>.<br/>

An important implementation note is that if the JavaScript code tries to utilize the double or triple encoded data in string comparisons, the value may be interpreted as different values based on the number of evals() the data has passed through before being passed to the if comparison and the number of times the value was JavaScript encoded.<br/>

If "A" is double JavaScript encoded then the following if check will return false.<br/>

<code>
var x = "doubleJavaScriptEncodedA"; //\u005c\u0075\u0030\u0030\u0034\u0031
if (x == "A") {
alert("x is A");
} else if (x == "\u0041") {
alert("This is what pops");
}
</code>

This brings up an interesting design point. Ideally, the correct way to apply encoding and avoid the problem stated above is to server-side encode for the output context where data is introduced into the application. Then client-side encode (using a JavaScript encoding library such as ESAPI4JS) for the individual subcontext (DOM methods) which untrusted data is passed to. ESAPI4JS (located at http://bit.ly/9hRTLH) and jQuery Encoder (located at https://github.com/chrisisbeef/jquery-encoder/blob/master/src/main/javascript/org/owasp/esapi/jquery/encoder.js) are two client side encoding libraries developed by Chris Schmidt.<br/>
Here are some examples of how they are used:<br/>
<code>
var input = "<%=Encoder.encodeForJS(untrustedData)%>"; //server-side encoding
</code>
<code>
window.location = ESAPI4JS.encodeForURL(input); //URL encoding is happening in JavaScript
</code>
<code>
document.writeln(ESAPI4JS.encodeForHTML(input)); //HTML encoding is happening in JavaScript
</code>

It has been well noted by the group that any kind of reliance on a JavaScript library for encoding would be problematic as the JavaScript library could be subverted by attackers. One option is to wait till ECMAScript 5 so the JavaScript library could support immutable properties.<br/>
Another option provided by Gaz (Gareth) was to use a specific code construct to limit mutability with anonymous clousures.<br/>

An example follows:<br/>

<code>
function escapeHTML(str) {
str = str + "''";
var out = "''";
for(var i=0; i<str.length; i++) {
if(str[i] === '<') {
out += '&lt;';
} else if(str[i] === '>') {
out += '&gt;';
} else if(str[i] === "'") {
out += '&#39;';
} else if(str[i] === '"') {
out += '&quot;';
} else {
out += str[i];
}
}
return out;
}
</code>

<br/>Chris Schmidt has put together another implementation of a JavaScript encoder at http://yet-another-dev.blogspot.com/2011/02/client-side-contextual-encoding-for.html. <br/>

6. Limit the usage of dynamic untrusted data to right side operations. And be aware of data which may be passed to the application which look like code (eg. <code>location</code>, <code>eval()</code>). (Achim)<br/>
<code>
var x = "<%=properly encoded data for flow%>";
</code>

If you want to change different object attributes based on user input use a level of indirection.<br/>

Instead of: <br/>

<code>
window[userData] = "moreUserData";
</code>

Do the following instead:<br/>
<code>
if (userData==="location") {
window.location = "static/path/or/properly/url/encoded/value";
}
</code>

7. When URL encoding in DOM be aware of character set issues as the character set in JavaScript DOM is not clearly defined (Mike Samuel).<br/>

8. Limit access to properties objects when using object[x] accessors. (Mike Samuel). In other words use a level of indirection between untrusted input and specified object properties.<br/>
Here is an example of the problem when using map types:<br/>
<code>
var myMapType = {};
myMapType[<%=untrustedData%>] = "moreUntrustedData";
</code>

Although the developer writing the code above was trying to add additional keyed elements to the <code>myMapType</code> object. This could be used by an attacker to subvert internal and external attributes of the <code>myMapType</code> object.<br/>

9. Run your JavaScript in a ECMAScript 5 canopy or sand box to make it harder for your JavaScript API to be compromised (Gareth Heyes and John Stevens).<br/>

10. Don’t <code>eval()</code> JSON to convert it to native JavaScript objects. Instead use <code>JSON.toJSON()</code> and <code>JSON.parse()</code> (Chris Schmidt).

= Common Problems Associated with Mitigating DOM Based XSS =
==Complex Contexts==
In many cases the context isn’t always straightforward to discern.<br/>
<code>
<a href="javascript:myFunction('<%=untrustedData%>', 'test');">Click Me</a>
...
<script>
Function myFunction (url,name) {
window.location = url;
}
</script>
</code>

In the above example, untrusted data started in the rendering URL context (<code>href</code> attribute of an <code><a></code> tag) then changed to a JavaScript execution context (<code>javascript:</code> protocol handler) which passed the untrusted data to an execution URL subcontext (<code>window.location</code> of myFunction). Because the data was introduced in JavaScript code and passed to a URL subcontext the appropriate server-side encoding would be the following:<br/>

<code>
<a href="javascript:myFunction('<%=Encoder.encodeForJS( ↩
Encoder.encodeForURL(untrustedData))%>', 'test');">Click Me</a>
...
</code>

Or if you were using ECMAScript 5 with an immutable JavaScript client-side encoding libraries you could do the following:<br/>

<code>

<a href="javascript:myFunction('<%=Encoder.encodeForJS(untrustedData)%>', 'test');">Click Me</a>
...
<script>
Function myFunction (url,name) {
var encodedURL = ESAPI4JS.encodeForURL(url); //URL encoding using client-side scripts
window.location = encodedURL;
}
</script>
</code>

== Inconsistencies of Encoding Libraries ==
There are a number of open source encoding libraries out there:<br/>

#[[ESAPI]]
#Apache Commons String Utils
#Jtidy
#Your company’s custom implementation.

Some work on a black list while others ignore important characters like “<” and “>”. ESAPI is one of the few which works on a whitelist and encodes all non-alphanumeric characters.
It is important to use an encoding library that understands which characters can be used to exploit vulnerabilies in their respective contexts. Misconceptions abound related to the proper encoding that is required.

==Encoding Misconceptions==
Many security training curriculums and papers advocate the blind usage of HTML encoding to resolve XSS. This logically seems to be prudent advice as the JavaScript parser does not understand HTML encoding. However, if the pages returned from your web application utilize a content type of “text/xhtml” or the file type extension of “*.xhtml” then HTML encoding may not work to mitigate against XSS.<br/>

For example: <br/>

<code>
<script>
&#x61;lert(1);
</script>
</code>

The HTML encoded value above is still executable. If that isn’t enough to keep in mind, you have to remember that encodings are lost when you retrieve them using the value attribute of a DOM element. <br/>

Let’s look at the sample page and script:<br/>

<code>
<form name="myForm" ...>
<input type="text" name="lName" value="<%=Encoder.encodeForHTML(last_name)%>">
...
</form>
<script>
var x = document.myForm.lName.value; //when the value is retrieved the encoding is reversed
document.writeln(x); //any code passed into lName is now executable.
</script>
</code>

Finally there is the problem that certain methods in JavaScript which are usually safe can be unsafe in certain contexts.<br/>

==Usually Safe Methods==

One example of an attribute which is thought to be safe is innerText. Some papers or guides advocate its use as an alternative to innerHTML to mitigate against XSS in innerHTML. However, depending on the tag which innerText is applied, code can be executed. Also note, innerText is non standard and is not supported in FireFox<br/>

<code>
<script>
var tag = document.createElement("script");
tag.innerText = "<%=untrustedData%>"; //executes code
</script>
</code>

= Authors and Contributing Editors =

Jim Manico - jim[at]owasp.org<br/>
Abraham Kang - abraham.kang[at]owasp.org<br/>
Gareth (Gaz) Heyes<br/>
Stefano Di Paola<br/>
Achim Hoffmann - achim[at]owasp.org<br/>
Robert (RSnake) Hansen<br/>
Mario Heiderich<br/>
John Steven<br/>
Chris (Chris BEEF) Schmidt<br/>
Mike Samuel<br/>
Jeremy Long<br/>
Eduardo (SirDarkCat) Alberto Vela Nava<br/>
Jeff Williams - jeff.williams[at]owasp.org <br/>
Erlend Oftedal
| valign="top" style="padding-left:25px;width:300px;border-right: 1px dotted gray;padding-right:25px;" |

== Other Cheatsheets ==

{{Cheatsheet_Navigation_Body}}

|}

[[Category:Cheatsheets]]

Clickjacking Defense Cheat Sheet

2016-06-29T08:59:05Z

Yozo: typo(symantics)

<div style="width:100%;height:160px;border:0,margin:0;overflow: hidden;">[[File:Cheatsheets-header.jpg|link=]]</div>
<br/>Last revision (mm/dd/yy): '''{{REVISIONMONTH}}/{{REVISIONDAY}}/{{REVISIONYEAR}}'''
= Introduction =
__TOC__{{TOC hidden}}

This cheat sheet is focused on providing developer guidance on [[Clickjacking|Clickjack/UI Redress]] attack prevention.

The most popular way to defend against Clickjacking is to include some sort of "frame-breaking" functionality which prevents other web pages from framing the site you wish to defend. This cheat sheet will discuss two methods of implementing frame-breaking: first is X-Frame-Options headers (used if the browser supports the functionality); and second is javascript frame-breaking code.

= Defending with Content Security Policy frame-ancestors directive =
The frame-ancestors directive can be used in a Content-Security-Policy HTTP response header to indicate whether or not a browser should be allowed to render a page in a <frame> or <iframe>. Sites can use this to avoid Clickjacking attacks, by ensuring that their content is not embedded into other sites.

frame-ancestors allows a site to authorize multiple domains using the normal Content Security Policy semantics.

See https://w3c.github.io/webappsec-csp/document/#directive-frame-ancestors for further details

=== Limitations ===
* '''Browser support:''' frame-ancestors is not supported by all the major browsers yet.
* '''X-Frame-Options takes priority:''' [https://w3c.github.io/webappsec/specs/content-security-policy/#frame-ancestors-and-frame-options Section 7.7.1 of the CSP Spec] says X-Frame-Options should be ignored if frame-ancestors is specified, but Chrome 40 & Firefox 35 ignore the frame-ancestors directive and follow the X-Frame-Options header instead.

= Defending with X-Frame-Options Response Headers =

The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a <frame> or <iframe>. Sites can use this to avoid Clickjacking attacks, by ensuring that their content is not embedded into other sites.

Set the x-frame-options header for all responses containing HTML content. The possible values are "DENY" or "SAMEORIGIN".

DENY will block any site (regardless of domain) from framing the content.
SAMEORIGIN will block all sites from framing the content, except sites within the same domain.

=== X-Frame-Options Header Types ===

There are three possible values for the X-Frame-Options header:
* <b>DENY</b>, which prevents any domain from framing the content. The "DENY" setting is recommended unless a specific need has been identified for framing.
* <b>SAMEORIGIN</b>, which only allows the current site to frame the content.
* <b>ALLOW-FROM uri</b>, which permits the specified 'uri' to frame this page. (e.g., ALLOW-FROM http://www.example.com) '''Check Limitations Below''' this will fail open if the browser does not support it.

=== Browser Support ===

The following browsers support X-Frame-Options headers.

<table border="1">
<tr> <th>Browser</th> <th>DENY/SAMEORIGIN Support Introduced</th> <th>ALLOW-FROM Support Introduced</th></tr>
<tr> <td>Chrome</td> <td>[http://blog.chromium.org/2010/01/security-in-depth-new-security-features.html 4.1.249.1042]</td>
<td>[https://code.google.com/p/chromium/issues/detail?id=129139 Not supported/Bug reported]</td> </tr>
<tr> <td>Firefox (Gecko)</td> <td>[https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options?redirectlocale=en-US&redirectslug=The_X-FRAME-OPTIONS_response_header 3.6.9 (1.9.2.9)]</td> <td>[https://bugzilla.mozilla.org/show_bug.cgi?id=690168 18.0]</td></tr>
<tr> <td>Internet Explorer</td> <td>[http://blogs.msdn.com/b/ie/archive/2009/01/27/ie8-security-part-vii-clickjacking-defenses.aspx 8.0]</td> <td>[http://erlend.oftedal.no/blog/tools/xframeoptions/ 9.0]</td> </tr>
<tr> <td>Opera</td> <td>[http://www.opera.com/docs/specs/presto26/#network 10.50]</td> <td></td> </tr>
<tr> <td>Safari</td> <td>[http://www.zdnet.com/blog/security/apple-safari-jumbo-patch-50-vulnerabilities-fixed/3541 4.0]</td><td>[https://bugs.webkit.org/show_bug.cgi?id=94836 Not supported/Bug reported]</td> </tr>
</table>

References:
* [https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options Mozilla Developer Network]<br>
* [http://datatracker.ietf.org/doc/draft-ietf-websec-x-frame-options/ IETF Draft]
* [http://erlend.oftedal.no/blog/tools/xframeoptions/ X-Frame-Options Compatibility Test] - Check this for the LATEST browser support info for the X-Frame-Options header

=== Implementation ===

To implement this protection, you need to add the X-Frame-Options HTTP Response header to any page that you want to protect from being clickjacked via framebusting. One way to do this is to add the HTTP Response Header manually to every page. A possibly simpler way is to implement a filter that automatically adds the header to every page.

OWASP has an [[ClickjackFilter for Java EE|article and some code]] that provides all the details for implementing this in the Java EE environment.

The SDL blog has posted an [http://blogs.msdn.com/sdl/archive/2009/02/05/clickjacking-defense-in-ie8.aspx article] covering how to implement this in a .NET environment.

=== Common Defense Mistakes ===
Meta-tags that attempt to apply the X-Frame-Options directive DO NOT WORK. For example, <meta http-equiv="X-Frame-Options" content="deny">) will not work. You must apply the X-FRAME-OPTIONS directive as HTTP Response Header as described above.

=== Limitations ===

* '''Per-page policy specification''' The policy needs to be specified for every page, which can complicate deployment. Providing the ability to enforce it for the entire site, at login time for instance, could simplify adoption.
* '''Problems with multi-domain sites''' The current implementation does not allow the webmaster to provide a whitelist of domains that are allowed to frame the page. While whitelisting can be dangerous, in some cases a webmaster might have no choice but to use more than one hostname.
* '''ALLOW-FROM browser support''' The ALLOW-FROM option is a relatively recent addition (circa 2012) and may not be supported by all browsers yet. BE CAREFUL ABOUT DEPENDING ON ALLOW-FROM. If you apply it and the browser does not support it, then you will have NO clickjacking defense in place.
* '''Multiple options not supported''' There is no way to allow the current site and a 3rd party site to frame the same response -- browsers only honour one X-Frame-Options header and only one value on that header.
* '''Nested Frames don't work with SAMEORIGIN and ALLOW-FROM''' In the following situation, the http://framed.invalid/child frame does not load because ALLOW-FROM applies to the top-level browsing context, not that of the immediate parent. The solution is to use ALLOW-FROM in both the parent and child frames (but this prevents the child frame loading if the //framed.invalid/parent page is loaded as the top level document).
+-//friendlysite.invalid-----------------------+
| |
| +-//framed.invalid/parent------------------+ |
| | | |
| | ALLOW-FROM http://friendlysite.invalid | |
| | | |
| | +-//framed.invalid/child--------+ | |
| | | | | |
| | | SAMEORIGIN | | |
| | | | | |
| | +-------------------------------+ | |
| +------------------------------------------+ |
+----------------------------------------------+
* '''X-Frame-Options Deprecated''' While the X-Frame-Options header is supported by the major browsers, it was never standardized and has been deprecated in favour of the frame-ancestors directive from the CSP Level 2 specification.
* '''Proxies''' Web proxies are notorious for adding and stripping headers. If a web proxy strips the X-Frame-Options header then the site loses its framing protection.

= Best-for-now Legacy Browser Frame Breaking Script =

One way to defend against clickjacking is to include a "frame-breaker" script
in each page that should not be framed. The following methodology will prevent
a webpage from being framed even in legacy browsers, that do not support the
X-Frame-Options-Header.

In the document HEAD element, add the following:

First apply an ID to the style element itself:

<style id="antiClickjack">body{display:none !important;}</style>

And then delete that style by its ID immediately after in the script:

<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
</script>

This way, everything can be in the document HEAD and you only need one method/taglib in your API.

Reference: [https://www.codemagi.com/blog/post/194 https://www.codemagi.com/blog/post/194]

= window.confirm() Protection =
The use of x-frame-options or a frame-breaking script is a more fail-safe method of clickjacking protection. However, in scenarios where content must be frameable, then a window.confirm() can be used to help mitigate Clickjacking by informing the user of the action they are about to perform.

Invoking window.confirm() will display a popup that cannot be framed. If the window.confirm() originates from within an iframe with a different domain than the parent, then the dialog box will display what domain the window.confirm() originated from. In this scenario the browser is displaying the origin of the dialog box to help mitigate Clickjacking attacks. It should be noted that Internet Explorer is the only known browser that does not display the domain that the window.confirm() dialog box originated from, to address this issue with Internet Explorer insure that the message within the dialog box contains contextual information about the type of action being performed. For example:

<script type="text/javascript">
var action_confirm = window.confirm("Are you sure you want to delete your youtube account?")
if (action_confirm) {
//... perform action
} else {
//... The user does not want to perform the requested action.
}
</script>

= Insecure Non-Working Scripts DO NOT USE =
Consider the following snippet which is '''NOT recommended''' for defending
against clickjacking:

<pre><script>if (top!=self) top.location.href=self.location.href</script></pre>

This simple frame breaking script attempts to prevent the page from being incorporated into a frame or iframe by forcing the parent window to load the current frame's URL. Unfortunately, multiple ways of defeating this type of script have been made public. We outline some here.

== Double Framing ==
Some frame busting techniques navigate to the correct page by assigning a value to parent.location. This works well if the victim page is framed by a single page. However, if the attacker encloses the victim in one frame inside another (a double frame), then accessing parent.location becomes a security violation in all popular browsers, due to the '''descendant frame navigation policy'''. This security violation disables the counter-action navigation.

'''Victim frame busting code:'''
<pre>
if(top.location!=self.locaton) {
parent.location = self.location;
}
</pre>

'''Attacker top frame:'''
<pre>
<iframe src="attacker2.html">
</pre>

'''Attacker sub-frame:'''
<pre>
<iframe src="http://www.victim.com">
</pre>

== The onBeforeUnload Event ==
A user can manually cancel any navigation request submitted by a framed page. To exploit this, the framing page registers an onBeforeUnload handler which is called whenever the framing page is about to be unloaded due to navigation. The handler function returns a string that becomes part of a prompt displayed to the user. Say the attacker wants to frame PayPal. He registers an unload handler function that returns the string "Do you want to exit PayPal?". When this string is displayed to the user is likely to cancel the navigation, defeating PayPal's frame busting attempt.

The attacker mounts this attack by registering an unload event on the top page using the
following code:
<pre>
<script>
window.onbeforeunload = function()
{
return "Asking the user nicely";
}
</script>
<iframe src="http://www.paypal.com">
</pre>
PayPal's frame busting code will generate a BeforeUnload event activating our function and prompting the user to cancel the navigation event.

== No-Content Flushing ==
While the previous attack requires user interaction, the same attack can be done without prompting the user. Most browsers (IE7, IE8, Google Chrome, and Firefox) enable an attacker to automatically cancel the incoming navigation request in an onBeforeUnload event handler by repeatedly submitting a navigation request to a site responding with \204 - No Content." Navigating to a No Content site is effectively a NOP, but flushes the request pipeline, thus canceling the original navigation request. Here is sample code to do this:

<pre>
var preventbust = 0
window.onbeforeunload = function() { killbust++ }
setInterval( function() {
if(killbust > 0){
killbust = 2;
window.top.location = 'http://nocontent204.com'
}
}, 1);
<iframe src="http://www.victim.com">
</pre>

== Exploiting XSS filters ==
IE8 and Google Chrome introduced reflective XSS filters that help protect web pages from certain types of XSS attacks. Nava and Lindsay (at Blackhat) observed that these filters can be used to circumvent frame busting code. The IE8 XSS filter compares given request parameters to a set of regular expressions in order to look for obvious attempts at cross-site scripting. Using "induced false positives", the filter can be used to disable selected scripts. By matching the beginning of any script tag in the request parameters, the XSS filter will disable all inline scripts within the page, including frame busting scripts. External scripts can also be targeted by matching an external include, effectively disabling all external scripts. Since subsets of the JavaScript loaded is still functional (inline or external) and cookies are still available, this attack is effective for clickjacking.

'''Victim frame busting code:'''
<pre>
<script>
if(top != self) {
top.location = self.location;
}
</script>
</pre>

'''Attacker:'''
<pre>
<iframe src="http://www.victim.com/?v=<script>if''>
</pre>

The XSS filter will match that parameter "<script>if" to the beginning of the frame busting script on the victim and will consequently disable all inline scripts in the victim's page, including the frame busting script. The XSSAuditor filter available for Google Chrome enables the same exploit.

== Clobbering top.location ==
Several modern browsers treat the location variable as a special immutable attribute across all contexts. However, this is not the case in IE7 and Safari 4.0.4 where the location variable can be redefined.

'''IE7'''
Once the framing page redefines location, any frame busting code in a subframe that tries to read top.location will commit a security violation by trying to read a local variable in another domain. Similarly, any attempt to navigate by assigning top.location will fail.

'''Victim frame busting code:'''

<pre>
if(top.location != self.location) {
top.location = self.location;
}
</pre>

'''Attacker:'''

<pre>
<script> var location = "clobbered";
</script>
<iframe src="http://www.victim.com">
</iframe>
</pre>

'''Safari 4.0.4'''

We observed that although location is kept immutable in most circumstances, when a custom location setter is defined via defineSetter (through window) the object location becomes undefined. The framing page simply does:
<pre>
<script>
window.defineSetter("location" , function(){});
</script>
</pre>
Now any attempt to read or navigate the top frame's location will fail.

== Restricted zones ==

Most frame busting relies on JavaScript in the framed page to detect framing and bust itself out. If JavaScript is disabled in the context of the subframe, the frame busting code will not run. There are unfortunately several ways of restricting JavaScript in a subframe:

* '''In IE 8:''' <pre><iframe src="http://www.victim.com" security="restricted"></iframe></pre>
* '''In Chrome:''' <pre><iframe src="http://www.victim.com" sandbox></iframe></pre>
*''' In Firefox and IE:''' Activate designMode in parent page.

== Other Cheatsheets ==

{{Cheatsheet_Navigation_Body}}

[[Category:Cheatsheets]]