Clarify CSRF <script> purpose and protection. Note how to deal with your own <script> tags.

Ref #21618

[ci skip]

2 files changed, 11 insertions, 6 deletions

diff --git a/guides/source/security.md b/guides/source/security.md
index 772a0b474c..5a6ac9446a 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -245,7 +245,9 @@ Or the attacker places the code into the onmouseover event handler of an image:
 <img src="http://www.harmless.com/img" width="400" height="400" onmouseover="..." />
 ```
 
-There are many other possibilities, like using a `<script>` tag to make a cross-site request to a URL with a JSONP or JavaScript response. The response is executable code that the attacker can find a way to run, possibly extracting sensitive data. To protect against this data leakage, we disallow dynamic JS responses for anything other than ajax requests irrespective of the origin. Only Ajax requests may have JavaScript responses since `XmlHttpRequest` is subject to the browser Same-Origin policy - meaning only your site can initiate ajax requests.
+There are many other possibilities, like using a `<script>` tag to make a cross-site request to a URL with a JSONP or JavaScript response. The response is executable code that the attacker can find a way to run, possibly extracting sensitive data. To protect against this data leakage, we must disallow cross-site `<script>` tags. Ajax requests, however, obey the browser's same-origin policy (only your own site is allowed to initiate `XmlHttpRequest`) so we can safely allow them to return JavaScript responses.
+
+Note: We can't distinguish a `<script>` tag's origin—whether it's a tag on your own site or on some other malicious site—so we must block all `<script>` across the board, even if it's actually a safe same-origin script served from your own site. In these cases, explicitly skip CSRF protection on actions that serve JavaScript meant for a `<script>` tag.
 
 To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is a one-liner in your application controller, and is the default for newly created rails applications:
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 2de9d6045e..52464a1c51 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -314,11 +314,13 @@ Upgrading from Rails 4.0 to Rails 4.1
 
 ### CSRF protection from remote `<script>` tags
 
-Or, "whaaat my tests are failing!!!?"
+Or, "whaaat my tests are failing!!!?" or "my `<script>` widget is busted!!"
 
-Cross-site request forgery (CSRF) protection now covers GET requests with dynamic JavaScript responses, too. By default, all javascript responses generated by an action will be blocked for non xhr requests. This will block usage of such urls in any `<script>` tag including your own. That way, in a possible attack scenario, it prevents a third-party site from referencing your JavaScript URL and attempting to run it to extract sensitive data.
+Cross-site request forgery (CSRF) protection now covers GET requests with
+JavaScript responses, too. This prevents a third-party site from remotely
+referencing your JavaScript with a `<script>` tag to extract sensitive data.
 
-It also means that your functional and integration tests that use
+This means that your functional and integration tests that use
 
 ```ruby
 get :index, format: :js
@@ -332,8 +334,9 @@ xhr :get, :index, format: :js
 
 to explicitly test an `XmlHttpRequest`.
 
-If you really mean to load JavaScript from remote `<script>` tags, skip CSRF
-protection on that action.
+Note: Your own `<script>` tags are treated as cross-origin and blocked by
+default, too. If you really mean to load JavaScript from `<script>` tags,
+you must now explicitly skip CSRF protection on those actions.
 
 ### Spring