Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jeremyevans/ruby-pledge

Ruby Interface to OpenBSD pledge(2) system call
https://github.com/jeremyevans/ruby-pledge

Last synced: about 1 month ago
JSON representation

Ruby Interface to OpenBSD pledge(2) system call

Lists

README 

        
= pledge



pledge exposes OpenBSD's pledge(2) and unveil(2) system

calls to ruby. pledge(2) allows a program to restrict the

types of operations the program can do, and unveil(2)

restricts access to the file system.



Unlike other similar systems, pledge and unveil are

designed for programs that need to use a wide variety of

operations and file access on initialization, but

a fewer number after initialization (when user input will

be accepted).



== pledge



First, you need to require the library



  require 'pledge'



Then you can use +Pledge.pledge+ as the interface to the pledge(2)

system call.  You pass +Pledge.pledge+ a string containing tokens

for the operations you would like to allow (called promises).

For example, if you want to give the process the ability to read

from the file system, but not write to the file system or

allow network access:



  Pledge.pledge("rpath")



To allow read/write filesystem access, but not network access:



  Pledge.pledge("rpath wpath cpath")



To allow inet/unix socket access and DNS queries, but not

filesystem access:



  Pledge.pledge("inet unix dns")



If you want to use pledging in a console application such as

irb or pry, you must include the tty promise:



  Pledge.pledge("tty rpath")



You can pass a second string argument containing tokens for

the operations you would like to allow in spawned processes

(called execpromises).  To allow spawning processes that have

read/write filesystem access only, but not network access:



  Pledge.pledge("proc exec rpath", "stdio rpath wpath cpath")



+Pledge+ is a module that extends itself, you can include it

in other classes:



  Object.send(:include, Pledge)

  pledge("rpath")



See the pledge(2) man page for a description of the allowed

promises in the strings passed to +Pledge.pledge+.



Using an unsupported promise will raise an exception.  The "stdio"

promise is added automatically to the current process's promises,

as ruby does not function without it, but it is not added to

the execpromises (as you can execute non-ruby programs).



== unveil



First, you need to require the library



  require 'unveil'



Then you can use +Pledge.unveil+ as the interface to the unveil(2)

system call.  You pass +Pledge.unveil+ a hash of paths and permissions,

for those paths, and it calls unveil(2) with the path and permissions

for each entry.



The permissions should be a string with the following characters:



r :: Allow read access to existing files and directories

w :: Allow write access to existing files and directories

x :: Allow execute access to programs

c :: Allow create access for new files and directories



You can use the empty string as permissions if you want to allow no access

to the given path, even if you have granted some access to a folder above

the given folder.  You can use a value of +:gem+ to allow read access to

the directory for the gem specified by the key.



+Pledge.unveil+ locks the file system access to the specified paths. If

you want to specify which paths to allow in multiple places in your

program, use +Pledge.unveil_without_lock+ for the initial calls and

+Pledge.unveil+ for the final call.



If +Pledge.unveil+ is called with an empty hash, it adds an unveil of +/+

with no permissions, which denies all access to the file system if

+unveil_without_lock+ was not called previously with paths.



Example:



  Pledge.unveil(

    '/home/foo/bar' => 'r',

    '/home/foo/bar/data' => 'rwc',

    '/bin' => 'x',

    '/home/foo/bar/secret' => '',

    'rack' => :gem

  )



The value of :gem is mostly needed if the gem uses autoload or

other forms of runtime requires.  This allows read access to

all files in the gem's folder, not just the gem's require paths,

so it works correctly for gems that access data (e.g. templates)

outside of the gem's require paths.



If you plan to use pledge and unveil together, you should

unveil before pledging, unless you use the +unveil+

promise when pledging.



=== Issues with unveil and File.realpath



+Pledge.unveil+ does not work with +File.realpath+ on Ruby <2.7.

The Ruby ports officially supported by OpenBSD have had support to

allow them to work together backported, as long as you are running

OpenBSD 6.6+ (or 6.5-current after July 2019).  As +require+ uses

+File.realpath+, this means in most cases where you would want to

use the +:gem+ support, it will not actually work correctly unless

you are using Ruby 2.7+ or an OpenBSD package with the backported

support.



== Reporting issues/bugs



This library uses GitHub Issues for tracking issues/bugs:



  https://github.com/jeremyevans/ruby-pledge/issues



== Contributing



The source code is on GitHub:



  https://github.com/jeremyevans/ruby-pledge



To get a copy:



  git clone git://github.com/jeremyevans/ruby-pledge.git



== Requirements



* OpenBSD 5.9+ (6.4+ for unveil, but 6.6+ recommended)

* ruby 1.8.7+

* rake-compiler (if compiling)



== Compiling



To build the library from a git checkout, use the compile task.



  rake compile



== Running the specs



The rake spec task runs the specs.  This is also the default rake

task.  This will compile the library if not already compiled. 



  rake



== Author



Jeremy Evans