NAME

Unix::Pledge - restrict system operations

SYNOPSIS

  use Unix::Pledge;

  # ...
  # Program initializtion, open files, drop privileges, fork, etc
  # ...

  # Now that we're initialized, limit our process to reading our .profile
  unveil("$ENV{HOME}/.profile", "r");
  unveil; # To ensure unveil can no longer be called
  pledge("stdio rpath"); # ... which this does also

  # Reading user's .profile works as expected
  open(my $fd, "<", "$ENV{HOME}/.profile");
  while(<$fd>) {
    print $_;
  }

  # Trying to open outside whitelisted path fails with file not found
  open($fd, "<", "/etc/passwd") or warn $!;

  # Trying to write will cause SIGABRT
  open($fd, ">", "$ENV{HOME}/.profile");

  # Abort trap (core dumped)

DESCRIPTION

The current process is forced into a restricted-service operating mode. A few subsets are available, roughly described as computation, memory management, read-write operations on file descriptors, opening of files, networking. In general, these modes were selected by studying the operation of many programs using libc and other such interfaces, and setting promises or paths.

Requires that the kernel supports the pledge(2) and unveil(2) system calls, which as of this writing are only available in OpenBSD.

There are two types of restriction which can be made: Restrict the set of system calls which can be made with "pledge" or the files which can be accessed with "unveil".

pledge

The pledge function takes one or two parameters: promises and optionally execpromises.

Both parameters are space-delimited strings listing modes of operation which represent system calls that a process is asserting are the only calls that it will make from then on. promises lists the modes this process will adhere to while execpromises lists the modes that will be adhered to after calling exec.

To set execpromises only, promises can be passed as undef or the empty string. A detailed description of which calls are restricted by which modes is available in the pledge(2) manpage.

Process violations of the previously "pledged" modes will result in the process being forcibly terminated via SIGABRT, which under normal circumstances will dump perl's core as it quits. In this way pledge serves as a capabilities framework like capsicum, systrace, AppArmor, etc. The difference is that pledge aims to be very easy to use for the typical developer to sandbox their process.

Note that restrictions are one way only: you can only increase the restrictions on your process, not relax them.

Also note that if either list of promises includes error then further attempts to raise privileges will fail silently and illegal system calls will fail rather than abort.

unveil

The unveil function takes two parameters - a directory/file path and access mode - or none. After it has been called with no parameters further calls to unveil will fail.

Each successive call to unveil adds a path which this process is permitted to access. Any attempt to access a file not previously unveiled will fail.

Full details on the difference between naming files and directories, and their access modes are in the unveil(2) manpage.

Note that, on OpenBSD at least, the kernel associates the unveiling with the file itself not the textual path, so unveiled files which are subsequently renamed or removed will be "lost". OpenBSD's manpage recommends only unveiling directories.

ERRORS

Unix::Pledge will croak on any errors.

EXPORT

The "pledge" and "unveil" functions are exported by default.

SEE ALSO

For detailed information on pledge and unveil, their parameters and errors, please see the OpenBSD pledge(2) and unveil(2) man pages.

Github repo

AUTHOR

Richard Farr <richard@nxbit.io>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Richard Farr

This module is licensed under the same terms as Perl itself.

cpanm Unix::Pledge

perl -MCPAN -e shell
install Unix::Pledge