sequel 5.83.0 → 5.84.0

data/doc/security.rdoc

@@ -1,443 +0,0 @@
-= Security Considerations with Sequel
-
-When using Sequel, there are some security areas you should be aware of:
-
-* Code Execution
-* SQL Injection
-* Denial of Service
-* Mass Assignment
-* General Parameter Handling
-
-== Code Execution
-
-The most serious security vulnerability you can have in any library is
-a code execution vulnerability.  Sequel should not be vulnerable to this,
-as it never calls eval on a string that is derived from user input.
-However, some Sequel methods used for creating methods via metaprogramming
-could conceivably be abused to do so:
-
-* Sequel::Dataset.def_sql_method
-* Sequel::JDBC.load_driver
-* Sequel::Plugins.def_dataset_methods
-* Sequel::Dataset.prepared_statements_module (private)
-* Sequel::SQL::Expression.to_s_method (private)
-
-As long as you don't call those with user input, you should not be
-vulnerable to code execution.
-
-== SQL Injection
-
-The primary security concern in SQL database libraries is SQL injection.
-Because Sequel promotes using ruby objects for SQL concepts instead
-of raw SQL, it is less likely to be vulnerable to SQL injection.
-However, because Sequel still makes it easy to use raw SQL, misuse of the
-library can result in SQL injection in your application.
-
-There are basically two kinds of possible SQL injections in Sequel:
-
-* SQL code injections
-* SQL identifier injections
-
-=== SQL Code Injections
-
-==== Full SQL Strings
-
-Some Sequel methods are designed to execute raw SQL strings, including:
-
-* Sequel::Database#execute
-* Sequel::Database#execute_ddl
-* Sequel::Database#execute_dui
-* Sequel::Database#execute_insert
-* Sequel::Database#run
-* Sequel::Database#<<
-* Sequel::Dataset#fetch_rows
-* Sequel::Dataset#with_sql_all
-* Sequel::Dataset#with_sql_delete
-* Sequel::Dataset#with_sql_each
-* Sequel::Dataset#with_sql_first
-* Sequel::Dataset#with_sql_insert
-* Sequel::Dataset#with_sql_single_value
-* Sequel::Dataset#with_sql_update
-
-Here are some examples of use:
-
-  DB.execute 'SQL'
-  DB.execute_ddl 'SQL'
-  DB.execute_dui 'SQL'
-  DB.execute_insert 'SQL'
-  DB.run 'SQL'
-  DB << 'SQL'
-  DB.fetch_rows('SQL'){|row| }
-  DB.dataset.with_sql_all('SQL')
-  DB.dataset.with_sql_delete('SQL')
-  DB.dataset.with_sql_each('SQL'){|row| }
-  DB.dataset.with_sql_first('SQL')
-  DB.dataset.with_sql_insert('SQL')
-  DB.dataset.with_sql_single_value('SQL')
-  DB.dataset.with_sql_update('SQL')
-
-If you pass a string to these methods that is derived from user input, you open
-yourself up to SQL injection.  These methods are not designed to work at all
-with user input.  If you must call them with user input, you should escape the
-user input manually via Sequel::Database#literal. Example:
-
-  DB.run "SOME SQL #{DB.literal(params[:user].to_s)}"
-
-==== Full SQL Strings, With Possible Placeholders
-
-Other Sequel methods are designed to support execution of raw SQL strings that may contain placeholders:
-
-* Sequel::Database#[]
-* Sequel::Database#fetch
-* Sequel::Dataset#with_sql
-
-Here are some examples of use:
-
-  DB['SQL'].all
-  DB.fetch('SQL').all
-  DB.dataset.with_sql('SQL').all
-
-With these methods you should use placeholders, in which case Sequel automatically escapes the input:
-
-  DB['SELECT * FROM foo WHERE bar = ?', params[:user].to_s]
-
-==== Manually Created Literal Strings
-
-Sequel generally treats ruby strings as SQL strings (escaping them correctly), and
-not as raw SQL.  However, you can convert a ruby string to a literal string, and
-Sequel will then treat it as raw SQL.  This is typically done through
-Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit].
-
-  Sequel.lit('a')
-
-Using Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] to turn a ruby string into a literal string results
-in SQL injection if the string is derived from user input.  With both of these
-methods, the strings can contain placeholders, which you can use to safely include
-user input inside a literal string:
-
-  Sequel.lit('a = ?', params[:user_id].to_s)
-
-Even though they have similar names, note that Sequel::Database#literal operates very differently from
-String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit].
-Sequel::Database#literal is for taking any supported object,
-and getting an SQL representation of that object, while
-String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] are for treating
-a ruby string as raw SQL.  For example:
-
-  DB.literal(Date.today) # "'2013-03-22'"
-  DB.literal('a') # "'a'"
-  DB.literal(Sequel.lit('a')) # "a"
-  DB.literal(a: 'a') # "(\"a\" = 'a')"
-  DB.literal(a: Sequel.lit('a')) # "(\"a\" = a)"
-
-==== SQL Filter Fragments
-
-Starting in Sequel 5, Sequel does not automatically convert plain strings to
-literal strings in typical code.  Instead, you can use Sequel.lit to
-create literal strings:
-
-  Sequel.lit("name > 'A'")
-
-To safely include user input as part of an SQL filter fragment, use Sequel.lit
-with placeholders:
-
-  DB[:table].where(Sequel.lit("name > ?", params[:id].to_s)) # Safe
-
-Be careful to never call Sequel.lit where the first argument is derived from
-user input.
-
-There are a few uncommon cases where Sequel will still convert
-plain strings to literal strings.
-
-==== SQL Fragment passed to Dataset#lock_style and Model#lock!
-
-The Sequel::Dataset#lock_style and Sequel::Model#lock! methods also treat
-an input string as SQL code. These methods should not be called with user input.
-
-  DB[:table].lock_style(params[:id]) # SQL injection!
-  Album.first.lock!(params[:id]) # SQL injection!
-
-==== SQL Type Names
-
-In general, most places where Sequel needs to use an SQL type that should
-be specified by the user, it allows you to use a ruby string, and that
-string is used verbatim as the SQL type.  You should not use user input
-for type strings.
-
-  DB[:table].select(Sequel.cast(:a, params[:id])) # SQL injection!
-
-==== SQL Function Names
-
-In most cases, Sequel does not quote SQL function names.  You should not use
-user input for function names.
-
-  DB[:table].select(Sequel.function(params[:id])) # SQL injection!
-
-==== SQL Window Frames
-
-For backwards compatibility, Sequel supports regular strings in the
-window function :frame option, which will be treated as a literal string:
-
-  DB[:table].select{fun(arg).over(frame: 'SQL Here')}
-
-You should make sure the frame argument is not derived from user input,
-or switch to using a hash as the :frame option value.
-
-==== auto_literal_strings extension
-
-If the auto_literal_strings extension is used for backwards compatibility,
-then Sequel will treat plain strings as literal strings if they are used
-as the first argument to a filtering method.  This can lead to SQL
-injection:
-
-  DB[:table].where("name > #{params[:id].to_s}")
-  # SQL injection when using auto_literal_strings extension
-
-If you are using the auto_literal_strings extension, you need to be very careful,
-as the following methods will treat a plain string given as the first argument
-as a literal string:
-
-* Sequel::Dataset#where
-* Sequel::Dataset#having
-* Sequel::Dataset#filter
-* Sequel::Dataset#exclude
-* Sequel::Dataset#exclude_having
-* Sequel::Dataset#or
-* Sequel::Dataset#first
-* Sequel::Dataset#last
-* Sequel::Dataset#[]
-
-Even stuff that looks like it may be safe isn't:
-
-  DB[:table].first(params[:num_rows])
-  # SQL injection when using auto_literal_strings extension
-
-The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and
-Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
-class methods will also treat string arguments as literal strings if the
-auto_literal_strings extension is used:
-
-  Album.find(params[:id])
-  # SQL injection when using auto_literal_strings extension
-
-Similar to the filter methods, the auto_literal_strings extension
-also makes Sequel::Dataset#update treats a string argument as raw SQL:
-
-  DB[:table].update("column = 1")
-
-So you should not do:
-
-  DB[:table].update(params[:changes])
-  # SQL injection when using auto_literal_strings extension
-
-or:
-
-  DB[:table].update("column = #{params[:value].to_s}")
-  # SQL injection when using auto_literal_strings extension
-
-Instead, you should do:
-
-  DB[:table].update(column: params[:value].to_s) # Safe
-
-Because using the auto_literal_strings extension makes SQL injection
-so much eaiser, it is recommended to not use it, and instead
-use Sequel.lit with placeholders.
- 
-=== SQL Identifier Injections
-
-Usually, Sequel treats ruby symbols as SQL identifiers, and ruby
-strings as SQL strings.  However, there are some parts of Sequel
-that treat ruby strings as SQL identifiers if an SQL string would
-not make sense in the same context.
-
-For example, Sequel::Database#from and Sequel::Dataset#from will treat a string as
-a table name:
-
-  DB.from('t') # SELECT * FROM "t"
-
-Another place where Sequel treats ruby strings as identifiers are
-the Sequel::Dataset#insert and Sequel::Dataset#update methods:
-
-  DB[:t].update('b'=>1) # UPDATE "t" SET "b" = 1
-  DB[:t].insert('b'=>1) # INSERT INTO "t" ("b") VALUES (1)
-
-Note how the identifier is still quoted in these cases.  Sequel quotes identifiers by default
-on most databases.  However, it does not quote identifiers by default on DB2.
-On those databases using an identifier derived from user input can lead to SQL injection.
-Similarly, if you turn off identifier quoting manually on other databases, you open yourself
-up to SQL injection if you use identifiers derived from user input.
-
-When Sequel quotes identifiers, using an identifier derived from user input does not lead to
-SQL injection, since the identifiers are also escaped when quoting.
-Exceptions to this are Oracle (can't escape <tt>"</tt>) and Microsoft Access
-(can't escape <tt>]</tt>).
-
-In general, even if doesn't lead to SQL Injection, you should avoid using identifiers
-derived from user input unless absolutely necessary.
-
-Sequel also allows you to create identifiers using
-Sequel.identifier[rdoc-ref:Sequel::SQL::Builders#identifier] for plain identifiers,
-Sequel.qualify[rdoc-ref:Sequel::SQL::Builders#qualify] and
-Sequel::SQL::Indentifier#[][rdoc-ref:Sequel::SQL::QualifyingMethods#[]] for qualified identifiers, and
-Sequel.as[rdoc-ref:Sequel::SQL::Builders#as] for aliased expressions.  So if you
-pass any of those values derived from user input, you are dealing with the same scenario.
-
-Note that the issues with SQL identifiers do not just apply to places where
-strings are used as identifiers, they also apply to all places where Sequel
-uses symbols as identifiers.  However, if you are creating symbols from user input,
-you at least have a denial of service vulnerability in ruby <2.2, and possibly a
-more serious vulnerability.
-
-Note that many Database schema modification methods (e.g. create_table, add_column)
-also allow for SQL identifier injections, and possibly also SQL code injections.
-These methods should never be called with user input.
-
-== Denial of Service
-
-Sequel converts some strings to symbols.  Because symbols in ruby <2.2 are not
-garbage collected, if the strings that are converted to symbols are
-derived from user input, you have a denial of service vulnerability due to
-memory exhaustion.
-
-The strings that Sequel converts to symbols are generally not derived
-from user input, so Sequel in general is not vulnerable to this.  However,
-users should be aware of the cases in which Sequel creates symbols, so
-they do not introduce a vulnerability into their application.
-
-=== Column Names/Aliases
-
-Sequel returns SQL result sets as an array of hashes with symbol keys.  The
-keys are derived from the name that the database server gives the column. These
-names are generally static.  For example:
-
-  SELECT column FROM table
-
-The database will generally use "column" as the name in the result set.
-
-If you use an alias:
-
-  SELECT column AS alias FROM table
-
-The database will generally use "alias" as the name in the result set. So
-if you allow the user to control the alias name:
-
-  DB[:table].select(:column.as(params[:alias]))
-
-Then you can have a denial of service vulnerability.  In general, such a vulnerability
-is unlikely, because you are probably indexing into the returned hash(es) by name,
-and if an alias was used and you didn't expect it, your application wouldn't work.
-
-=== Database Connection Options
-
-All database connection options are converted to symbols.  For a
-connection URL, the keys are generally fixed, but the scheme is turned
-into a symbol and the query option keys are used as connection option
-keys, so they are converted to symbols as well.  For example:
-
-  postgres://host/database?option1=foo&option2=bar
-
-Will result in :postgres, :option1, and :option2 symbols being created.
-
-Certain option values are also converted to symbols.  In the general case,
-the sql_log_level option value is, but some adapters treat additional
-options similarly.
-
-This is not generally a risk unless you are allowing the user to control
-the connection URLs or are connecting to arbitrary databases at runtime.
-
-== Mass Assignment
-
-Mass assignment is the practice of passing a hash of columns and values
-to a single method, and having multiple column values for a given object set
-based on the content of the hash.
-The security issue here is that mass assignment may allow the user to
-set columns that you didn't intend to allow.
-
-The Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set] and Model#update[rdoc-ref:Sequel::Model::InstanceMethods#update] methods do mass
-assignment.  The default configuration of Sequel::Model allows all model
-columns except for the primary key column(s) to be set via mass assignment.
-
-Example:
-
-  album = Album.new
-  album.set(params[:album]) # Mass Assignment
-
-Both Model.new[rdoc-ref:Sequel::Model::InstanceMethods::new] and Model.create[rdoc-ref:Sequel::Model::ClassMethods#create]
-call Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set] internally, so
-they also allow mass assignment:
-
-  Album.new(params[:album]) # Mass Assignment
-  Album.create(params[:album]) # Mass Assignment
-
-When the argument is derived from user input, instead of these methods, it is encouraged to either use 
-Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields] or
-Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields],
-which allow you to specify which fields to allow on a per-call basis.  This
-pretty much eliminates the chance that the user will be able to set a column
-you did not intend to allow:
-
-  album.set_fields(params[:album], [:name, :copies_sold])
-  album.update_fields(params[:album], [:name, :copies_sold])
-
-These two methods iterate over the second argument (+:name+ and +:copies_sold+ in
-this example) instead of iterating over the entries in the first argument
-(<tt>params[:album]</tt> in this example).
-
-If you want to override the columns that Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set]
-allows by default during mass assignment, you can use the whitelist_security plugin, then call
-the set_allowed_columns class method.
-
-  Album.plugin :whitelist_security
-  Album.set_allowed_columns(:name, :copies_sold)
-  Album.create(params[:album]) # Only name and copies_sold set
-
-Being explicit on a per-call basis using the set_fields and update_fields methods is recommended
-instead of using the whitelist_security plugin and setting a global whitelist.
-
-For more details on the mass assignment methods, see the {Mass Assignment Guide}[rdoc-ref:doc/mass_assignment.rdoc].
-
-== General Parameter Handling
-
-This issue isn't necessarily specific to Sequel, but it is a good general practice.
-If you are using values derived from user input, it is best to be explicit about
-their type.  For example:
-
-  Album.where(id: params[:id])
-
-is probably a bad idea.  Assuming you are using a web framework, <tt>params[:id]</tt> could
-be a string, an array, a hash, nil, or potentially something else.
-
-Assuming that +id+ is an integer field, you probably want to do:
-
-  Album.where(id: params[:id].to_i)
-
-If you are looking something up by name, you should try to enforce the value to be
-a string:
-
-  Album.where(name: params[:name].to_s)
-
-If you are trying to use an IN clause with a list of id values based on input provided
-on a web form:
-
-  Album.where(id: params[:ids].to_a.map(&:to_i))
-
-Basically, be as explicit as possible. While there aren't any known security issues
-in Sequel when you do:
-
-  Album.where(id: params[:id])
-
-It allows the attacker to choose to do any of the following queries:
-
-  id IS NULL # nil
-  id = '1' # '1'
-  id IN ('1', '2', '3') # ['1', '2', '3']
-  id = ('a' = 'b') # {'a'=>'b'}
-  id = ('a' IN ('a', 'b') AND 'c' = '') # {'a'=>['a', 'b'], 'c'=>''}
-
-While none of those allow for SQL injection, it's possible that they
-might have an issue in your application.  For example, a long array
-or deeply nested hash might cause the database to have to do a lot of
-work that could be avoided.
-
-In general, it's best to let the attacker control as little as possible,
-and explicitly specifying types helps a great deal there.