unicorn-lockdown 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24ec67b0fb4c2a47aea2652b30a1b99973226d379492fff1a87c1aef3dba5038
-  data.tar.gz: 84ecb2a8a3a97929e4fc6c960eaee2cab8df0c9f784297e6a3b11ff00c8044f8
+  metadata.gz: 5246972fac1124b5bad333f7c94163ca00193f6ad621febaef8d833be05bb6b8
+  data.tar.gz: f015a78584e3fbbeecdfc961f49acdbd9b6f967d6e73e5e47300ccf3b3b15552
 SHA512:
-  metadata.gz: 866fcee1a554851025331f856fcb47e3f77f53967a79abda8fc89fd9ead7fd2c390f090338dc3a3047dca22d2b8e7f87595fe5dbc509e5636d825e56c0670544
-  data.tar.gz: bbec6a5aa7159b05ef7995ca56235f3c08cc001c1fbf6593d2ec1f2c99db457b2d998b01d866f1223b14c58e03e68bef348b0c8e0bbcf213ae38021a3d6da18a
+  metadata.gz: 1d10bca6474b0c6da80c244670e0edd1fd128fa7866285dad4efaf7c5634f48889db95499556330462d23415237bddb537c80e2316e4a2b935878cefc0c2da66
+  data.tar.gz: b325c37291644bc1b06d37ff6184db81c1355668a612a1cf1bb6516aeee199cf664cce13bb4fcaba2c1bfb2252087ced308f2efa6a5c26f2d78a805ab4a271d9

data/CHANGELOG

@@ -1,3 +1,9 @@
+= 0.13.0 (2019-07-09)
+
+* Add Chrooter.unveil for using unveil in tests (jeremyevans)
+
+* Support Unicorn.lockdown :unveil and :dev_unveil options for use of unveil instead of chroot (jeremyevans) 
+
 = 0.12.0 (2019-04-29)
 
 * Do not reference the rack middleware unicorn loads by default if unicorn is set to not load default middleware (jeremyevans)

data/README.rdoc

@@ -1,16 +1,17 @@
 = unicorn-lockdown
 
 unicorn-lockdown is a helper library for running Unicorn on OpenBSD in a way
-that supports security features such as chroot, privdrop, fork+exec,
+that supports security features such as chroot (or unveil), privdrop, fork+exec,
 and pledge.
 
 With the configuration unicorn-lockdown uses, the unicorn process executes as root,
 and the unicorn master process continues to run as root.  The master process
 forks worker processes, which re-exec (fork+exec) so that a new memory layout
 is used in each worker process.  The worker process then loads the application,
-after which it chroots to the application's directory, drops root privileges
-and then runs as the application user (privdrop), then runs pledge to limit
-the allowed system calls to the minimum required to run the application.
+after which it chroots to the application's directory (or uses unveil to limit
+file system permissions), drops root privileges and then runs as the application
+user (privdrop), then runs pledge to limit the allowed system calls to the minimum
+required to run the application.
 
 == Assumptions
 
@@ -21,6 +22,11 @@ the PATH to the appropriate unicornXY executable.
 It also assumes you have a SMTP server listening on localhost port 25 to
 receive notification emails of worker crashes, if you are notifying for those.
 
+If using unveil instead of chroot to limit file system access, you must be
+using OpenBSD 6.6+ (or 6.5-current after July 2019), one of the OpenBSD Ruby
+ports with backported support for unveil to work correctly with +File.realpath+,
+and version 1.2.0+ of the pledge gem.
+
 == Usage
 
 === unicorn-lockdown-setup
@@ -71,7 +77,7 @@ directory and can make modifications to the application.
 
 unicorn-lockdown is the library required in your unicorn configuration
 file for the application, to handle configuring unicorn to run the app
-with chroot, privdrop, fork+exec, and pledge.
+with chroot (or unveil), privdrop, fork+exec, and pledge.
 
 When you run unicorn-lockdown-add, it will create the unicorn configuration
 file for the app if one does not already exist, looking similar to:
@@ -81,7 +87,7 @@ file for the app if one does not already exist, looking similar to:
   Unicorn.lockdown(self,
     :app=>"app_name",
     :user=>"user_name", # Set application user here
-    :pledge=>'rpath prot_exec inet unix' # More may be needed
+    :pledge=>'rpath prot_exec inet unix', # More may be needed
     :email=>'root' # update this with correct email
   )
 
@@ -96,6 +102,13 @@ Unicorn.lockdown options:
           log files.
 :pledge :: (optional) a pledge string to limit the allowed system calls
            after privileges have been dropped
+:unveil :: (optional) a hash of paths to limit file system access, passed
+           to +Pledge.unveil+.  Forces use of unveil instead of chroot.
+:dev_unveil :: (optional, requires :unveil option) a hash of paths to
+               limit file system, merged into the :unveil option paths
+               if in the development environment.  Useful if you are
+               allowing more access in development, such as access needed
+               for file reloading.
 :email :: (optional) an email address to use for notifications when the
           worker process crashes or an unhandled exception is raised by
           the application or middleware.
@@ -202,6 +215,22 @@ the current directory after loading the specs, then drop
 privileges to the user given (and optionally pledging using the given
 pledge string), then run the specs.
 
+If you want to use unveil instead of chroot, you can use
++Chrooter.unveil+:
+
+  require 'minitest/autorun'
+  require 'chrooter'
+  at_exit do
+    Chrooter.unveil('user_name', 'rpath prot_exec inet unix',
+      'views' => 'r',
+      'rack' => :gem,
+      'mail' => :gem,
+    )
+  end
+
+One advantage of using unveil instead of chroot is that the unveils
+will take effect even when not starting the tests as root.
+
 == autoload
 
 As you'll find out if you try to run your applications with chroot,
@@ -211,6 +240,22 @@ If you use other gems that use autoload, you'll have to add code that
 references the autoloaded constants after the application is loaded but
 before chrooting.
 
+If you have to use libraries that use autoload, it is recommended that
+you use the support for unveil instead of using chroot, and allow
+access to the given gems.  unicorn-lockdown will automatically unveil
+the +rack+ gem, and will unveil the +mail+ gem if the +Mail+ constant
+is defined.
+
+  Unicorn.lockdown(self,
+    :app=>"app_name",
+    :user=>"user_name", # Set application user here
+    :pledge=>'rpath prot_exec inet unix', # More may be needed
+    :unveil=>{
+      'views' => 'r',
+      'gem-name' => :gem,
+    }
+  )
+
 == Author
 
 Jeremy Evans <code@jeremyevans.net>

data/lib/chrooter.rb

@@ -20,9 +20,36 @@ if defined?(SimpleCov) && Process.euid == 0
   raise "cannot run coverage testing in chroot mode"
 end
 
-# Chrooter allows for testing programs in both chroot and non
+# Chrooter allows for testing programs in both chroot/unveil and non
 # chroot modes.
 module Chrooter
+  # If the current user is the super user, drop privileges to
+  # the given +user+ first.
+  #
+  # Use Pledge.unveil to limit access to the file system based on the
+  # +unveil+ option.  Then pledge the process with the given +pledge+
+  # permissions (if given).
+  def self.unveil(user, pledge=nil, unveil={}, group=user)
+    require 'unveil'
+
+    unveil = Hash[unveil]
+    if defined?(Rack)
+      unveil['rack'] = :gem
+    end
+    if defined?(Mail)
+      unveil['mail'] = :gem
+    end
+
+    if Process.euid == 0
+      _drop_privs(user, group)
+      puts "Unveiled, running as user #{user}"
+    end
+
+    Pledge.unveil(unveil)
+
+    _pledge(pledge)
+  end
+
   # If the current user is the super user, change to the given
   # user/group, chroot to the given directory, and pledge
   # the process with the given permissions (if given).
@@ -75,15 +102,10 @@ module Chrooter
     end
 
     if Process.euid == 0
-      uid = Etc.getpwnam(user).uid
-      gid = Etc.getgrnam(group).gid
-      if Process.egid != gid
-        Process.initgroups(user, gid)
-        Process::GID.change_privilege(gid)
+      _drop_privs(user, group) do
+        Dir.chroot(dir)
+        Dir.chdir('/')
       end
-      Dir.chroot(dir)
-      Dir.chdir('/')
-      Process.euid != uid and Process::UID.change_privilege(uid)
       puts "Chrooted to #{dir}, running as user #{user}"
     else
       # Load minitest plugins before freezing loaded features,
@@ -97,6 +119,26 @@ module Chrooter
       $LOADED_FEATURES.freeze
     end
 
+    _pledge(pledge)
+  end
+
+  def self._drop_privs(user, group)
+    uid = Etc.getpwnam(user).uid
+    gid = Etc.getgrnam(group).gid
+    if Process.egid != gid
+      Process.initgroups(user, gid)
+      Process::GID.change_privilege(gid)
+    end
+
+    yield if block_given?
+
+    Process.euid != uid and Process::UID.change_privilege(uid)
+
+    nil
+  end
+  private_class_method :_drop_privs
+
+  def self._pledge(pledge)
     unless defined?(SimpleCov)
       if pledge
         # If running coverage tests, don't run pledged as coverage
@@ -107,4 +149,5 @@ module Chrooter
 
     nil
   end
+  private_class_method :_pledge
 end

data/lib/unicorn-lockdown.rb

@@ -59,6 +59,12 @@ class << Unicorn
   # The pledge string to use.
   attr_accessor :pledge
 
+  # The hash of unveil paths to use.
+  attr_accessor :unveil
+
+  # The hash of additional unveil paths to use if in the development environment.
+  attr_accessor :dev_unveil
+
   # The address to email for crash and unhandled exception notifications
   attr_accessor :email
 
@@ -86,12 +92,16 @@ class << Unicorn
   #           Can be an array of two strings, where the first string is the primary
   #           group, and the second string is the group used for the log files.
   # :pledge :: The string to use when pledging
+  # :unveil :: A hash of unveil paths
+  # :dev_unveil :: A hash of unveil paths to use in development
   def lockdown(configurator, opts)
     Unicorn.app_name = opts.fetch(:app)
     Unicorn.user_name = opts.fetch(:user)
     Unicorn.group_name = opts[:group] || opts[:user]
     Unicorn.email = opts[:email]
     Unicorn.pledge = opts[:pledge]
+    Unicorn.unveil = opts[:unveil]
+    Unicorn.dev_unveil = opts[:dev_unveil]
 
     configurator.instance_exec do
       listen "/var/www/sockets/#{Unicorn.app_name}.sock"
@@ -137,49 +147,74 @@ class << Unicorn
           end
         end
 
-        # Before chrooting, reference all constants that use autoload
-        # that are probably needed at runtime.  This must be done
-        # before chrooting as attempting to load the constants after
-        # chrooting will break things.
-        
-        # Start with rack, which uses autoload for all constants.
-        # Most of rack's constants are not used at runtime, this
-        # lists the ones most commonly needed.
-        Rack::Multipart
-        Rack::Multipart::Parser
-        Rack::Multipart::Generator
-        Rack::Multipart::UploadedFile
-        Rack::Mime
-        Rack::Auth::Digest::Params
-
-        # In the development environment, reference all middleware
-        # the unicorn will load by default, unless unicorn is
-        # set to not load middleware by default.
-        if ENV['RACK_ENV'] == 'development' && (!respond_to?(:set) || set[:default_middleware] != false)
-          Rack::ContentLength
-          Rack::CommonLogger
-          Rack::Chunked
-          Rack::Lint
-          Rack::ShowExceptions
-          Rack::TempfileReaper
-        end
+        if unveil = Unicorn.unveil
+          require 'unveil'
 
-        # If using the mail library, eagerly autoload all constants.
-        # This costs about 9MB of memory, but the mail gem changes
-        # their autoloaded constants on a regular basis, so it's
-        # better to be safe than sorry.
-        if defined?(Mail)
-          Mail.eager_autoload!
-        end
+          unveil = if Unicorn.dev_unveil && ENV['RACK_ENV'] == 'development'
+            unveil.merge(Unicorn.dev_unveil)
+          else
+            Hash[unveil]
+          end
+
+          # Allow read access to the rack gem directory, as rack autoloads constants.
+          unveil['rack'] = :gem
+
+          if defined?(Mail)
+            # If using the mail library, allow read access to the mail gem directory,
+            # as mail autoloads constants.
+            unveil['mail'] = :gem
+          end
 
-        # Strip path prefixes from the reloader.  This is only
-        # really need in development mode for code reloading to work.
-        pwd = Dir.pwd
-        Unreloader.strip_path_prefix(pwd) if defined?(Unreloader)
+          # Drop privileges
+          worker.user(Unicorn.user_name, Unicorn.group_name)
 
-        # Drop privileges.  This must be done after chrooting as
-        # chrooting requires root privileges.
-        worker.user(Unicorn.user_name, Unicorn.group_name, pwd)
+          # Restrict access to the file system based on the specified unveil.
+          Pledge.unveil(unveil)
+        else
+          # Before chrooting, reference all constants that use autoload
+          # that are probably needed at runtime.  This must be done
+          # before chrooting as attempting to load the constants after
+          # chrooting will break things.
+          
+          # Start with rack, which uses autoload for all constants.
+          # Most of rack's constants are not used at runtime, this
+          # lists the ones most commonly needed.
+          Rack::Multipart
+          Rack::Multipart::Parser
+          Rack::Multipart::Generator
+          Rack::Multipart::UploadedFile
+          Rack::Mime
+          Rack::Auth::Digest::Params
+
+          # In the development environment, reference all middleware
+          # the unicorn will load by default, unless unicorn is
+          # set to not load middleware by default.
+          if ENV['RACK_ENV'] == 'development' && (!respond_to?(:set) || set[:default_middleware] != false)
+            Rack::ContentLength
+            Rack::CommonLogger
+            Rack::Chunked
+            Rack::Lint
+            Rack::ShowExceptions
+            Rack::TempfileReaper
+          end
+
+          # If using the mail library, eagerly autoload all constants.
+          # This costs about 9MB of memory, but the mail gem changes
+          # their autoloaded constants on a regular basis, so it's
+          # better to be safe than sorry.
+          if defined?(Mail)
+            Mail.eager_autoload!
+          end
+
+          # Strip path prefixes from the reloader.  This is only
+          # really need in development mode for code reloading to work.
+          pwd = Dir.pwd
+          Unreloader.strip_path_prefix(pwd) if defined?(Unreloader)
+
+          # Drop privileges.  This must be done after chrooting as
+          # chrooting requires root privileges.
+          worker.user(Unicorn.user_name, Unicorn.group_name, pwd)
+        end
 
         if Unicorn.pledge
           # Pledge after dropping privileges, because dropping

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unicorn-lockdown
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-29 00:00:00.000000000 Z
+date: 2019-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pledge
@@ -78,6 +78,6 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Helper library for running Unicorn with chroot/privdrop/fork+exec/pledge
+summary: Helper library for running Unicorn with (chroot|unveil)/privdrop/fork+exec/pledge
   on OpenBSD
 test_files: []