Ruby: Update CSRF protection notes in documentation

[smowton]

Autofix is confused about how the protect_from_forgery method works in Rails >= 5: GPT-5 says:

In modern Rails versions (>=5, including 6 and 7 which this gem permits), ActionController::Base already enables CSRF protection by default with the :exception strategy; an explicit call to protect_from_forgery without options does not weaken security.

This is false: manual testing confirms that it actually does downgrade from :exception to :null-session behaviour when a manual call is made.

I can't find any authoritative source showing this gotcha, so I can see how the AI is confused and how humans might also struggle to verify the truth.

[Copilot]

Pull Request Overview

This PR updates documentation for the CSRF protection disabled query to clarify how Rails' protect_from_forgery method behaves in version 5 and later. The change corrects a common misconception about the default behavior of manual protect_from_forgery calls.

Key Changes

• Adds clarification that Rails 5+ defaults to :exception strategy for CSRF protection
• Documents that manually calling protect_from_forgery without arguments downgrades to :null_session behavior
• Addresses confusion about how explicit calls interact with Rails' automatic protection

[Copilot]

The phrase 'null the session' is grammatically incorrect. It should be 'nullify the session' or 'set the session to null'.

[hvitved]

I agree that this reads a bit weird.

[smowton]

Reworded.

[github-actions]

QHelp previews:

ruby/ql/src/queries/security/cwe-352/CSRFProtectionDisabled.qhelp

CSRF protection weakened or disabled

Cross-site request forgery (CSRF) is a type of vulnerability in which an attacker is able to force a user to carry out an action that the user did not intend.

The attacker tricks an authenticated user into submitting a request to the web application. Typically this request will result in a state change on the server, such as changing the user's password. The request can be initiated when the user visits a site controlled by the attacker. If the web application relies only on cookies for authentication, or on other credentials that are automatically included in the request, then this request will appear as legitimate to the server.

A common countermeasure for CSRF is to generate a unique token to be included in the HTML sent from the server to a user. This token can be used as a hidden field to be sent back with requests to the server, where the server can then check that the token is valid and associated with the relevant user session.

Recommendation

In many web frameworks, CSRF protection is enabled by default. In these cases, using the default configuration is sufficient to guard against most CSRF attacks.

Example

The following example shows a case where CSRF protection is disabled by skipping token verification.

class UsersController < ApplicationController
  skip_before_action :verify_authenticity_token
end

Verification can be re-enabled by removing the call to skip_before_action.

Care should be taken when using the Rails protect_from_forgery method to prevent CSRF. The default behaviour of this method is to null the session when an invalid CSRF token is provided. This may not be sufficient to avoid a CSRF vulnerability - for example if parts of the session are memoized. Calling protect_from_forgery with: :exception can help to avoid this by raising an exception on an invalid CSRF token instead. Note this remains true even in Rails version 5 and later: these versions automatically run protect_from_forgery with: :exception by default, but manually calling protect_from_forgery with no with argument will still downgrade protection to provide an empty session rather than raise an exception.

References

• Wikipedia: Cross-site request forgery
• OWASP: Cross-site request forgery
• Securing Rails Applications: Cross-Site Request Forgery (CSRF)
• Veracode: When Rails' protect_from_forgery Fails.
• Common Weakness Enumeration: CWE-352.

ruby/ql/src/queries/security/cwe-352/CSRFProtectionNotEnabled.qhelp

CSRF protection not enabled

Cross-site request forgery (CSRF) is a type of vulnerability in which an attacker is able to force a user to carry out an action that the user did not intend.

The attacker tricks an authenticated user into submitting a request to the web application. Typically this request will result in a state change on the server, such as changing the user's password. The request can be initiated when the user visits a site controlled by the attacker. If the web application relies only on cookies for authentication, or on other credentials that are automatically included in the request, then this request will appear as legitimate to the server.

A common countermeasure for CSRF is to generate a unique token to be included in the HTML sent from the server to a user. This token can be used as a hidden field to be sent back with requests to the server, where the server can then check that the token is valid and associated with the relevant user session.

Recommendation

In the Rails web framework, CSRF protection is enabled by the adding a call to the protect_from_forgery method inside an ActionController class. Typically this is done in the ApplicationController class, or an equivalent class from which other controller classes are subclassed. The default behaviour of this method is to null the session when an invalid CSRF token is provided. This may not be sufficient to avoid a CSRF vulnerability - for example if parts of the session are memoized. Calling protect_from_forgery with: :exception can help to avoid this by raising an exception on an invalid CSRF token instead. Note that Rails versions 5 and later automatically run protect_from_forgery with: :exception by default, but manually calling protect_from_forgery with no with argument will downgrade protection to provide an empty session rather than raise an exception.

Example

The following example shows a case where CSRF protection is enabled with a secure request handling strategy of :exception.

class ApplicationController < ActionController::Base
  protect_from_forgery with: :exception
end
  

References

• Wikipedia: Cross-site request forgery
• OWASP: Cross-site request forgery
• Securing Rails Applications: Cross-Site Request Forgery (CSRF)
• Veracode: When Rails' protect_from_forgery Fails.
• Common Weakness Enumeration: CWE-352.

[hvitved]

run -> runs.

[smowton]

Changed version -> versions instead

[hvitved]

I agree that this reads a bit weird.