asana2flowdock 1.0.0

data/vendor/bundle/ruby/1.9.1/gems/sequel-4.15.0/doc/security.rdoc

@@ -0,0 +1,370 @@
+= 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::Schema::CreateTableGenerator.add_type_method
+* Sequel::Dataset.def_mutation_method
+* Sequel::Dataset.def_sql_method
+* Sequel::Model::Plugins.def_dataset_methods
+* Sequel.def_adapter_method (private)
+* Sequel::SQL::Expression.to_s_method (private)
+* Sequel::Plugins::HookClassMethods::ClassMethods#add_hook_type
+
+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, including:
+
+* Sequel::Database#execute
+* Sequel::Database#run
+* Sequel::Database#<<
+* Sequel::Database#[]
+* Sequel::Database#fetch
+* Sequel::Dataset#with_sql
+
+Here are some examples of use:
+
+  DB.run 'SQL'
+  DB << 'SQL'
+  DB.execute 'SQL'
+  DB['SQL'].all
+  DB.fetch('SQL').all
+  DB.dataset.with_sql('SQL').all
+
+If you pass a string to these methods that is derived from user input, you open
+yourself up to SQL injection.  The Sequel::Database#run, Sequel::Database#<<, and
+Sequel::Database#execute methods are not designed to work at all with user input.
+If you must use 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)}"
+
+With Sequel::Database#[], Sequel::Database#fetch and Sequel::Dataset#with_sql, you should use placeholders,
+in which case Sequel automatically literalizes 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 String#lit
+if the {core_extensions}[rdoc-ref:doc/core_extensions.rdoc] are in use,
+or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] if they are not in use.
+
+  'a'.lit
+  Sequel.lit('a')
+
+Using String#lit or 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:
+
+  'a = ?'.lit(params[:user_id].to_s)
+  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
+
+The most common way to use raw SQL with Sequel is in filters:
+
+  DB[:table].where("name > 'M'")
+
+If a filter method is passed a string as the first argument, it treats the rest of
+the arguments (if any) as placeholders to the string.  So you should never do:
+
+  DB[:table].where("name > #{params[:id].to_s}") # SQL Injection!
+
+Instead, you should use a placeholder:
+
+  DB[:table].where("name > ?", params[:id].to_s) # Safe
+ 
+Note that for that type of query, Sequel generally encourages the following form:
+
+  DB[:table].where{|o| o.name > params[:id].to_s} # Safe
+
+Sequel's DSL supports a wide variety of SQL concepts, so it's possible to
+code most applications without ever using raw SQL.
+
+A large number of dataset methods ultimately pass down their arguments to a filter
+method, even some you may not expect, so you should be careful.  At least the
+following methods pass their arguments to a filter method:
+
+* Sequel::Dataset#where
+* Sequel::Dataset#having
+* Sequel::Dataset#filter
+* Sequel::Dataset#exclude
+* Sequel::Dataset#exclude_where
+* Sequel::Dataset#exclude_having
+* Sequel::Dataset#and
+* Sequel::Dataset#or
+* Sequel::Dataset#first
+* Sequel::Dataset#last
+* Sequel::Dataset#[]
+* Sequel::Dataset#[]=
+
+The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
+class methods also call down to the filter methods.
+
+==== SQL Fragment passed to Dataset#update
+
+Similar to the filter methods, Sequel::Dataset#update also treats a
+string argument as raw SQL:
+
+  DB[:table].update("column = 1")
+
+So you should not do:
+
+  DB[:table].update("column = #{params[:value].to_s}") # SQL Injection!
+
+Instead, you should do:
+
+  DB[:table].update(:column => params[:value].to_s) # Safe
+
+==== SQL Fragment passed to Dataset#lock_style
+
+The Sequel::Dataset#lock_style method also treats an input string 
+as SQL code. This method should not be called with user input.
+
+==== 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.
+
+==== SQL Function Names
+
+In most cases, Sequel does not quote SQL function names.  You should not use
+user input for function names.
+
+=== 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 and Informix.
+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] 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, and possibly a more serious
+vulnerability.
+
+== Denial of Service
+
+Sequel converts some strings to symbols.  Because symbols in ruby 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 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
+
+Instead of these methods, it is encouraged to either use the
+Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only],
+Model#update_only[rdoc-ref:Sequel::Model::InstanceMethods#update_only],
+Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields], or
+Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields]
+methods, 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_only(params[:album], [:name, :copies_sold])
+  album.set_fields(params[:album], [:name, :copies_sold])
+
+You can override the columns to allow by default during mass assignment via
+the Model.set_allowed_columns[rdoc-ref:Sequel::Model::ClassMethods#set_allowed_columns] class method.  This is a good
+practice, though being explicit on a per-call basis is still recommended:
+
+  Album.set_allowed_columns(:name, :copies_sold)
+  Album.create(params[:album]) # Only name and copies_sold set
+
+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, params\[:id\] could
+be a string, an array, a hash, or nil.
+
+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{|i| i.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.

data/vendor/bundle/ruby/1.9.1/gems/sequel-4.15.0/doc/sharding.rdoc

@@ -0,0 +1,245 @@
+= Read-Only Slaves/Writable Master and Database Sharding
+
+Sequel has support for read only slave databases
+with a writable master database, as well as database sharding (where you can
+pick a server to use for a given dataset).  Support for both
+features is database independent, and should work for all database adapters
+that ship with Sequel.
+
+== The :servers Database option
+
+Sharding and read_only support are both enabled via the :servers database
+option.  Using the :servers database option makes Sequel use a connection pool
+class that supports sharding, and the minimum required to enable sharding
+support is to use the empty hash:
+
+  DB=Sequel.connect('postgres://master_server/database', :servers=>{})
+
+In most cases, you are probably not going to want to use an empty hash.  Keys in the server hash are
+not restricted to type, but the general recommendation is to use a symbol
+unless you have special requirements. Values in the server hash should be
+either hashes or procs that return hashes. These hashes are merged into
+the Database object's default options hash to get the connection options
+for the shard, so you don't need to override all options, just the ones
+that need to be modified.  For example, if you are using the same user,
+password, and database name and just the host is changing, you only need
+a :host entry in each shard's hash.
+
+Note that all servers should have the same schema for all
+tables you are accessing, unless you really know what you are doing.
+
+== Master and Slave Database Configurations
+
+=== Single Read-Only Slave, Single Master
+
+To use a single, read-only slave that handles SELECT queries, the following
+is the simplest configuration:
+
+  DB=Sequel.connect('postgres://master_server/database', \
+    :servers=>{:read_only=>{:host=>'slave_server'}})
+
+This will use the slave_server for SELECT queries and master_server for
+other queries.
+
+=== Multiple Read-Only Slaves, Single Master
+
+Let's say you have 4 slave database servers with names slave_server0,
+slave_server1, slave_server2, and slave_server3.
+
+  DB=Sequel.connect('postgres://master_server/database', \
+    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}})
+  def DB.get_slave_host
+    @current_host ||= -1
+    "slave_server#{(@current_host+=1)%4}"
+  end
+
+This will use one of the slave servers for SELECT queries and use the
+master_server for other queries.  It's also possible to pick a random host
+instead of using the round robin approach presented above, but that can result
+in less optimal resource usage.
+
+=== Multiple Read-Only Slaves, Multiple Masters
+
+This involves the same basic idea as the multiple slaves, single master, but
+it shows that the master database is named :default.  So for 4 masters and
+4 slaves:
+
+  DB=Sequel.connect('postgres://master_server/database', \
+    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}, \
+      :default=>proc{|db| {:host=>db.get_master_host}}})
+  def DB.get_slave_host
+    @current_slave_host ||= -1
+    "slave_server#{(@current_slave_host+=1)%4}"
+  end
+  def DB.get_master_host
+    @current_master_host ||= -1
+    "master_server#{(@current_master_host+=1)%4}"
+  end
+  
+== Sharding
+
+There is specific support in Sequel for handling master/slave database
+combinations, with the only necessary setup being the database configuration.
+However, since sharding is always going to be implementation dependent, Sequel
+supplies the basic infrastructure, but you have to tell it which server to use
+for each dataset.  Let's assume a simple scenario, a distributed rainbow
+table for SHA-1 hashes, sharding based on the first hex character (for a total
+of 16 shards).  First, you need to configure the database:
+
+  servers = {}
+  (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
+    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
+  end
+  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers)
+  
+This configures 17 servers, the 16 shard servers (/hash_host_[0-9a-f]/), and 1
+default server which will be used if no shard is specified ("hash_host").  If
+you want the default server to be one of the shard servers (e.g. hash_host_a),
+it's easiest to do:
+
+  DB=Sequel.connect('postgres://hash_host_a/hashes', :servers=>servers)
+
+That will still set up a second pool of connections for the default server,
+since it considers the default server and shard servers independent.  Note that
+if you always set the shard on a dataset before using it in queries, it will
+not attempt to connect to the default server.  Sequel may use the default
+server in queries it generates itself, such as to get column names or table
+schemas, so you should always have a default server that works.
+
+To set the shard for a given query, you use the Dataset#server method:
+
+  DB[:hashes].server(:a).where(:hash=>/31337/)
+  
+That will return all matching rows on the hash_host_a shard that have a hash
+column that contains 31337.
+
+Rainbow tables are generally used to find specific hashes, so to save some
+work, you might want to add a method to the dataset that automatically sets
+the shard to use.  This is fairly easy using a Sequel::Model:
+
+  class Rainbow < Sequel::Model(:hashes)
+    dataset_module do
+      def plaintext_for_hash(hash)
+        raise(ArgumentError, 'Invalid SHA-1 Hash') unless /\A[0-9a-f]{40}\z/.match(hash)
+        server(hash[0...1].to_sym).where(:hash=>hash).get(:plaintext)
+      end
+    end
+  end
+  
+  Rainbow.plaintext_for_hash("e580726d31f6e1ad216ffd87279e536d1f74e606")
+
+The connection pool can be further controlled to change how it handles attempts
+to access shards that haven't been configured.  The default is
+to assume the :default shard.  However, you can specify a
+different shard using the :servers_hash option when connecting
+to the database:
+
+  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new(:some_shard))
+
+You can also use this feature to raise an exception if an
+unconfigured shard is used:
+
+  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new{raise 'foo'})
+
+If you specify a :servers_hash option to raise an exception for non configured
+shards you should also explicitly specify a :read_only entry in your :servers option
+for the case where a shard is not specified. In most cases it is sufficient
+to make the :read_only entry the same as the :default shard:
+
+  servers = {:read_only => {}}
+  (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
+    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
+  end
+  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers, 
+    :servers_hash=>Hash.new{raise Exception.new("Invalid Server")}) 
+
+=== Sharding Plugin
+
+Sequel comes with a sharding plugin that makes it easy to use sharding with model objects.
+It makes sure that objects retrieved from a specific shard are always saved back to that
+shard, allows you to create objects on specific shards, and even makes sure associations
+work well with shards.  You just need to remember to set to model to use the plugin:
+
+  class Rainbow < Sequel::Model(:hashes)
+    plugin :sharding
+  end
+
+  Rainbow.server(:a).first(:id=>1).update(:plaintext=>'VGM')
+
+If all of your models are sharded, you can set all models to use the plugin via:
+
+  Sequel::Model.plugin :sharding
+
+=== server_block Extension
+
+By default, you must specify the server/shard you want to use for every dataset/action,
+or Sequel will use the default shard.  If you have a group of queries that should use the
+same shard, it can get a bit redundent to specify the same shard for all of them.
+
+The server_block extension adds a Database#with_server method that scopes all database
+access inside the block to the given shard by default:
+
+  DB.extension :server_block
+  DB.with_server(:a) do
+    # this SELECT query uses the "a" shard
+    if r = Rainbow.first(:hash=>/31337/)
+      r.count += 1
+      # this UPDATE query also uses the "a" shard
+      r.save
+    end
+  end
+
+The server_block extension doesn't currently integrate with the sharding plugin, as it
+ties into the Dataset#server method.  This shouldn't present a problem in practice as
+long as you just access the models inside the with_server block, since they will use
+the shard set by with_server by default.  However, you will probably have issues if
+you retrieve the models inside the block and save them outside of the block.  If you
+need to do that, call the server method explicitly on the dataset used to retrieve the
+model objects.
+
+=== arbitrary_servers Extension
+
+By default, Sequel's sharding support is designed to work with predefined shards.  It ships
+with Database#add_servers and Database#remove_servers methods to modify these predefined
+shards on the fly, but it is a bit cumbersome to work with truly arbitrary servers
+(requiring you to call add_servers before use, then remove_servers after use).
+
+The arbitrary_servers extension allows you to pass a server/shard options hash as the
+server to use, and those options will be merged directly into the database's default options:
+
+  DB.extension :arbitrary_servers
+  DB[:rainbows].server(:host=>'hash_host_a').all
+  # or
+  DB[:rainbows].server(:host=>'hash_host_b', :database=>'backup').all
+
+arbitrary_servers is designed to work well in conjunction with the server_block extension:
+
+  DB.with_server(:host=>'hash_host_b', :database=>'backup') do
+    DB.synchronize do
+      # All queries here default to the backup database on hash_host_b
+    end
+  end
+
+If you are using arbitrary_servers with server_block, you may want to
+define the following method (or something similar) so that you don't
+need to call synchronize separately:
+
+  def DB.with_server(*)
+    super{synchronize{yield}}
+  end
+
+The reason for the synchronize method is that it checks out a connection
+and makes the same connection available for the duration of the block.
+If you don't do that, Sequel will probably disconnect from the database
+and reconnect to the database on each request, since connections to
+arbitrary servers are not cached.
+
+Note that this extension only works with the sharded threaded connection
+pool.  If you are using the sharded single connection pool, you need
+to switch to the sharded threaded connection pool before using this
+extension.  If you are passing the :single_threaded option to
+the Database, just remove that option.  If you are setting:
+
+  Sequel.single_threaded = true 
+
+just remove or comment out that code.