1Name 2==== 3 4xss-nginx-module - Native cross-site scripting support in nginx 5 6Table of Contents 7================= 8 9* [Name](#name) 10* [Synopsis](#synopsis) 11* [Description](#description) 12* [Directives](#directives) 13 * [xss_get](#xss_get) 14 * [xss_callback_arg](#xss_callback_arg) 15 * [xss_override_status](#xss_override_status) 16 * [xss_check_status](#xss_check_status) 17 * [xss_input_types](#xss_input_types) 18* [Limitations](#limitations) 19* [Trouble Shooting](#trouble-shooting) 20* [Installation](#installation) 21* [Compatibility](#compatibility) 22* [TODO](#todo) 23* [Author](#author) 24* [Copyright & License](#copyright--license) 25* [See Also](#see-also) 26 27Synopsis 28======== 29 30```nginx 31# accessing /foo?callback=process gives the response 32# body "process(...);" (without quotes) where "..." 33# is the original response body of the /foo location. 34server { 35 location /foo { 36 # your content handler goes here... 37 38 xss_get on; 39 xss_callback_arg 'callback'; 40 xss_input_types 'application/json'; # default 41 xss_output_type 'application/x-javascript'; # default 42 } 43 ... 44} 45``` 46 47Description 48=========== 49 50This module adds cross-site AJAX support to nginx. Currently only 51cross-site GET is supported. But cross-site POST will be added 52in the future. 53 54The cross-site GET is currently implemented as JSONP 55(or "JSON with padding"). See http://en.wikipedia.org/wiki/JSON#JSONP 56for more details. 57 58Directives 59========== 60 61[Back to TOC](#table-of-contents) 62 63xss_get 64------- 65**syntax:** *xss_get on | off* 66 67**default:** *xss_get off* 68 69**context:** *http, server, location, if location* 70 71Enables JSONP support for GET requests. 72 73[Back to TOC](#table-of-contents) 74 75xss_callback_arg 76---------------- 77**syntax:** *xss_callback_arg <name>* 78 79**default:** *none* 80 81**context:** *http, http, location, if location* 82 83Specifies the JavaScript callback function name 84used in the responses. 85 86For example, 87 88```nginx 89location /foo { 90 xss_get on; 91 xss_callback_arg c; 92 ... 93} 94``` 95 96then 97 98``` 99GET /foo?c=blah 100``` 101 102returns 103 104```javascript 105blah(...); 106``` 107 108[Back to TOC](#table-of-contents) 109 110xss_override_status 111------------------- 112**syntax:** *xss_override_status on | off* 113 114**default:** *xss_check_status on* 115 116**context:** *http, server, location, if location* 117 118Specifies whether to override 30x, 40x and 50x status to 200 119when the response is actually being processed. 120 121[Back to TOC](#table-of-contents) 122 123xss_check_status 124----------------- 125**syntax:** *xss_check_status on | off* 126 127**default:** *xss_check_status on* 128 129**context:** *http, server, location, if location* 130 131By default, ngx_xss only process responses with the status code 132200 or 201. 133 134[Back to TOC](#table-of-contents) 135 136xss_input_types 137--------------- 138**syntax:** *xss_input_types [mime-type]...* 139 140**default:** *xss_input_types application/json* 141 142**context:** *http, server, location, if location* 143 144Only processes the responses of the specified MIME types. 145 146Example: 147 148```nginx 149xss_input_types application/json text/plain; 150``` 151 152[Back to TOC](#table-of-contents) 153 154Limitations 155=========== 156 157* ngx_xss will not work with [ngx_echo](https://github.com/openresty/echo-nginx-module)'s 158subrequest interfaces, due to the underlying 159limitations imposed by subrequests' "postponed chain" mechanism in the nginx core. 160The standard ngx_addition module also falls into this category. You're recommended, 161however, to use [ngx_lua](https://github.com/openresty/lua-nginx-module) as the content 162handler to issue subrequests *and* ngx_xss 163to do JSONP, because [ngx_lua](https://github.com/openresty/lua-nginx-module)'s 164[ngx.location.capture()](https://github.com/openresty/lua-nginx-module#ngxlocationcapture) 165interface does not utilize the "postponed chain" mechanism, thus getting out of this 166limitation. We're taking this approach in production and it works great. 167 168[Back to TOC](#table-of-contents) 169 170Trouble Shooting 171================ 172 173Use the "info" error log level (or lower) to get more 174diagnostics when things go wrong. 175 176[Back to TOC](#table-of-contents) 177 178Installation 179============ 180 181You're recommended to install this module (as well as the Nginx core and many other goodies) via the [OpenResty bundle](http://openresty.org). See [the detailed instructions](http://openresty.org/#Installation) for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up. 182 183Alternatively, you can install this module manually with the Nginx source: 184 185Grab the nginx source code from [nginx.org](http://nginx.org/), for example, 186the version 1.13.6 (see [nginx compatibility](#compatibility)), and then build the source with this module: 187 188```bash 189 190 $ wget 'http://nginx.org/download/nginx-1.13.6.tar.gz' 191 $ tar -xzvf nginx-1.13.6.tar.gz 192 $ cd nginx-1.13.6/ 193 194 # Here we assume you would install you nginx under /opt/nginx/. 195 $ ./configure --prefix=/opt/nginx \ 196 --add-module=/path/to/rds-json-nginx-module 197 198 $ make -j2 199 $ make install 200``` 201 202Download the latest version of the release tarball of this module from [xss-nginx-module file list](https://github.com/openresty/xss-nginx-module/tags). 203 204Also, this module is included and enabled by default in the [OpenResty bundle](http://openresty.org). 205 206[Back to TOC](#table-of-contents) 207 208Compatibility 209============= 210 211The following versions of Nginx should work with this module: 212 213* **1.13.x** (last tested: 1.13.6) 214* **1.12.x** 215* **1.11.x** (last tested: 1.11.2) 216* **1.10.x** 217* **1.9.x** (last tested: 1.9.7) 218* **1.8.x** 219* **1.7.x** (last tested: 1.7.10) 220* **1.6.x** 221* **1.5.x** 222* **1.4.x** (last tested: 1.4.3) 223* **1.2.x** (last tested: 1.2.9) 224* **1.0.x** (last tested: 1.0.10) 225* **0.9.x** (last tested: 0.9.4) 226* **0.8.x** (last tested: 0.8.54) 227* **0.7.x** >= 0.7.30 (last tested: 0.7.67) 228 229Earlier versions of Nginx like 0.6.x and 0.5.x will *not* work. 230 231If you find that any particular version of Nginx above 0.7.30 does not 232work with this module, please consider reporting a bug. 233 234[Back to TOC](#table-of-contents) 235 236TODO 237==== 238 239* add cross-site POST support. 240 241[Back to TOC](#table-of-contents) 242 243Author 244====== 245 246Yichun "agentzh" Zhang (章亦春) <agentzh@gmail@com> 247 248[Back to TOC](#table-of-contents) 249 250Copyright & License 251=================== 252 253The implementation of the builtin connection pool has borrowed 254a lot of code from Maxim Dounin's upstream_keepalive module. 255This part of code is copyrighted by Maxim Dounin. 256 257This module is licenced under the BSD license. 258 259Copyright (C) 2009-2018 by Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com> OpenResty Inc. 260 261All rights reserved. 262 263Redistribution and use in source and binary forms, with or without 264modification, are permitted provided that the following conditions 265are met: 266 267* Redistributions of source code must retain the above copyright 268notice, this list of conditions and the following disclaimer. 269* Redistributions in binary form must reproduce the above copyright 270notice, this list of conditions and the following disclaimer in the 271documentation and/or other materials provided with the distribution. 272 273THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 274"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 275LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 276A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 277HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 278SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 279TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 280PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 281LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 282NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 283SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 284 285[Back to TOC](#table-of-contents) 286 287See Also 288======== 289 290* [Introduction to JSONP](http://en.wikipedia.org/wiki/JSONP) 291* [ngx_lua](https://github.com/openresty/lua-nginx-module) 292 293[Back to TOC](#table-of-contents) 294 295