From 9df42276f94a128eef4e6f3e6dc6f5055cd63529 Mon Sep 17 00:00:00 2001 From: Patrik Ragnarsson Date: Wed, 27 Mar 2024 09:06:28 +0100 Subject: [PATCH] Update prebuilt files Ran and committed the changes from bundle exec rake pull build Looks like we have been accepting changes here that should have gone into the sinatra/sinatra repo. Oh well. --- _includes/README.html | 267 ++++++++++-------- .../rack-protection-authenticity-token.html | 3 +- ...ck-protection-content-security-policy.html | 4 +- _includes/rack-protection-escaped-params.html | 2 +- _includes/rack-protection-form-token.html | 2 +- _includes/rack-protection-http-origin.html | 4 +- _includes/rack-protection-ip-spoofing.html | 2 +- _includes/rack-protection-json-csrf.html | 2 +- _includes/rack-protection-path-traversal.html | 2 +- _includes/rack-protection-readme.html | 36 +-- .../rack-protection-remote-referrer.html | 2 +- _includes/rack-protection-remote-token.html | 2 +- .../rack-protection-session-hijacking.html | 2 +- _includes/rack-protection-xss-header.html | 2 +- _includes/sinatra-contrib-readme.html | 28 +- 15 files changed, 191 insertions(+), 169 deletions(-) diff --git a/_includes/README.html b/_includes/README.html index cedce68..5cf6608 100644 --- a/_includes/README.html +++ b/_includes/README.html @@ -1,4 +1,4 @@ - +

Gem Version @@ -15,10 +15,11 @@ end -

Install the gem:

+

Install the gems needed:

gem install sinatra
-gem install puma # or any other server
+gem install rackup
+gem install puma # or any other server (optional step)
 

And run with:

@@ -323,7 +324,7 @@

Static Files

Note that the public directory name is not included in the URL. A file ./public/css/style.css is made available as -https://example.com/css/style.css.

+http://example.com/css/style.css.

Use the :static_cache_control setting (see below) to add Cache-Control header info.

@@ -474,7 +475,7 @@

Haml Templates

- + @@ -533,7 +534,7 @@

Nokogiri Templates

Dependencyhamlhaml
File Extension
- + @@ -547,6 +548,40 @@

Nokogiri Templates

It also takes a block for inline templates (see example).

+

Sass Templates

+ +
Dependencynokogirinokogiri
File Extension
+ + + + + + + + + + + + +
Dependencysass-embedded
File Extension.sass
Examplesass :stylesheet, :style => :expanded
+ +

Scss Templates

+ + + + + + + + + + + + + + +
Dependencysass-embedded
File Extension.scss
Examplescss :stylesheet, :style => :expanded
+

Liquid Templates

@@ -616,7 +651,7 @@

RDoc Templates

- + @@ -649,7 +684,7 @@

AsciiDoc Templates

DependencyRDocRDoc
File Extension
- + @@ -707,7 +742,7 @@

Slim Templates

DependencyAsciidoctorAsciidoctor
File Extension
- + @@ -1038,21 +1073,6 @@

Session Secret Security

99ae8af...snip...ec0f262ac -

Session Secret Generation (Bonus Points)

- -

Use the sysrandom gem to -use the system RNG facilities to generate random values instead of -userspace OpenSSL which MRI Ruby currently defaults to:

- -
$ gem install sysrandom
-Building native extensions.  This could take a while...
-Successfully installed sysrandom-1.x
-1 gem installed
-
-$ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
-99ae8af...snip...ec0f262ac
-
-

Session Secret Environment Variable

Set a SESSION_SECRET environment variable for Sinatra to the value you @@ -1066,13 +1086,9 @@

Session Secret Security

Session Secret App Config

Set up your app config to fail-safe to a secure random secret -if the SESSION_SECRET environment variable is not available.

- -

For bonus points use the sysrandom -gem here as well:

+if the SESSION_SECRET environment variable is not available:

require 'securerandom'
-# -or- require 'sysrandom/securerandom'
 set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
 
@@ -1261,51 +1277,9 @@

Streaming Responses

If the optional parameter is set to keep_open, it will not call close on the stream object, allowing you to close it at any later point in the -execution flow. This only works on evented servers, like Rainbows. -Other servers will still close the stream:

- -
# config.ru
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  connections = []
-
-  get '/subscribe', provides: 'text/event-stream'  do
-    # register a client's interest in server events
-    stream(:keep_open) do |out|
-      connections << out
-      # purge dead connections
-      connections.reject!(&:closed?)
-    end
-  end
+execution flow.

- post '/' do - connections.each do |out| - # notify client that a new message has arrived - out << "data: #{params[:msg]}\n\n" - - # indicate client to connect again - out.close - end - - 204 # response without entity body - end -end - -run App -
- -
# rainbows.conf
-Rainbows! do
-  use :EventMachine
-end
-~~~~`
-
-Run:
-
-~~~~shell
-rainbows -c rainbows.conf
-
+

You can have a look at the chat example

It’s also possible for the client to close the connection when trying to write to the socket. Because of this, it’s recommended to check @@ -1382,7 +1356,7 @@

Browser Redirect

Any additional parameters are handled like arguments passed to halt:

redirect to('/bar'), 303
-redirect 'https://www.google.com/', 'wrong place, buddy'
+redirect 'http://www.google.com/', 'wrong place, buddy'
 

You can also easily redirect back to the page the user came from with @@ -1554,7 +1528,7 @@

Accessing the Request Object

The incoming request object can be accessed from request level (filter, routes, error handlers) through the request method:

-
# app running on https://example.com/example
+
# app running on http://example.com/example
 get '/foo' do
   t = %w[text/css text/html application/javascript]
   request.accept              # ['text/html', '*/*']
@@ -1577,7 +1551,7 @@ 

Accessing the Request Object

request.user_agent # user agent (used by :agent condition) request.cookies # hash of browser cookies request.xhr? # is this an ajax request? - request.url # "https://example.com/example/foo" + request.url # "http://example.com/example/foo" request.path # "/example/foo" request.ip # client IP address request.secure? # false (would be true over ssl) @@ -1767,7 +1741,7 @@

Configuring attack protection

You can also hand in an array in order to disable a list of protections:

-
set :protection, :except => [:path_traversal, :session_hijacking]
+
set :protection, :except => [:path_traversal, :remote_token]
 

By default, Sinatra will only set up session based protection if :sessions @@ -1905,9 +1879,13 @@

Available Settings

raise_errors
- Raise exceptions (will stop application). Enabled by default when + Raise unhandled errors (will stop application). Enabled by default when environment is set to "test", disabled otherwise.
+
+ Any explicitly defined error handlers always override this setting. See + the "Error" section below. +
run
@@ -2000,6 +1978,23 @@

Available Settings

+

Lifecycle Events

+ +

There are 2 lifecycle events currently exposed by Sinatra. One when the server starts and one when it stops.

+ +

They can be used like this:

+ +
on_start do
+  puts "===== Booting up ====="
+end
+
+on_stop do
+  puts "===== Shutting down ====="
+end
+
+ +

Note that these callbacks only work when using Sinatra to start the web server.

+

Environments

There are three predefined environments: "development", @@ -2052,6 +2047,13 @@

Error

set :show_exceptions, :after_handler
 
+

A catch-all error handler can be defined with error and a block:

+ +
error do
+  'Sorry there was a nasty error'
+end
+
+

The exception object can be obtained from the sinatra.error Rack variable:

error do
@@ -2059,7 +2061,7 @@ 

Error

end
-

Custom errors:

+

Pass an error class as an argument to create handlers for custom errors:

error MyCustomError do
   'So what happened was...' + env['sinatra.error'].message
@@ -2100,6 +2102,58 @@ 

Error

running under the development environment to display nice stack traces and additional debugging information in your browser.

+

Behavior with raise_errors option

+ +

When raise_errors option is true, errors that are unhandled are raised +outside of the application. Additionally, any errors that would have been +caught by the catch-all error handler are raised.

+ +

For example, consider the following configuration:

+ +
# First handler
+error MyCustomError do
+  'A custom message'
+end
+
+# Second handler
+error do
+  'A catch-all message'
+end
+
+ +

If raise_errors is false:

+ +
    +
  • When MyCustomError or descendant is raised, the first handler is invoked. +The HTTP response body will contain "A custom message".
  • +
  • When any other error is raised, the second handler is invoked. The HTTP +response body will contain "A catch-all message".
  • +
+ +

If raise_errors is true:

+ +
    +
  • When MyCustomError or descendant is raised, the behavior is identical to +when raise_errors is false, described above.
  • +
  • When any other error is raised, the second handler is not invoked, and +the error is raised outside of the application. +
      +
    • If the environment is production, the HTTP response body will contain +a generic error message, e.g. "An unhandled lowlevel error occurred. The +application logs may have details." +
    • +
    • If the environment is not production, the HTTP response body will contain +the verbose error backtrace.
    • +
    • Regardless of environment, if show_exceptions is set to :after_handler, +the HTTP response body will contain the verbose error backtrace.
    • +
    +
  • +
+ +

In the test environment, raise_errors is set to true by default. This +means that in order to write a test for a catch-all error handler, +raise_errors must temporarily be set to false for that particular test.

+

Rack Middleware

Sinatra rides on Rack, a minimal standard @@ -2216,7 +2270,7 @@

Sinatra::Base - Mid

Sinatra::Base is a blank slate. Most options are disabled by default, -including the built-in server. See Configuring +including the built-in server. See Configuring Settings for details on available options and their behavior. If you want behavior more similar to when you define your app at the top level (also known as Classic @@ -2571,65 +2625,30 @@

Multi-threading

Sinatra doesn’t impose any concurrency model but leaves that to the underlying Rack handler (server) like Puma or WEBrick. Sinatra itself is thread-safe, so there won’t be any problem if the Rack handler -uses a threaded model of concurrency. This would mean that when starting -the server, you’d have to specify the correct invocation method for the -specific Rack handler. The following example is a demonstration of how -to start a multi-threaded Rainbows server:

- -
# config.ru
-
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  get '/' do
-    "Hello, World"
-  end
-end
-
-run App
-
- -
# rainbows.conf
-
-# Rainbows configurator is based on Unicorn.
-Rainbows! do
-  use :ThreadSpawn
-end
-
- -

To start the server, the command would be:

- -
rainbows -c rainbows.conf
-
+uses a threaded model of concurrency.

Requirement

The following Ruby versions are officially supported:

-
Ruby 2.6
+
Ruby
- 2.6 is fully supported and recommended. There are currently no plans to - drop official support for it. + The stable releases are fully supported and recommended.
-
Rubinius
+
TruffleRuby
- Rubinius is officially supported (Rubinius >= 2.x). It is recommended to - gem install puma. + The latest stable release of TruffleRuby is supported.
JRuby
- The latest stable release of JRuby is officially supported. It is not - recommended to use C extensions with JRuby. It is recommended to - gem install trinidad. + The latest stable release of JRuby is supported. It is not + recommended to use C extensions with JRuby.
-

Versions of Ruby before 2.6 are no longer supported as of Sinatra 3.0.0.

- -

We also keep an eye on upcoming Ruby versions. Expect upcoming -3.x releases to be fully supported.

+

Versions of Ruby before 2.7.8 are no longer supported as of Sinatra 4.0.0.

Sinatra should work on any operating system supported by the chosen Ruby implementation.

@@ -2701,7 +2720,7 @@

Further Reading

  • Sinatra Book - Cookbook Tutorial
  • -Sinatra Recipes - Community contributed +Sinatra Recipes - Community contributed recipes
  • API documentation for the latest release or the current HEAD on diff --git a/_includes/rack-protection-authenticity-token.html b/_includes/rack-protection-authenticity-token.html index 1b79409..78b3042 100644 --- a/_includes/rack-protection-authenticity-token.html +++ b/_includes/rack-protection-authenticity-token.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_request_forgery

    +

    en.wikipedia.org/wiki/Cross-site_request_forgery

    This middleware only accepts requests other than GET, HEAD, OPTIONS, TRACE if their given access token matches the token included in the session.

    @@ -48,6 +48,7 @@

    Example: Forms applicationHere is server.rb:

    require 'rack/protection'
    +require 'rack/session'
     
     app = Rack::Builder.app do
       use Rack::Session::Cookie, secret: 'secret'
    diff --git a/_includes/rack-protection-content-security-policy.html b/_includes/rack-protection-content-security-policy.html
    index 7b80b87..df687d7 100644
    --- a/_includes/rack-protection-content-security-policy.html
    +++ b/_includes/rack-protection-content-security-policy.html
    @@ -9,10 +9,10 @@
     

    Content Security Policy, a mechanism web applications can use to mitigate a broad class of content injection vulnerabilities, such as cross-site scripting (XSS). Content Security Policy is a declarative policy that lets the authors (or server administrators) of a web application inform the client about the sources from which the application expects to load resources.

    More info
    -

    W3C CSP Level 1 : www.w3.org/TR/CSP1/ (deprecated) W3C CSP Level 2 : www.w3.org/TR/CSP2/ (current) W3C CSP Level 3 : www.w3.org/TR/CSP3/ (draft) developer.mozilla.org/en-US/docs/Web/Security/CSP caniuse.com/#search=ContentSecurityPolicy content-security-policy.com/ securityheaders.io scotthelme.co.uk/csp-cheat-sheet/ www.html5rocks.com/en/tutorials/security/content-security-policy/

    +

    W3C CSP Level 1 : www.w3.org/TR/CSP1/ (deprecated) W3C CSP Level 2 : www.w3.org/TR/CSP2/ (current) W3C CSP Level 3 : www.w3.org/TR/CSP3/ (draft) developer.mozilla.org/en-US/docs/Web/Security/CSP caniuse.com/#search=ContentSecurityPolicy content-security-policy.com/ securityheaders.io scotthelme.co.uk/csp-cheat-sheet/ www.html5rocks.com/en/tutorials/security/content-security-policy/

    -

    Sets the ‘Content-Security-Policy’ header.

    +

    Sets the ‘content-security-policy’ header.

    Options: ContentSecurityPolicy configuration is a complex topic with

    diff --git a/_includes/rack-protection-escaped-params.html b/_includes/rack-protection-escaped-params.html index ad65ca7..c9a1702 100644 --- a/_includes/rack-protection-escaped-params.html +++ b/_includes/rack-protection-escaped-params.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_scripting

    +

    en.wikipedia.org/wiki/Cross-site_scripting

    Automatically escapes Rack::Request#params so they can be embedded in HTML or JavaScript without any further issues.

    diff --git a/_includes/rack-protection-form-token.html b/_includes/rack-protection-form-token.html index b83ce3e..160f9ca 100644 --- a/_includes/rack-protection-form-token.html +++ b/_includes/rack-protection-form-token.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_request_forgery

    +

    en.wikipedia.org/wiki/Cross-site_request_forgery

    Only accepts submitted forms if a given access token matches the token included in the session. Does not expect such a token from Ajax request.

    diff --git a/_includes/rack-protection-http-origin.html b/_includes/rack-protection-http-origin.html index 20f9d7f..4183907 100644 --- a/_includes/rack-protection-http-origin.html +++ b/_includes/rack-protection-http-origin.html @@ -6,14 +6,14 @@

    Google Chrome 2, Safari 4 and later

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_request_forgery tools.ietf.org/html/draft-abarth-origin

    +

    en.wikipedia.org/wiki/Cross-site_request_forgery tools.ietf.org/html/draft-abarth-origin

    Does not accept unsafe HTTP requests when value of Origin HTTP request header does not match default or permitted URIs.

    If you want to permit a specific domain, you can pass in as the ‘:permitted_origins` option:

    -
    use Rack::Protection, permitted_origins: ["http://localhost:3000", "https://127.0.01:3000"]
    +
    use Rack::Protection, permitted_origins: ["http://localhost:3000", "http://127.0.01:3000"]
     

    The ‘:allow_if` option can also be set to a proc to use custom allow/deny logic.

    diff --git a/_includes/rack-protection-ip-spoofing.html b/_includes/rack-protection-ip-spoofing.html index cad9015..a2be2bc 100644 --- a/_includes/rack-protection-ip-spoofing.html +++ b/_includes/rack-protection-ip-spoofing.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    blog.c22.cc/2011/04/22/surveymonkey-ip-spoofing/

    +

    blog.c22.cc/2011/04/22/surveymonkey-ip-spoofing/

    Detect (some) IP spoofing attacks.

    diff --git a/_includes/rack-protection-json-csrf.html b/_includes/rack-protection-json-csrf.html index 8f34865..92515fb 100644 --- a/_includes/rack-protection-json-csrf.html +++ b/_includes/rack-protection-json-csrf.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    flask.pocoo.org/docs/0.10/security/#json-security haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx

    +

    flask.pocoo.org/docs/0.10/security/#json-security haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx

    JSON GET APIs are vulnerable to being embedded as JavaScript when the Array prototype has been patched to track data. Checks the referrer even on GET requests if the content type is JSON.

    diff --git a/_includes/rack-protection-path-traversal.html b/_includes/rack-protection-path-traversal.html index 7497049..3b324cb 100644 --- a/_includes/rack-protection-path-traversal.html +++ b/_includes/rack-protection-path-traversal.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Directory_traversal

    +

    en.wikipedia.org/wiki/Directory_traversal

    Unescapes ‘/’ and ‘.’, expands path_info. Thus GET /foo/%2e%2e%2fbar becomes GET /bar.

    diff --git a/_includes/rack-protection-readme.html b/_includes/rack-protection-readme.html index a0d5daf..bcfea39 100644 --- a/_includes/rack-protection-readme.html +++ b/_includes/rack-protection-readme.html @@ -36,14 +36,14 @@

    Cross Site Request Forgery

    Cross Site Scripting

    @@ -52,10 +52,10 @@

    Cross Site Scripting

    Clickjacking

    @@ -63,7 +63,7 @@

    Clickjacking

    Prevented by:

    Directory Traversal

    @@ -71,7 +71,7 @@

    Directory Traversal

    Prevented by:

    Session Hijacking

    @@ -79,7 +79,8 @@

    Session Hijacking

    Prevented by:

    @@ -87,7 +88,8 @@

    Prevented by:

    IP Spoofing

    @@ -95,7 +97,7 @@

    IP Spoofing

    Prevented by:

    @@ -104,7 +106,7 @@

  • +Rack::Protection::StrictTransport (not included by use Rack::Protection)

    Installation

    @@ -114,9 +116,9 @@

    Installation

    Instrumentation

    -

    Instrumentation is enabled by passing in an instrumenter as an option. +

    Instrumentation is enabled by passing in an instrumenter as an option.

    -
     use Rack::Protection, instrumenter: ActiveSupport::Notifications
    +
    use Rack::Protection, instrumenter: ActiveSupport::Notifications
     

    The instrumenter is passed a namespace (String) and environment (Hash). The namespace is ‘rack.protection’ and the attack type can be obtained from the environment key ‘rack.protection.attack’.

    diff --git a/_includes/rack-protection-remote-referrer.html b/_includes/rack-protection-remote-referrer.html index 9e91322..0fc1aa5 100644 --- a/_includes/rack-protection-remote-referrer.html +++ b/_includes/rack-protection-remote-referrer.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_request_forgery

    +

    en.wikipedia.org/wiki/Cross-site_request_forgery

    Does not accept unsafe HTTP requests if the Referer [sic] header is set to a different host.

    diff --git a/_includes/rack-protection-remote-token.html b/_includes/rack-protection-remote-token.html index 8e715ba..bf484fe 100644 --- a/_includes/rack-protection-remote-token.html +++ b/_includes/rack-protection-remote-token.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Cross-site_request_forgery

    +

    en.wikipedia.org/wiki/Cross-site_request_forgery

    Only accepts unsafe HTTP requests if a given access token matches the token included in the session or the request comes from the same origin.

    diff --git a/_includes/rack-protection-session-hijacking.html b/_includes/rack-protection-session-hijacking.html index 8b1f17c..9098f02 100644 --- a/_includes/rack-protection-session-hijacking.html +++ b/_includes/rack-protection-session-hijacking.html @@ -6,7 +6,7 @@

    all

    More infos
    -

    en.wikipedia.org/wiki/Session_hijacking

    +

    en.wikipedia.org/wiki/Session_hijacking

    Tracks request properties like the user agent in the session and empties the session if those properties change. This essentially prevents attacks from Firesheep. Since all headers taken into consideration can be spoofed, too, this will not prevent determined hijacking attempts.

    diff --git a/_includes/rack-protection-xss-header.html b/_includes/rack-protection-xss-header.html index 2b02071..363b0b2 100644 --- a/_includes/rack-protection-xss-header.html +++ b/_includes/rack-protection-xss-header.html @@ -6,7 +6,7 @@

    Internet Explorer 8+ and Chrome

    More infos
    -

    blogs.msdn.com/b/ie/archive/2008/07/01/ie8-security-part-iv-the-xss-filter.aspx

    +

    blogs.msdn.com/b/ie/archive/2008/07/01/ie8-security-part-iv-the-xss-filter.aspx

    Sets X-XSS-Protection header to tell the browser to block attacks.

    diff --git a/_includes/sinatra-contrib-readme.html b/_includes/sinatra-contrib-readme.html index 1c6a2f0..6fa23fd 100644 --- a/_includes/sinatra-contrib-readme.html +++ b/_includes/sinatra-contrib-readme.html @@ -22,49 +22,49 @@

    Common Extensions

    @@ -77,7 +77,7 @@

    Custom Extensions

    • -sinatra/reloader: Automatically reloads Ruby files on code changes. DEPRECATED: Please consider +sinatra/reloader: Automatically reloads Ruby files on code changes. DEPRECATED: Please consider consider using an alternative like rerun or rack-unreloader instead.
    @@ -86,7 +86,7 @@

    Other Tools

    DependencySlimSlim Lang
    File Extension