1=========================================================== 2ratproxy - passive web application security assessment tool 3=========================================================== 4 5 http://code.google.com/p/ratproxy 6 7 * Written and maintained by Michal Zalewski <lcamtuf@google.com>. 8 * Copyright 2007, 2008 Google Inc, rights reserved. 9 * Released under terms and conditions of the Apache License, version 2.0. 10 11----------------- 12What is ratproxy? 13----------------- 14 15Ratproxy is a semi-automated, largely passive web application security audit 16tool. It is meant to complement active crawlers and manual proxies more 17commonly used for this task, and is optimized specifically for an accurate and 18sensitive detection, and automatic annotation, of potential problems and 19security-relevant design patterns based on the observation of existing, 20user-initiated traffic in complex web 2.0 environments. The approach taken with 21ratproxy offers several important advantages over more traditional methods: 22 23 * No risk of disruptions. In the default operating mode, tool does not 24 generate a high volume of attack-simulating traffic, and as such may be 25 safely employed against production systems at will, for all types of ad hoc, 26 post-release audits. Active scanners may trigger DoS conditions or persistent 27 XSSes, and hence are poorly suited for live platforms. 28 29 * Low effort, high yield. Compared to active scanners or fully manual 30 proxy-based testing, ratproxy assessments take very little time or bandwidth 31 to run, and proceed in an intuitive, distraction-free manner - yet provide a 32 good insight into the inner workings of a product, and the potential security 33 vulnerabilities therein. They also afford a consistent and predictable 34 coverage of user-accessible features. 35 36 * Preserved control flow of human interaction. By silently following the 37 browser, the coverage in locations protected by nonces, during other 38 operations valid only under certain circumstances, or during dynamic events 39 such as cross-domain Referer data disclosure, is greatly enhanced. 40 Brute-force crawlers and fuzzers usually have no way to explore these areas 41 in a reliable manner. 42 43 * WYSIWYG data on script behavior. Javascript interfaces and event handlers 44 are explored precisely to a degree they are used in the browser, with no need 45 for complex guesswork or simulations. Active scanners often have a 46 significant difficulty exploring JSON responses, XMLHttpRequest() behavior, 47 UI-triggered event data flow, and the like. 48 49 * Easy process integration. The proxy can be transparently integrated into 50 an existing manual security testing or interface QA processes without 51 introducing a significant setup or operator training overhead. 52 53----------------------- 54Is it worth trying out? 55----------------------- 56 57There are numerous alternative proxy tools meant to aid security auditors - 58most notably WebScarab, Paros, Burp, and ProxMon. Stick with whatever suits 59your needs, as long as you get the data you need in the format you like. 60 61That said, ratproxy is there for a reason. It is designed specifically to 62deliver concise reports that focus on prioritized issues of clear relevance to 63contemporary web 2.0 applications, and to do so in a hands-off, repeatable 64manner. It should not overwhelm you with raw HTTP traffic dumps, and it goes 65far beyond simply providing a framework to tamper with the application by hand. 66 67Ratproxy implements a number of fairly advanced and unique checks based on our 68experience with these applications, as well as all the related browser quirks 69and content handling oddities. It features a sophisticated content-sniffing 70functionality capable of distinguishing between stylesheets and Javascript code 71snippets, supports SSL man-in-the-middle, on the fly Flash ActionScript 72decompilation, and even offers an option to confirm high-likelihood flaw 73candidates with very lightweight, a built-in active testing module. 74 75Last but not least, if you are undecided, the proxy may be easily chained with 76third-party security testing proxies of your choice. 77 78---------------------------------- 79How does it avoid false positives? 80---------------------------------- 81 82Operating in a non-disruptive mode makes the process of discovering security 83flaws particularly challenging, as the presence of some vulnerabilities must be 84deduced based on very subtle, not always reliable cues - and even in active 85testing modes, ratproxy strives to minimize the amount of rogue traffic 86generated, and side effects caused. 87 88The set of checks implemented by ratproxy is outlined later on - but just as 89importantly, underneath all the individual check logic, the proxy uses a number 90of passively or semi-passively gathered signals to more accurately prioritize 91reported problems and reduce the number of false alarms as much as possible. 92The five core properties examined for a large number of checks are: 93 94 * What the declared and actually detected MIME type for the document is. 95 This is a fairly important signal, as many problems manifest themselves 96 only in presence of subtle mismatches between these two - whereas other 97 issues need to be treated as higher or lower priority based on this data. 98 More fundamentally, the distinction between certain classes of content - such 99 as "renderables" that may be displayed inline by the browser - is 100 very important to many checks. 101 102 * How pages respond to having cookie-based authentication removed. This 103 provides useful information on whether the resource is likely to contain 104 user-specific data, amongst other things. Carefully preselected requests that 105 fail some security checks are replayed as-is, but with authentication data 106 removed; responses are then compared, with virtually no risk of undesirable 107 side effects in common applications. 108 109 * Whether requests seem to contain non-trivial, sufficiently complex 110 security tokens, or other mechanisms that may make the URL difficult to 111 predict. This provides information needed to determine the presence of XSRF 112 defenses, to detect cross-domain token leakage, and more. (In active testing 113 mode, the function of such tokens is further validated by replaying the 114 request with modified values.) 115 116 * Whether any non-trivial parts of the query are echoed back in the response, 117 and in what context. This is used to pick particularly interesting 118 candidates for XSS testing - or, in active mode, to schedule low-overhead, 119 lightweight probes. 120 121 * Whether the interaction occurs on a boundary of a set of domains defined 122 by runtime settings as the trusted environment subjected to the audit, and 123 the rest of the world. Many boundary behaviors have a special significance, 124 as they outline cross-domain trust patterns and information disclosure 125 routes. 126 127In addition to this, several places employ check-specific logic to further 128fine-tune the results. 129 130------------------------------------ 131What specific tests are implemented? 132------------------------------------ 133 134Key low-level check groups implemented by ratproxy are: 135 136 * Potentially unsafe JSON-like responses that may be vulnerable to 137 cross-domain script inclusion. JSON responses may be included across domains 138 by default, unless safe serialization schemes, security tokens, or parser 139 breaking syntax is used. Ratproxy will check for these properties, and 140 highlight any patterns of concern. 141 142 * Bad caching headers on sensitive content. Ratproxy is able to accurately 143 detect presence of several types of sensitive documents, such as locations 144 that return user-specific data, or resources that set new, distinctive 145 cookies. If the associated requests have predictable URLs, and lack HTTP 146 caching directives that would prevent proxy-level caching, there is a risk 147 of data leakage. 148 149 In pedantic mode, ratproxy will also spot differences in HTTP/1.1 and 150 HTTP/1.0 caching intents - as these may pose problems for a fraction of 151 users behind legacy cache engines (such as several commercial systems used 152 to date by some corporations). 153 154 * Suspicious cross-domain trust relationships. Based on the observation of 155 dynamic control flow, and a flexible definition of trusted perimeter, 156 ratproxy is capable of accurately detecting dangerous interactions between 157 domains, including but not limited to: 158 159 * Security token leakage via Referer headers, 160 * Untrusted script or stylesheet inclusion, 161 * General references to third-party domains, 162 * Mixed content issues in HTTPS-only applications, 163 * Tricky cross-domain POST requests in single sign-on systems. 164 165 * Numerous classes of content serving issues - a broad class of problems 166 that lead to subtles XSSes, and includes MIME type mismatches, charset 167 problems, Flash issues, and more. Research indicates that a vast number of 168 seemingly minor irregularities in content type specifications may trigger 169 cross-site scripting in unusal places; for example, subtle mistakes such as 170 serving GIF files as image/jpeg, typing utf8 instead of utf-8 in 171 Content-Type headers, or confusing HTTP charset with XML declaration 172 charset values are all enough to cause trouble. Even seemingly harmless 173 actions such as serving valid, attacker-controlled PNG images inline were 174 known to cause problems due to browser design flaws. 175 176 Likewise, certain syntax patterns are dangerous to return to a browser 177 regardless of MIME types, as there are known methods to have MIME types 178 overridden or ignored altogether. Ratproxy uses a set of fairly advanced 179 checks that spot these problems with a considerable accuracy and relatively 180 few false positives in contemporary scenarios, accounting for various 181 classes of content served. 182 183 * Queries with insufficient XSRF defenses (POSTs, plus any requests that 184 set cookies by default; and other suspicious looking GET requests as an 185 option). In active testing mode, the proxy will also actually try to 186 validate XSRF protections by replaying requests with modified token values, 187 and comparing responses. 188 189 * Suspected or confirmed XSS / data injection vectors, including attacks 190 through included JSON-based script injection, or response header splitting. 191 In the default, passive mode, ratproxy does not attempt to confirm the 192 quality of XSS filtering in tested applications, but it will automatically 193 enumerate and annotate the best subjects for manual inspection - and will 194 offer the user the ability to feed this data to external programs, or modify 195 and replay interesting requests on the fly. The proxy will also take note 196 of any seemingly successful manual XSS attempts taken by the user. 197 198 In active testing mode, the proxy will go one step further and attempt a 199 single-shot verification of XSS filtering mechanisms, carefully tweaking 200 only these request parameters that truly need to be tested at the time (and 201 carefully preserving XSRF tokens, and more). 202 203 * HTTP and META redirectors. Redirectors, unless properly locked down, may 204 be used without owner's consent, which in some contexts may be seen as 205 undesirable. Furthermore, in extreme cases, poorly implemented redirectors 206 may open up cross-site scripting vectors in less common browsers. 207 208 Ratproxy will take note of any redirectors observed for further testing. 209 210 * A broad set of other security problems, such as alarming Javascript, 211 OGNL, Java, SQL, file inclusion patterns, directory indexes, server errors, 212 and so forth. Ratproxy will preselect particularly interesting candidates for 213 further testing. 214 215 Although in the initial beta, not all web technologies may necessarily be 216 analyzed to greatest extent possible, we intend to actively improve the tool 217 based on your feedback. 218 219 * Several additional, customizable classes of requests and responses useful 220 in understanding the general security model of the application (file upload 221 forms, POST requests, cookie setters, etc). 222 223For a full list of individual issues reported, please see messages.list in the 224source tarball. 225 226------------------------------------------ 227What is the accuracy of reported findings? 228------------------------------------------ 229 230Ratproxy usually fares very well with typical, rich, modern web applications - 231that said, by the virtue of operating in passive mode most of the time, all the 232findings reported merely highlight areas of concern, and are not necessarily 233indicative of actual security flaws. The information gathered during a testing 234session should be then interpreted by a security professional with a good 235understanding of the common problems and security models employed in web 236applications. 237 238Please keep in mind that the tool is still in beta, and you may run into 239problems with technologies we had no chance to examine, or that were not a 240priority at this time. Please contact the author to report any issues 241encountered. 242 243--------------------- 244How to run the proxy? 245--------------------- 246 247 NOTE: Please do not be evil. Use ratproxy only against services you own, or 248 have a permission to test. Keep in mind that although the proxy is mostly 249 passive and unlikely to cause disruptions, it is not stealth. Furthermore, the 250 proxy is not designed for dealing with rogue and misbehaving HTTP servers and 251 clients - and offers no guarantees of safe (or sane) behavior there. 252 253Initiating ratproxy sessions is fairly straigtforward, once an appropriate set 254of runtime options is dediced upon. Please familiarize yourself with these 255settings, as they have a very significant impact on the quality of produced 256reports. 257 258The main binary, ./ratproxy, takes the following arguments: 259 260 -w logfile - this option causes raw, machine-readable proxy logs to be 261 written to a specified file. By default, all data is written 262 to stdout only. The log produced this way is not meant for 263 human consumption - it might be postprocessed with third-party 264 utilities, or pretty-printed using 'ratproxy-report.sh', 265 however. 266 267 -v logdir - prompts ratproxy to store full HTTP traces of all requests 268 featured in the logfile, writing them to a specified directory. 269 In most cases, it is advisable to enable this option, as it 270 provides useful hints for further analysis. 271 272 -p port - causes ratproxy to listen for browser connections on a TCP 273 port different than the default 8080. 274 275 -r - instructs ratproxy to accept remote connections. By default, 276 the proxy listens on loopback interfaces only. This option 277 enables remote access to the service. 278 279 WARNING: Ratproxy does not feature any specific access 280 control mechanisms, and may be abused if exposed to the 281 Internet. Please make sure to use proper firewall controls 282 whenever using -r option to prevent this. 283 284 -d domain - specifies a domain name suffix used to distinguish between 285 the audited infrastructure and third-party sites. Host names 286 that match -d values will be subjected to analysis, and ones 287 that do not will be considered the outside world. Interactions 288 between these two classes will be subjected to additional 289 checks. 290 291 NOTE: This feature is extremely important for several of the 292 checks implemented by ratproxy. If -d option is missing, 293 ratproxy will treat all URLs as being a part of the audited 294 service, and cross-domain interaction checks will not be 295 carried out at all. If it is set incorrectly, report coverage 296 may decrease. 297 298 Multiple -d options may and often should be combined to 299 define the perimeter for testing and flow analysis (e.g., -d 300 example.com -d example-ad-service.com -d example-ng.com). 301 302 -P host:port - causes ratproxy to talk to an upstream proxy instead of 303 directly routing requests to target services. Useful for 304 testing systems behind corporate proxies, or chaining 305 multiple proxy-type security testing tools together. 306 307 -l - ratproxy sometimes needs to tell if a page has substantially 308 changed between two requests to better qualify the risks 309 associated with some observations. By default, this is 310 achieved through strict page checksum comparison (MD5). This 311 options enables an alternative, relaxed checking mode that 312 relies on page length comparison instead. 313 314 Since some services tend to place dynamically generated 315 tokens on rendered pages, it is generally advisable to enable 316 this mode most of the time. 317 318 -2 - several services are known to render the same page with 319 dynamic content of variable length in response to two 320 subsequent, otherwise identical requests. This might be a 321 result of inline ad rendering, or other content randomization. 322 323 When dealing with such services, ratproxy might be instructed 324 to acquire three, not two, samples for page comparison for some 325 checks, to further minimize the number of false positives. 326 327 -e - enables pedantic caching header validation. Security problems 328 may arise when documents clearly not meant to be cached are 329 served in a way that permits public proxies to store them. By 330 default, ratproxy detects poorly chosen HTTP/1.1 caching 331 directives that are most likely to affect general population. 332 333 Some additional issues may appear with users behind legacy 334 proxies that support HTTP/1.0 only, however - as is the case 335 with several commercial solutions. These proxies may ignore 336 HTTP/1.1 directives and interpret HTTP/1.0 cues only. In -e 337 mode, ratproxy will complain about all cases where there 338 appears to be a mismatch between HTTP/1.0 and HTTP/1.1 caching 339 intents. 340 341 This tends to generate a large number of warnings for many 342 services; if you prefer to focus on more pressing issues first, 343 you might want to keep it off at first. 344 345 -x - tells the proxy to log all URLs that seem to be particularly 346 well-suited for further, external XSS testing (by the virtue 347 of being echoed on the page in a particular manner). By 348 default, ratproxy will not actually attempt to confirm these 349 vectors (-X option enables disruptive checking, however) - but 350 you will be able to use the data for manual testing or as 351 input to third-party software. 352 353 Generally recommended, unless it proves to be too noisy. 354 355 -t - by default, ratproxy logs some of the most likely directory 356 traversal candidates. This option tells the proxy to log less 357 probable guesses, too. These are good leads for manual testing 358 or as input to an external application. 359 360 Generally recommended, unless it proves to be too noisy. 361 362 -i - with this option supplied, ratproxy will log all PNG files 363 served inline. PNG files are a cross-site scripting vector in 364 some legacy browsers. The default behavior is to log these 365 images that require authentication only, based on the 366 assumption that such images are most likely to be 367 user-controlled. 368 369 This option should be enabled when auditing applications 370 that permit picture uploads and sharing; otherwise, it may 371 just generate noise. 372 373 -f - with this option enabled, the proxy will log all Flash 374 applications encountered for further analysis. This is 375 particularly useful when combined with -v, in which case, Flash 376 files will be automatically disassembled and conveniently 377 included in 'ratproxy-report.sh' output. 378 379 Since recent Flash vulnerabilities make the platform a major 380 potential cross-site scripting vector, it is advisable to 381 enable this feature. 382 383 -s - tells ratproxy to log all POST requests for further analysis 384 and processing, in a separate section of the final report. 385 This is useful for bookkeeping and manual review, since POST 386 features are particularly likely to expose certain security 387 design flaws. 388 389 -c - enables logging of all URLs that seem to set cookies, 390 regardless of their presumed security impact. Again, useful for 391 manual design analysis and bookkeeping. Not expected to 392 contribute much noise to the report. 393 394 -g - extends XSRF token validation checks to GET requests. By 395 default, the proxy requires anti-XSRF protection on POST 396 requests and cookie setters only. Some applications tend to 397 perform state changing operations via GET requests, too, and 398 so with this option enabled, additional data will be collected 399 and analyzed. 400 401 This feature is verbose, but useful for certain application 402 designs. 403 404 -j - enables detection of discouraged Javascript syntax, such as 405 eval() calls or .innerHTML operations. Javascript code that 406 makes use of these will be tagged for manual inspection. 407 408 -m - enables logging of "active" content referenced across domain 409 boundaries to detect patterns such as remote image inclusion 410 or remote linking (note that logging of remote script or 411 stylesheet inclusion is enabled at all times). 412 413 This option has an effect only when a proper set of domains 414 is specified with -d command-line parameter - and is 415 recommended for sites where a careful control of cross-domain 416 trust relationships needs to be ensured. 417 418 -X - enables active testing. When this option is provided, 419 ratproxy will attempt to actively, disruptively validate the 420 robustness of XSS and XSRF defenses whenever such a check is 421 deemed necessary. 422 423 By the virtue of doing passive preselection, this does not 424 generate excessive traffic and maintains the same level of 425 coverage as afforded in passive mode. 426 427 The downside is that these additional requests may disrupt 428 the application or even trigger persistent problems; as such, 429 please exercise caution when using it against mission-critical 430 production systems. 431 432 -C - in disruptive testing mode, ratproxy will replay some 433 requests with modified parameters. This may disrupt the state 434 of some applications and make them difficult to navigate. To 435 remediate this, -C option enables additional replaying of the 436 unmodified request at the end of the process, in hopes of 437 restoring the original server-side state. 438 439 This option is generally recommended in -X mode. 440 441 -k - instructs ratproxy that the application is expected to use 442 HTTPS exclusively; any downgrades to HTTP will be reported 443 and prioritized depending on potential impact. 444 445 This option obviously makes sense only if the application is 446 indeed meant to use HTTPS and HTTPS only. 447 448 -a - tells ratproxy to indiscriminately log all visited URLs. 449 Useful for assessing the coverage achieved. 450 451In practice, for low verbosity reporting that looks for high-probability issues 452only, a good starting point is: 453 454 ./ratproxy -v <outdir> -w <outfile> -d <domain> -lfscm 455 456To increase verbosity and include output from some less specific checks, the 457following set of options is a good idea: 458 459 ./ratproxy -v <outdir> -w <outfile> -d <domain> -lextifscgjm 460 461For active testing, simply add -XC options as needed. 462 463Once the proxy is running, you need to configure your web browser to point to 464the appropriate machine and port (a simple Firefox extension such as QuickProxy 465may come handy in the long run); it is advisable to close any non-essential 466browser windows and purge browser cache, as to maximize coverage and minimize 467noise. 468 469The next step is to open the tested service in your browser, log in if 470necessary, then interact with it in a regular, reasonably exhaustive manner: 471try all available views, features, upload and download files, add and delete 472data, and so forth - then log out gracefully and terminate ratproxy with Ctrl-C. 473 474 NOTE: Do not be tempted to tunnel automated spider traffic (e.g. wget -r or 475 active scanners) via ratproxy. This will not have the desired effect. The tool 476 depends strictly on being able to observe well-behaved, valid user-application 477 interaction. 478 479 SECURITY WARNING: When interacting with SSL applications, ratproxy will 480 substitute its own, dummy, self-signed certificate in place of that 481 legitimately returned by the service. This is expected to generate browser 482 warnings - click through them to accept the key temporarily for the site. Do 483 not add the key permanently to your browser configuration - the key is known to 484 anyone who ever downloaded the tool. Furthermore, please note that ratproxy 485 will also forego any server certificate validation steps - so while interacting 486 with the service in this mode, you can have no expectation of server identity, 487 transmission integrity, or data privacy. Do not use important accounts and do 488 not enter sensitive data while running ratproxy tests. 489 490Once the proxy is terminated, you may further process its pipe-delimited (|), 491machine-readable, greppable output with third party tools if so desired, then 492generate a human-readable HTML report: 493 494 ./ratproxy-report.sh ratproxy.log >report.html 495 496This will produce an annotated, prioritized report with all the identified 497issues. When opened in a browser, you will have an opportunity to replay GET 498and POST requests, tweak their parameters, view traces, and inspect Flash 499disassemblies, too. 500 501Enjoy :-) 502 503----------------------------------- 504Credits, contributions, suggestions 505----------------------------------- 506 507If you are interested in contributing to the project, a list of features and 508improvements for the proxy can be found in doc/TODO in the source tarball. 509 510If you have any questions, suggestions, or concerns regarding the application, 511the author can be reached at lcamtuf@google.com. 512 513Ratproxy was made possible by the contributions of, and valuable feedback from, 514Google's information security engineering team. 515 516