cap2 0.0.1 → 0.1.0

data/README.md

@@ -1,7 +1,7 @@
 Cap2
 ====
 
-Cap2 is a Ruby library for managing the POSIX 1003.1e capabilities available in Linux kernels. These capabilities are a partitioning of the all powerful root privilege into a set of distinct privileges. See capabilites(7) for more information.
+Cap2 is a Ruby library for managing the POSIX 1003.1e capabilities available in Linux kernels. These capabilities are a partitioning of the all powerful root privilege into a set of distinct privileges. See capabilities(7) for more information.
 
 Installation
 ------------
@@ -32,57 +32,127 @@ $ sudo make install
 $ gem install cap2
 ```
 
-Querying Capabilities
----------------------
+Usage
+-----
 
-### Processes
+Cap2 provides methods for querying and modifying capabilities for both processes and files.
 
-Suppose a process with pid 1000 exists with the following capabilities:
+Process capabilities are accessed via a `Cap2::Process` object (returned from `Cap2.process`) and file capabilities via a `Cap2::File` object (returned from `Cap2.file`):
 
 ```
-Permitted   - CAP_CHOWN, CAP_LEASE
-Effective   - CAP_CHOWN
-Inheritable - CAP_LEASE
+Cap2.process              # Returns a Cap2::Process for the current process
+Cap2.process(1000)        # Returns a Cap2::Process for the process with pid 1000
+Cap2.file('/sbin/init')   # Returns a Cap2::File for the /sbin/init file
 ```
 
-Then:
+Capabilities are referenced using lower cased symbols, and without the CAP_ prefix (e.g. `:kill` represents CAP_KILL).
+
+### Querying Capabilities
+
+There are three methods - `permitted?`, `effective?` and `inheritable?` - defined on both `Cap2::Process` and `Cap2::File` for querying capabilities. Each take a capability symbol and return true / false if the capability is in / not in the relevant set:
 
 ```
-process = Cap2.process(1000)  # => #<Cap2::Process>
+# the init daemon - all caps permitted & effective but not inheritable
+init = Cap2.process(1)      # => #<Cap2::Process @pid=1>
+
+init.permitted?(:kill)      # => true
+init.permitted?(:chown)     # => true
+
+init.effective?(:fowner)    # => true
+
+init.inheritable?(:kill)    # => false
+init.inheritable?(:fowner)  # => false
+
+# assume /bin/ping is using file capabilities to enable CAP_NET_RAW on exec
+ping = Cap2.file('/bin/ping')   # => #<Cap2::File @filename="/bin/ping">
+
+ping.permitted?(:net_raw)       # => true
+ping.permitted?(:mknod)         # => false
+
+ping.effective?(:net_raw)       # => true
+
+ping.inheritable?(:net_raw)     # => false
+```
+
+### Modifying Capabilities
+
+Cap2 provides different levels of control over process and file capabilities.
+
+#### Files
+
+To modify the permitted capabilities of a file (i.e. the capabilities which will be permitted in any process that exec's the file), use `Cap2::File#permit` and `Cap2::File#unpermit`:
+
+```
+Cap2.process.effective?(:setfcap)   # => true - needed to set file capabilities
+
+file = Cap2.file('/tmp/file')       # => #<Cap2::File @filename="/tmp/file">
 
-process.permitted?(:chown)    # => true
-process.permitted?(:lease)    # => true
-process.permitted?(:fowner)   # => false
+file.permitted?(:mknod)             # => false
 
-process.effective?(:chown)    # => true
-process.effective?(:lease)    # => false
+file.permit(:mknod)                 # => true
+file.permitted?(:mknod)             # => true
 
-process.inheritable?(:chown)  # => false
-process.inheritable?(:lease)  # => true
+file.unpermit(:mknod)               # => true
+file.permitted?(:mknod)             # => false
 ```
 
-### Files
+To modify the effective capabilities of a file (i.e. the capabilities which will be enabled in any process that exec's the file), use `Cap2::File#enable_on_exec` and `Cap2::File#disable_on_exec`:
 
-Suppose the file "/tmp/cap_test" exists with the following capabilities:
+```
+Cap2.process.effective?(:setfcap)   # => true - needed to set file capabilities
+
+file = Cap2.file('/tmp/file')       # => #<Cap2::File @filename="/tmp/file">
+
+file.effective?(:net_raw)           # => false
 
+file.enable_on_exec(:net_raw)       # => true
+file.effective?(:net_raw)           # => true
+
+file.disable_on_exec(:net_raw)      # => true
+file.effective?(:net_raw)           # => false
 ```
-Permitted   - CAP_CHOWN, CAP_LEASE
-Effective   - CAP_CHOWN
-Inheritable - CAP_LEASE
+
+To modify the inheritable capabilities of a file (i.e. the capabilities which will be ANDed with the inheritable set of any process that exec's the file to determine which capabilities are in the permitted set of the process), use `Cap2::File#allow_inherit` and `Cap2::File#disallow_inherit`:
+
 ```
+Cap2.process.effective?(:setfcap)   # => true - needed to set file capabilities
+
+file = Cap2.file('/tmp/file')       # => #<Cap2::File @filename="/tmp/file">
 
-Then:
+file.inheritable?(:fowner)          # => false
 
+file.allow_inherit(:fowner)         # => true
+file.inheritable?(:fowner)          # => true
+
+file.disallow_inherit(:fowner)      # => true
+file.inheritable?(:fowner)          # => false
 ```
-file = Cap2.file('/tmp/cap_test')  # => #<Cap2::File>
 
-file.permitted?(:chown)            # => true
-file.permitted?(:lease)            # => true
-file.permitted?(:fowner)           # => false
+#### Processes
+
+Cap2 can be used to enable / disable capabilities of the current Ruby process.
 
-file.effective?(:chown)            # => true
-file.effective?(:lease)            # => false
+Suppose the ruby binary file permits :kill, but does not enable it on exec:
 
-file.inheritable?(:chown)          # => false
-file.inheritable?(:lease)          # => true
 ```
+ruby = Cap2.file('/usr/bin/ruby')   # => #<Cap2::File @filename="/usr/bin/ruby">
+ruby.permitted?(:kill)              # => true
+ruby.effective?(:kill)              # => false
+```
+
+and we want to kill a process running as root with pid 1000:
+
+```
+Cap2.process.effective?(:kill)  # => false
+Process.kill("TERM", 1000)      # => Errno::EPERM: Operation not permitted
+
+Cap2.process.enable(:kill)      # => true
+Cap2.process.effective?(:kill)  # => true
+Process.kill("TERM", 1000)      # => 1
+```
+
+Notes
+-----
+
+* Cap2 cannot be used to modify capabilities of other processes. If you are curious as to why, see the Notes section of [cap_set_proc(3)](http://linux.die.net/man/3/cap_set_proc) for an explanation.
+* File capabilities are not supported for shell scripts due to security implications, similar to the reasons setuid is disabled, [see here](http://unix.stackexchange.com/questions/364/allow-setuid-on-shell-scripts#answer-2910) for more information.

data/Rakefile

@@ -9,3 +9,10 @@ desc 'Run all specs in the spec directory'
 RSpec::Core::RakeTask.new(:spec => [:clobber, :compile]) do |t|
   t.pattern = FileList['spec/**/*_spec.rb']
 end
+
+require 'rdoc/task'
+
+RDoc::Task.new do |rd|
+  rd.title = 'Cap2'
+  rd.rdoc_files.include("lib/**/*.rb", "ext/**/*.c")
+end

data/ext/cap2/cap2.c

@@ -1,149 +1,417 @@
 #include <ruby.h>
 #include <errno.h>
+#include <unistd.h>
 #include <sys/capability.h>
 
-static VALUE cap2_has_cap(cap_t cap_d, cap_flag_t set, cap_value_t cap) {
+/*
+ * Converts a Ruby symbol into cap_flag_t set, defined in <sys/capability.h>
+ *
+ * Raises an ArgumentError if set is not a valid capability set
+ */
+cap_flag_t cap2_sym_to_set(VALUE set) {
+  char *set_s;
+
+  Check_Type(set, T_SYMBOL);
+
+  set = rb_sym_to_s(set);
+
+  set_s = StringValueCStr(set);
+
+       if(strcmp(set_s, "permitted")   == 0) return CAP_PERMITTED;
+  else if(strcmp(set_s, "effective")   == 0) return CAP_EFFECTIVE;
+  else if(strcmp(set_s, "inheritable") == 0) return CAP_INHERITABLE;
+  else rb_raise(rb_eArgError, "unknown set %s", set_s);
+}
+
+/*
+ * Converts a Ruby symbol into cap_value_t capability value, defined
+ * in <linux/capability.h>
+ *
+ * Raises an ArgumentError if cap is not a valid capability value.
+ */
+cap_value_t cap2_sym_to_cap(VALUE cap) {
+  char *cap_s;
+
+  Check_Type(cap, T_SYMBOL);
+
+  cap = rb_sym_to_s(cap);
+
+  cap_s = StringValueCStr(cap);
+
+       if(strcmp(cap_s, "chown")            == 0) return CAP_CHOWN;
+  else if(strcmp(cap_s, "dac_override")     == 0) return CAP_DAC_OVERRIDE;
+  else if(strcmp(cap_s, "dac_read_search")  == 0) return CAP_DAC_READ_SEARCH;
+  else if(strcmp(cap_s, "fowner")           == 0) return CAP_FOWNER;
+  else if(strcmp(cap_s, "fsetid")           == 0) return CAP_FSETID;
+  else if(strcmp(cap_s, "kill")             == 0) return CAP_KILL;
+  else if(strcmp(cap_s, "setgid")           == 0) return CAP_SETGID;
+  else if(strcmp(cap_s, "setuid")           == 0) return CAP_SETUID;
+  else if(strcmp(cap_s, "setpcap")          == 0) return CAP_SETPCAP;
+  else if(strcmp(cap_s, "linux_immutable")  == 0) return CAP_LINUX_IMMUTABLE;
+  else if(strcmp(cap_s, "net_bind_service") == 0) return CAP_NET_BIND_SERVICE;
+  else if(strcmp(cap_s, "net_broadcast")    == 0) return CAP_NET_BROADCAST;
+  else if(strcmp(cap_s, "net_admin")        == 0) return CAP_NET_ADMIN;
+  else if(strcmp(cap_s, "net_raw")          == 0) return CAP_NET_RAW;
+  else if(strcmp(cap_s, "ipc_lock")         == 0) return CAP_IPC_LOCK;
+  else if(strcmp(cap_s, "ipc_owner")        == 0) return CAP_IPC_OWNER;
+  else if(strcmp(cap_s, "sys_module")       == 0) return CAP_SYS_MODULE;
+  else if(strcmp(cap_s, "sys_rawio")        == 0) return CAP_SYS_RAWIO;
+  else if(strcmp(cap_s, "sys_chroot")       == 0) return CAP_SYS_CHROOT;
+  else if(strcmp(cap_s, "sys_ptrace")       == 0) return CAP_SYS_PTRACE;
+  else if(strcmp(cap_s, "sys_pacct")        == 0) return CAP_SYS_PACCT;
+  else if(strcmp(cap_s, "sys_admin")        == 0) return CAP_SYS_ADMIN;
+  else if(strcmp(cap_s, "sys_boot")         == 0) return CAP_SYS_BOOT;
+  else if(strcmp(cap_s, "sys_nice")         == 0) return CAP_SYS_NICE;
+  else if(strcmp(cap_s, "sys_resource")     == 0) return CAP_SYS_RESOURCE;
+  else if(strcmp(cap_s, "sys_time")         == 0) return CAP_SYS_TIME;
+  else if(strcmp(cap_s, "sys_tty_config")   == 0) return CAP_SYS_TTY_CONFIG;
+  else if(strcmp(cap_s, "mknod")            == 0) return CAP_MKNOD;
+  else if(strcmp(cap_s, "lease")            == 0) return CAP_LEASE;
+  else if(strcmp(cap_s, "audit_write")      == 0) return CAP_AUDIT_WRITE;
+  else if(strcmp(cap_s, "audit_control")    == 0) return CAP_AUDIT_CONTROL;
+  else if(strcmp(cap_s, "setfcap")          == 0) return CAP_SETFCAP;
+  else if(strcmp(cap_s, "mac_override")     == 0) return CAP_MAC_OVERRIDE;
+  else if(strcmp(cap_s, "mac_admin")        == 0) return CAP_MAC_ADMIN;
+  else if(strcmp(cap_s, "syslog")           == 0) return CAP_SYSLOG;
+  else if(strcmp(cap_s, "wake_alarm")       == 0) return CAP_WAKE_ALARM;
+  else rb_raise(rb_eArgError, "unknown capability %s", cap_s);
+}
+
+/*
+ * Returns a boolean representing whether cap_d has the given capability enabled
+ * in the given set
+ */
+VALUE cap2_has_cap(cap_t cap_d, VALUE set_sym, VALUE cap_sym) {
+  cap_flag_t set;
+  cap_value_t cap;
   cap_flag_value_t flag_value = CAP_CLEAR;
 
+  set = cap2_sym_to_set(set_sym);
+  cap = cap2_sym_to_cap(cap_sym);
+
   cap_get_flag(cap_d, cap, set, &flag_value);
 
   return flag_value == CAP_SET ? Qtrue : Qfalse;
 }
 
-static VALUE cap2_pid_has_cap(VALUE self, VALUE pid, VALUE set, VALUE cap) {
+/*
+ * Convert @pid stored in the given Process object to an int and return it.
+ */
+static int cap2_process_pid(VALUE process) {
+  VALUE pid;
+
+  pid = rb_iv_get(process, "@pid");
+
+  return FIX2INT(pid);
+}
+
+/*
+ * Return a cap_t struct containing the capabilities of the given Process object.
+ */
+static cap_t cap2_process_caps(VALUE process) {
   cap_t cap_d;
-  VALUE result;
+  int pid;
 
-  int p = FIX2INT(pid);
+  pid = cap2_process_pid(process);
 
-  cap_d = cap_get_pid(p);
+  cap_d = cap_get_pid(pid);
 
   if (cap_d == NULL) {
     rb_raise(
       rb_eRuntimeError,
       "Failed to get capabilities for proccess %d: (%s)\n",
-      p, strerror(errno)
+      pid, strerror(errno)
     );
   }
 
-  set = FIX2INT(set);
-  cap = FIX2INT(cap);
+  return cap_d;
+}
+
+/*
+ * Enable/disable the given capability in the given set for the given Process
+ * object.
+ */
+static VALUE cap2_process_set_cap(VALUE process, cap_flag_t set, VALUE cap_sym, cap_flag_value_t set_or_clear) {
+  cap_t cap_d;
+  int pid;
+  cap_value_t caps[1];
+
+  pid = cap2_process_pid(process);
+
+  if((pid_t) pid != getpid())
+    rb_raise(
+      rb_eRuntimeError,
+      "Cannot set capabilities for other processes"
+    );
+
+  caps[0] = cap2_sym_to_cap(cap_sym);
+
+  cap_d = cap_get_pid(pid);
+
+  cap_set_flag(cap_d, set, 1, caps, set_or_clear);
+
+  if(cap_set_proc(cap_d) == -1) {
+    rb_raise(
+      rb_eRuntimeError,
+      "Failed to set capabilities for process %d: (%s)\n",
+      pid, strerror(errno)
+    );
+  } else {
+    return Qtrue;
+  }
+}
+
+/*
+ * call-seq:
+ *  has?(set, capability) -> true or false
+ *
+ * Return whether the process has the given capability enabled in the given set.
+ *
+ *   Cap2.process(1).has?(:permitted, :kill)    #=> true
+ *   Cap2.process(1000).has?(:permitted, :kill) #=> false
+ */
+VALUE cap2_process_has_cap(VALUE self, VALUE set_sym, VALUE cap_sym) {
+  cap_t cap_d;
+  VALUE result;
+
+  cap_d = cap2_process_caps(self);
 
-  result = cap2_has_cap(
-    cap_d,
-    (cap_flag_t) set,
-    (cap_value_t) cap
-  );
+  result = cap2_has_cap(cap_d, set_sym, cap_sym);
 
   cap_free(cap_d);
 
   return result;
 }
 
-static VALUE cap2_file_has_cap(VALUE self, VALUE filename, VALUE set, VALUE cap) {
+/*
+ * call-seq:
+ *  enable(capability) -> true or false
+ *
+ * Enable the given capability for this process.
+ *
+ * Raises a RuntimeError if the process's pid is not the same as the current
+ * pid (you cannot enable capabilities for other processes, that's their job).
+ *
+ *   process = Cap2.process              #=> <Cap2::Process>
+ *   process.permitted?(:kill)           #=> true
+ *   process.effective?(:kill)           #=> false
+ *   process.enable(:kill)               #=> true
+ *   process.effective?(:kill)           #=> true
+ */
+VALUE cap2_process_enable(VALUE self, VALUE cap_sym) {
+  return cap2_process_set_cap(self, CAP_EFFECTIVE, cap_sym, CAP_SET);
+}
+
+/*
+ * call-seq:
+ *  disable(capability) -> true or false
+ *
+ * Disable the given capability for this process.
+ *
+ *   process = Cap2.process              #=> <Cap2::Process>
+ *   process.permitted?(:kill)           #=> true
+ *   process.effective?(:kill)           #=> true
+ *   process.disable(:kill)              #=> true
+ *   process.effective?(:kill)           #=> false
+ */
+VALUE cap2_process_disable(VALUE self, VALUE cap_sym) {
+  return cap2_process_set_cap(self, CAP_EFFECTIVE, cap_sym, CAP_CLEAR);
+}
+
+/*
+ * Convert @filename stored in the given File object to a char* and return it.
+ */
+static char *cap2_file_filename(VALUE file) {
+  VALUE filename;
+
+  filename = rb_iv_get(file, "@filename");
+
+  return StringValueCStr(filename);
+}
+
+/*
+ * Return a cap_t struct containing the capabilities of the given File object.
+ */
+static cap_t cap2_file_caps(VALUE file) {
   cap_t cap_d;
-  VALUE result;
+  char *filename;
 
-  char *f = StringValueCStr(filename);
+  filename = cap2_file_filename(file);
 
-  cap_d = cap_get_file(f);
+  cap_d = cap_get_file(filename);
 
   if (cap_d == NULL && errno != ENODATA) {
     rb_raise(
       rb_eRuntimeError,
       "Failed to get capabilities for file %s: (%s)\n",
-      f, strerror(errno)
+      filename, strerror(errno)
+    );
+  }
+
+  return cap_d;
+}
+
+/*
+ * Enable/disable the given capability in the given set for the given File
+ * object.
+ */
+static VALUE cap2_file_set_cap(VALUE file, cap_flag_t set, VALUE cap_sym, cap_flag_value_t set_or_clear) {
+  cap_t cap_d;
+  char *filename;
+  cap_value_t caps[1];
+
+  filename = cap2_file_filename(file);
+
+  caps[0] = cap2_sym_to_cap(cap_sym);
+
+  cap_d = cap_get_file(filename);
+
+  if(cap_d == NULL)
+    cap_d = cap_init();
+
+  cap_set_flag(cap_d, set, 1, caps, set_or_clear);
+
+  if(cap_set_file(filename, cap_d) == -1) {
+    rb_raise(
+      rb_eRuntimeError,
+      "Failed to set capabilities for file %s: (%s)\n",
+      filename, strerror(errno)
     );
+  } else {
+    return Qtrue;
   }
+}
 
-  set = FIX2INT(set);
-  cap = FIX2INT(cap);
+/*
+ * call-seq:
+ *  has?(set, capability) -> true or false
+ *
+ * Return whether the file has the given capability enabled in the given set.
+ *
+ *   Cap2.file('/bin/ping').has?(:permitted, :net_raw)    #=> true
+ *   Cap2.file('/tmp/ping').has?(:permitted, :net_raw)    #=> false
+ */
+VALUE cap2_file_has_cap(VALUE self, VALUE set_sym, VALUE cap_sym) {
+  cap_t cap_d;
+  VALUE result;
+
+  cap_d = cap2_file_caps(self);
 
-  result = cap2_has_cap(
-    cap_d,
-    (cap_flag_t) set,
-    (cap_value_t) cap
-  );
+  result = cap2_has_cap(cap_d, set_sym, cap_sym);
 
   cap_free(cap_d);
 
   return result;
 }
 
-#define SetsHashSet(key,val) \
-  rb_hash_aset(sets_hash, rb_str_new2(key), INT2FIX(val))
+/*
+ * call-seq:
+ *  permit(capability) -> true or false
+ *
+ * Permit processes executing this file to enable the given capability.
+ *
+ *   file = Cap2.file('/tmp/killer')    #=> <Cap2::File>
+ *   file.permitted?(:kill)             #=> false
+ *   file.permit(:kill)                 #=> true
+ *   file.permitted?(:kill)             #=> true
+ */
+VALUE cap2_file_permit(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_PERMITTED, cap_sym, CAP_SET);
+}
 
-#define CapsHashSet(key,val) \
-  rb_hash_aset(caps_hash, rb_str_new2(key), INT2FIX(val))
+/*
+ * call-seq:
+ *  unpermit(capability) -> true or false
+ *
+ * Dont permit processes executing ths file to enable the given capability.
+ *
+ *   file = Cap2.file('/tmp/foo')      #=> <Cap2::File>
+ *   file.permit(:kill)                #=> true
+ *   file.permitted?(:kill)            #=> true
+ *   file.unpermit(:kill)              #=> true
+ *   file.permitted?(:kill)            #=> false
+ */
+VALUE cap2_file_unpermit(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_PERMITTED, cap_sym, CAP_CLEAR);
+}
 
+/*
+ * call-seq:
+ *  allow_inherit(capability) -> true or false
+ *
+ * Allow processes executing this file to inherit the given capability.
+ *
+ *   file = Cap2.file('/tmp/foo')      #=> <Cap2::File>
+ *   file.inheritable?(:kill)          #=> false
+ *   file.allow_inherit(:kill)         #=> true
+ *   file.inheritable?(:kill)          #=> true
+ */
+VALUE cap2_file_allow_inherit(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_INHERITABLE, cap_sym, CAP_SET);
+}
+
+/*
+ * call-seq:
+ *  disallow_inherit(capability) -> true or false
+ *
+ * Dont allow processes executing this file to inherit the given capability.
+ *
+ *   file = Cap2.file('/tmp/foo')      #=> <Cap2::File>
+ *   file.inheritable?(:kill)          #=> true
+ *   file.allow_inherit(:kill)         #=> true
+ *   file.inheritable?(:kill)          #=> false
+ */
+VALUE cap2_file_disallow_inherit(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_INHERITABLE, cap_sym, CAP_CLEAR);
+}
+
+/*
+ * call-seq:
+ *  set_effective(capability) -> true or false
+ *
+ * Enable the given capability when a proces executes this file.
+ *
+ *   file = Cap2.file('/tmp/foo')      #=> <Cap2::File>
+ *   file.effective?(:kill)            #=> false
+ *   file.set_effective(:kill)         #=> true
+ *   file.effective?(:kill)            #=> true
+ */
+VALUE cap2_file_set_effective(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_EFFECTIVE, cap_sym, CAP_SET);
+}
+
+/*
+ * call-seq:
+ *  disable_on_exec(capability) -> true or false
+ *
+ * Dont enable the given capability when a process executes this file.
+ *
+ *   file = Cap2.file('/tmp/foo')      #=> <Cap2::File>
+ *   file.effective?(:kill)            #=> true
+ *   file.disable_on_exec(:kill)       #=> true
+ *   file.effective?(:kill)            #=> false
+ */
+VALUE cap2_file_clear_effective(VALUE self, VALUE cap_sym) {
+  return cap2_file_set_cap(self, CAP_EFFECTIVE, cap_sym, CAP_CLEAR);
+}
 void Init_cap2(void) {
   VALUE rb_mCap2;
-
-  // sets_hash and caps_hash act as maps between lower cased
-  // names of capabilities (e.g. 'dac_override') and the CAP_
-  // constants defined in linux/capability.h and
-  // sys/capability.h (e.g. CAP_DAC_OVERRIDE). They are
-  // assigned to Cap2::SETS and Cap2::CAPS respectively.
-  VALUE sets_hash, caps_hash;
+  VALUE rb_cCap2File;
+  VALUE rb_cCap2Process;
 
   rb_mCap2 = rb_define_module("Cap2");
 
-  sets_hash = rb_hash_new();
-  SetsHashSet("permitted",    CAP_PERMITTED);
-  SetsHashSet("effective",    CAP_EFFECTIVE);
-  SetsHashSet("inheritable",  CAP_INHERITABLE);
-  rb_define_const(rb_mCap2, "SETS", sets_hash);
-
-  caps_hash = rb_hash_new();
-  CapsHashSet("chown",            CAP_CHOWN);
-  CapsHashSet("dac_override",     CAP_DAC_OVERRIDE);
-  CapsHashSet("dac_read_search",  CAP_DAC_READ_SEARCH);
-  CapsHashSet("fowner",           CAP_FOWNER);
-  CapsHashSet("fsetid",           CAP_FSETID);
-  CapsHashSet("kill",             CAP_KILL);
-  CapsHashSet("setgid",           CAP_SETGID);
-  CapsHashSet("setuid",           CAP_SETUID);
-  CapsHashSet("setpcap",          CAP_SETPCAP);
-  CapsHashSet("linux_immutable",  CAP_LINUX_IMMUTABLE);
-  CapsHashSet("net_bind_service", CAP_NET_BIND_SERVICE);
-  CapsHashSet("net_broadcast",    CAP_NET_BROADCAST);
-  CapsHashSet("net_admin",        CAP_NET_ADMIN);
-  CapsHashSet("net_raw",          CAP_NET_RAW);
-  CapsHashSet("ipc_lock",         CAP_IPC_LOCK);
-  CapsHashSet("ipc_owner",        CAP_IPC_OWNER);
-  CapsHashSet("sys_module",       CAP_SYS_MODULE);
-  CapsHashSet("sys_rawio",        CAP_SYS_RAWIO);
-  CapsHashSet("sys_chroot",       CAP_SYS_CHROOT);
-  CapsHashSet("sys_ptrace",       CAP_SYS_PTRACE);
-  CapsHashSet("sys_pacct",        CAP_SYS_PACCT);
-  CapsHashSet("sys_admin",        CAP_SYS_ADMIN);
-  CapsHashSet("sys_boot",         CAP_SYS_BOOT);
-  CapsHashSet("sys_nice",         CAP_SYS_NICE);
-  CapsHashSet("sys_resource",     CAP_SYS_RESOURCE);
-  CapsHashSet("sys_time",         CAP_SYS_TIME);
-  CapsHashSet("sys_tty_config",   CAP_SYS_TTY_CONFIG);
-  CapsHashSet("mknod",            CAP_MKNOD);
-  CapsHashSet("lease",            CAP_LEASE);
-  CapsHashSet("audit_write",      CAP_AUDIT_WRITE);
-  CapsHashSet("audit_control",    CAP_AUDIT_CONTROL);
-  CapsHashSet("setfcap",          CAP_SETFCAP);
-  CapsHashSet("mac_override",     CAP_MAC_OVERRIDE);
-  CapsHashSet("mac_admin",        CAP_MAC_ADMIN);
-  CapsHashSet("syslog",           CAP_SYSLOG);
-  CapsHashSet("wake_alarm",       CAP_WAKE_ALARM);
-  rb_define_const(rb_mCap2, "CAPS", caps_hash);
-
-  rb_define_module_function(
-    rb_mCap2,
-    "pid_has_cap?",
-    cap2_pid_has_cap,
-    3
-  );
-
-  rb_define_module_function(
-    rb_mCap2,
-    "file_has_cap?",
-    cap2_file_has_cap,
-    3
-  );
+  rb_cCap2Process = rb_define_class_under(rb_mCap2, "Process", rb_cObject);
+  rb_define_method(rb_cCap2Process, "has?", cap2_process_has_cap, 2);
+  rb_define_method(rb_cCap2Process, "enable", cap2_process_enable, 1);
+  rb_define_method(rb_cCap2Process, "disable", cap2_process_disable, 1);
+
+  rb_cCap2File = rb_define_class_under(rb_mCap2, "File", rb_cObject);
+  rb_define_method(rb_cCap2File, "has?", cap2_file_has_cap, 2);
+  rb_define_method(rb_cCap2File, "permit", cap2_file_permit, 1);
+  rb_define_method(rb_cCap2File, "unpermit", cap2_file_unpermit, 1);
+  rb_define_method(rb_cCap2File, "allow_inherit", cap2_file_allow_inherit, 1);
+  rb_define_method(rb_cCap2File, "disallow_inherit", cap2_file_disallow_inherit, 1);
+  rb_define_method(rb_cCap2File, "set_effective", cap2_file_set_effective, 1);
+  rb_define_method(rb_cCap2File, "disable_on_exec", cap2_file_clear_effective, 1);
 }

data/lib/cap2.rb

@@ -1,48 +1,15 @@
 require 'cap2.so'
-require 'cap2/entity'
 require 'cap2/process'
 require 'cap2/file'
 
+# Cap2 is a module for querying the POSIX 1003.1e capabilities
+# available in Linux kernels. These capabilities are a
+# partitioning of the all powerful root privilege into a set
+# of distinct privileges.
+#
+# For more information see capabilities(7).
 module Cap2
-  # = Cap2
-  #
-  # Cap2 is a module for querying the POSIX 1003.1e capabilities
-  # available in Linux kernels. These capabilities are a
-  # partitioning of the all powerful root privilege into a set
-  # of distinct privileges.
   class << self
-    # A wrapper function around the native Cap2.pid_has_cap?
-    # and Cap2.file_has_cap?. Returns true if the given
-    # capability is enabled in the given set for the given pid /
-    # filename.
-    #
-    # @param [String, Fixnum] pid_or_filename
-    #   When a Fixnum, query the capabilities for the process
-    #   with this value. When a String, query for the file
-    #   with a filename of this value.
-    #
-    # @param [Symbol] set
-    #   One of :permitted, :effective or :inheritable.
-    #
-    # @param [Symbol] cap
-    #   A lower cased name of a capability, without the 'CAP_'
-    #   prefix. For example, :chown would query the CAP_CHOWN
-    #   capability
-    def has_capability?(pid_or_filename, set, cap)
-      # See ext/cap2/cap2.c for the definition of SETS and CAPS
-      set = SETS[set.to_s]
-      cap = CAPS[cap.to_s]
-
-      case pid_or_filename
-      when Fixnum
-        pid_has_cap?(pid_or_filename, set, cap)
-      when String
-        file_has_cap?(pid_or_filename, set, cap)
-      else
-        raise ArgumentError, "wrong argument type, expected Fixnum or String, got #{pid_or_filename.class}"
-      end
-    end
-
     # Returns a Cap2::Process initialized with the given pid,
     # defaulting to the current pid.
     def process(pid = ::Process.pid)
@@ -77,6 +44,12 @@ module Cap2
     end
   end
 
+  # Raised when trying to initialise a Process object for a non-existent pid.
   class ProcessNotFound < StandardError; end
+
+  # Raised when trying to initialise a File object for a non-existent file.
   class FileNotFound < StandardError; end
+
+  # Raised when trying to enable unpermitted / uninheritable file capabilities.
+  class IncompatibleCapabilities < StandardError; end
 end

data/lib/cap2/file.rb

@@ -1,11 +1,26 @@
+require 'cap2/set_methods'
+
 module Cap2
-  class File < Entity
-    # = Cap2::File
-    #
-    # A class with methods for querying capabilities for the
-    # file with filename provided to the initialize method.
+  # A class with methods for querying capabilities for the
+  # file with filename provided to the initialize method.
+  class File
+    include SetMethods
+
+    # Initialize a new File object for the given filename.
     def initialize(filename)
-      @entity_id = filename
+      @filename = filename
+    end
+
+    # Enable the given capability in the file's effective set.
+    #
+    # The capability must be either permitted or inheritable (or else it cannot
+    # possibly be enabled in the new process).
+    def enable_on_exec(capability)
+      if permitted?(capability) || inheritable?(capability)
+        set_effective(capability)
+      else
+        raise IncompatibleCapabilities, 'cannot enable_on_exec a capability which is neither permitted nor inheritable'
+      end
     end
   end
 end

data/lib/cap2/process.rb

@@ -1,11 +1,14 @@
+require 'cap2/set_methods'
+
 module Cap2
-  class Process < Entity
-    # = Cap2::Process
-    #
-    # A class with methods for querying capabilities for the
-    # process with pid provided to the initialize method.
+  # A class with methods for querying capabilities for the
+  # process with pid provided to the initialize method.
+  class Process
+    include SetMethods
+
+    # Initialize a new Process object for the given pid.
     def initialize(pid)
-      @entity_id = pid
+      @pid = pid
     end
   end
 end

data/lib/cap2/set_methods.rb

@@ -0,0 +1,26 @@
+module Cap2
+  # A mixin for the Cap2::Process and Cap2::File
+  # classes providing convenience methods for querying
+  # permitted, effective and inheritable capabilities.
+  #
+  # Each method takes a capability argument, a lower
+  # cased name of a capability, without the 'CAP_' prefix.
+  # For example, :chown would query the CAP_CHOWN capability.
+  module SetMethods
+    # Returns whether the given capability is permitted
+    def permitted?(capability)
+      has?(:permitted, capability)
+    end
+
+    # Returns whether the given capability is effective
+    def effective?(capability)
+      has?(:effective, capability)
+    end
+
+    # Returns whether the given capability is inheritable
+    def inheritable?(capability)
+      has?(:inheritable, capability)
+    end
+  end
+end
+

data/lib/cap2/version.rb

@@ -1,3 +1,3 @@
 module Cap2
-  Version = '0.0.1'
+  Version = '0.1.0'
 end

data/spec/cap2_spec.rb

@@ -1,38 +1,6 @@
 require 'spec_helper'
 
 describe Cap2 do
-  describe '.has_capability?' do
-    context 'for processes' do
-      context 'when the given process does not have the given capability' do
-        it { should_not have_capability(
-          Process.pid, :permitted, :dac_override) }
-      end
-
-      context 'when the given process does have the given capability' do
-        it { should have_capability(
-          1, :permitted, :dac_override) }
-      end
-    end
-
-    context 'for files' do
-      let(:file) { Tempfile.new('cap-test') }
-
-      context 'when the given file does not have the given capability' do
-        it { should_not have_capability(
-          file.path, :permitted, :dac_override) }
-      end
-
-      context 'when the given file does have the given capability' do
-        before(:each) do
-          system %{sudo setcap "cap_dac_override+p" #{file.path}}
-        end
-
-        it { should have_capability(
-          file.path, :permitted, :dac_override) }
-      end
-    end
-  end
-
   describe '.process' do
     let(:process) { double 'process' }
 

data/spec/file_spec.rb

@@ -1,6 +1,140 @@
 require 'spec_helper'
 
 describe Cap2::File do
-  it_behaves_like 'an entity'
-end
+  let(:file) { Tempfile.new('cap-test') }
+
+  subject { Cap2::File.new(file.path) }
+
+  describe '#permitted?' do
+    context "when the file doesn't have the given capability" do
+      it { should_not be_permitted(:dac_override) }
+    end
+
+    context 'when the process does have the given capability' do
+      before(:each) do
+        system %{sudo setcap "cap_dac_override+p" #{file.path}}
+      end
+
+      it { should be_permitted(:dac_override) }
+    end
+  end
+
+  describe '#effective?' do
+    context "when the file doesn't have the given capability" do
+      it { should_not be_effective(:dac_override) }
+    end
+
+    context 'when the process does have the given capability' do
+      before(:each) do
+        system %{sudo setcap "cap_dac_override+pe" #{file.path}}
+      end
+
+      it { should be_effective(:dac_override) }
+    end
+  end
+
+  describe '#inheritable?' do
+    context "when the file doesn't have the given capability" do
+      it { should_not be_inheritable(:dac_override) }
+    end
+
+    context 'when the process does have the given capability' do
+      before(:each) do
+        system %{sudo setcap "cap_dac_override+i" #{file.path}}
+      end
+
+      it { should be_inheritable(:dac_override) }
+    end
+  end
+
+  describe '#permit' do
+    specify do
+      expect { running_as_root('permit(:fowner)') }.to \
+        change { subject.permitted?(:fowner) }.from(false).to(true)
+    end
+  end
+
+  describe '#unpermit' do
+    before(:each) do
+      run_as_root('permit(:fowner)')
+    end
 
+    specify do
+      expect { running_as_root('unpermit(:fowner)') }.to \
+        change { subject.permitted?(:fowner) }.from(true).to(false)
+    end
+  end
+
+  describe '#allow_inherit' do
+    specify do
+      expect { running_as_root('allow_inherit(:chown)') }.to \
+        change { subject.inheritable?(:chown) }.from(false).to(true)
+    end
+  end
+
+  describe '#disallow_inherit' do
+    before(:each) do
+      run_as_root('allow_inherit(:chown)')
+    end
+
+    specify do
+      expect { running_as_root('disallow_inherit(:chown)') }.to \
+        change { subject.inheritable?(:chown) }.from(true).to(false)
+    end
+  end
+
+  describe '#enable_on_exec' do
+    context 'when the capability is not permitted or inheritable' do
+      specify do
+        expect { subject.enable_on_exec(:lease) }.to \
+          raise_error(
+            Cap2::IncompatibleCapabilities,
+            'cannot enable_on_exec a capability which is neither permitted nor inheritable'
+          )
+      end
+    end
+
+    context 'when the capability is permitted' do
+      before(:each) do
+        run_as_root('permit(:lease)')
+      end
+
+      specify do
+        expect { running_as_root('enable_on_exec(:lease)') }.to \
+          change { subject.effective?(:lease) }.from(false).to(true)
+      end
+    end
+
+    context 'when the capability is inheritable' do
+      before(:each) do
+        run_as_root('allow_inherit(:lease)')
+      end
+
+      specify do
+        expect { running_as_root('enable_on_exec(:lease)') }.to \
+          change { subject.effective?(:lease) }.from(false).to(true)
+      end
+    end
+  end
+
+  describe '#disable_on_exec' do
+    before(:each) do
+      run_as_root('permit(:kill)', 'enable_on_exec(:kill)')
+    end
+
+    specify do
+      expect { running_as_root('disable_on_exec(:kill)') }.to \
+        change { subject.effective?(:kill) }.from(true).to(false)
+    end
+  end
+
+  # FIXME: Would like to call the given code on subject directly (e.g.
+  #        `subject.permit(:fowner)`) but this would require the test
+  #        suite to be run as root?
+  def run_as_root(*codes)
+    codes.each do |code|
+      system %{sudo ruby -Ilib -rcap2 -e 'Cap2.file("#{file.path}").#{code}'}
+    end
+  end
+  alias running_as_root run_as_root
+end

data/spec/process_spec.rb

@@ -1,5 +1,31 @@
 require 'spec_helper'
 
 describe Cap2::Process do
-  it_behaves_like 'an entity'
+  describe '#permitted?' do
+    context "when the process doesn't have the given capability" do
+      subject { Cap2::Process.new(Process.pid) }
+
+      it { should_not be_permitted(:dac_override) }
+    end
+
+    context 'when the process does have the given capability' do
+      subject { Cap2::Process.new(1) }
+
+      it { should be_permitted(:dac_override) }
+    end
+  end
+
+  describe '#effective?' do
+    context "when the process doesn't have the given capability" do
+      subject { Cap2::Process.new(Process.pid) }
+
+      it { should_not be_effective(:dac_override) }
+    end
+
+    context 'when the process does have the given capability' do
+      subject { Cap2::Process.new(1) }
+
+      it { should be_effective(:dac_override) }
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -7,7 +7,6 @@
 
 require 'cap2'
 require 'tempfile'
-require 'support/entity'
 
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cap2
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-18 00:00:00.000000000 Z
+date: 2012-08-30 00:00:00.000000000 Z
 dependencies: []
 description: ! "    Cap2 is a Ruby library for managing the POSIX 1003.1e capabilities\n
-  \   available in Linux kernels.\n    \n    These capabilities are a partitioning
-  of the all powerful root\n    privilege into a set of distinct privileges.\n    \n
-  \   See capabilites(7) for more information.\n"
+  \   available in Linux kernels.\n\n    These capabilities are a partitioning of
+  the all powerful root\n    privilege into a set of distinct privileges.\n\n    See
+  capabilites(7) for more information.\n"
 email:
 - lewismarshall86@gmail.com
 executables: []
@@ -29,10 +29,10 @@ files:
 - ext/cap2/cap2.c
 - lib/cap2.rb
 - lib/cap2/process.rb
-- lib/cap2/entity.rb
 - lib/cap2/version.rb
 - lib/cap2/file.rb
-- spec/support/entity.rb
+- lib/cap2/set_methods.rb
+- lib/cap2.so
 - spec/process_spec.rb
 - spec/cap2_spec.rb
 - spec/spec_helper.rb
@@ -62,3 +62,4 @@ signing_key:
 specification_version: 3
 summary: A Ruby library for managing Linux file and process capabilities
 test_files: []
+has_rdoc: 

data/lib/cap2/entity.rb

@@ -1,31 +0,0 @@
-module Cap2
-  class Entity
-    # = Entity
-    #
-    # A superclass for the Cap2::Process and Cap2::File
-    # classes providing convenience methods for querying
-    # permitted, effective and inheritable capabilities.
-    #
-    # Each method takes a capability argument, a lower
-    # cased name of a capability, without the 'CAP_' prefix.
-    # For example, :chown would query the CAP_CHOWN capability.
-
-    def permitted?(capability)
-      has?(:permitted, capability)
-    end
-
-    def effective?(capability)
-      has?(:effective, capability)
-    end
-
-    def inheritable?(capability)
-      has?(:inheritable, capability)
-    end
-
-    private
-    def has?(set, cap)
-      Cap2.has_capability?(@entity_id, set, cap)
-    end
-  end
-end
-

data/spec/support/entity.rb

@@ -1,38 +0,0 @@
-require 'spec_helper'
-
-shared_examples_for 'an entity' do
-  let(:entity_id) { double 'entity id' }
-  let(:capability) { double 'capability' }
-
-  subject { described_class.new(entity_id) }
-
-  describe '#permitted?' do
-    it 'should call Cap2.has_capability? correctly' do
-      Cap2.
-        should_receive(:has_capability?).
-        with(entity_id, :permitted, capability)
-
-      subject.permitted?(capability)
-    end
-  end
-
-  describe '#effective?' do
-    it 'should call Cap2.has_capability? correctly' do
-      Cap2.
-        should_receive(:has_capability?).
-        with(entity_id, :effective, capability)
-
-      subject.effective?(capability)
-    end
-  end
-
-  describe '#inheritable?' do
-    it 'should call Cap2.has_capability? correctly' do
-      Cap2.
-        should_receive(:has_capability?).
-        with(entity_id, :inheritable, capability)
-
-      subject.inheritable?(capability)
-    end
-  end
-end