pledge

= 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 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 [e-mail]