cap2 0.2.1 → 0.2.2

data/README.md

@@ -32,8 +32,8 @@ $ sudo make install
 $ gem install cap2
 ```
 
-Usage
------
+Process and File Objects
+------------------------
 
 Cap2 provides methods for querying and modifying capabilities for both processes and files.
 
@@ -45,11 +45,18 @@ Cap2.process(1000)        # Returns a Cap2::Process for the process with pid 100
 Cap2.file('/sbin/init')   # Returns a Cap2::File for the /sbin/init file
 ```
 
+Querying Capabilities
+---------------------
+
 Capabilities are referenced using lower cased symbols, and without the CAP_ prefix (e.g. `:kill` represents CAP_KILL).
 
-### Querying Capabilities
+There are three methods defined on both `Cap2::Process` and `Cap2::File` for querying capabilities:
 
-There are three methods - `permitted?`, `enabled?` and `inheritable?` - defined on both `Cap2::Process` and `Cap2::File` for querying capabilities. Each of these methods, Cap2::File#enabled? being the exception, take a list of capability symbols and return true / false if the capabilities are in / not in the relevant set:
+* `permitted?`
+* `enabled?`
+* `inheritable?`
+
+Each of these methods, `Cap2::File#enabled?` being the exception, take a list of capability symbols and return true / false if the capabilities are in / not in the relevant set:
 
 ```
 # the init daemon - all caps permitted & enabled but not inheritable
@@ -63,7 +70,9 @@ init.enabled?(:kill, :chown)      # => true
 
 init.inheritable?(:chown)         # => false
 init.inheritable?(:fowner, :kill) # => 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">
 
@@ -75,15 +84,39 @@ ping.enabled?                   # => true
 ping.inheritable?(:net_raw)     # => false
 ```
 
-#### Why does Cap2::File#enabled? not take an arguement?
+### Why does Cap2::File#enabled? not take an arguement?
 
 Under the hood, the file effective set is just a single bit. When enabled, any process which exec's the file will have the capabilities from it's resulting permitted set also in it's effective set.
 
-### Modifying Capabilities
+Modifying File Capabilities
+---------------------------
+
+The file capability modification methods are:
 
-Cap2 provides different levels of control over process and file capabilities.
+* `permit(capabilities)`
+* `unpermit(capabilities)`
+* `allow_inherit(capabilities)`
+* `disallow_inherit(capabilities)`
+* `enable`
+* `disable`
 
-#### Files
+where `capabilities` can take any of the following forms:
+
+```
+# list of one or more symbols
+(:chown)
+(:mknod, :kill, :mac_admin)
+
+# hash with an :only key
+(:only => :fowner)
+(:only => [:lease, :net_raw])
+
+# hash with an :except key
+(:except => :sys_time)
+(:except => [:syslog, :fsetid])
+```
+
+### Permitting capabilities
 
 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`:
 
@@ -103,6 +136,8 @@ file.unpermit(:chown, :fowner)           # => true
 file.permitted?(:mknod, :chown, :fowner) # => false
 ```
 
+### Enabling capabilities
+
 To modify the effective bit of a file (i.e. whether the resulting permitted capabilities of any process that exec's the file will also be enabled in it's effective set), use `Cap2::File#enable` and `Cap2::File#disable`:
 
 ```
@@ -120,6 +155,8 @@ file.disable                        # => true
 file.enabled?                       # => false
 ```
 
+### Inheriting capabilities
+
 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`:
 
 ```
@@ -136,7 +173,9 @@ file.disallow_inherit(:fowner)      # => true
 file.inheritable?(:fowner)          # => false
 ```
 
-To clear all capabilities for a file, use Cap2::File#clear:
+### Clearing capabilities
+
+To clear all capabilities for a file, use `Cap2::File#clear`:
 
 ```
 Cap2.process.enabled?(:setfcap)     # => true - needed to set file capabilities
@@ -158,7 +197,8 @@ file.inheritable?(:kill, :mknod)    # => false
 file.enabled?                       # => false
 ```
 
-#### Processes
+Modifying Process Capabilities
+------------------------------
 
 Cap2 can be used to enable / disable capabilities of the current Ruby process.
 

data/ext/cap2/cap2.c

@@ -79,6 +79,18 @@ VALUE cap2_caps_to_hash(cap_t cap_d) {
   return caps;
 }
 
+VALUE cap2_allcaps(VALUE self) {
+  int i;
+  VALUE caps;
+
+  caps = rb_ary_new();
+
+  for(i = 0; i < __CAP_COUNT; i++)
+    rb_ary_push(caps, ID2SYM(rb_intern(cap2_caps[i].name)));
+
+  return caps;
+}
+
 /*
  * Convert @pid stored in the given Process object to an int and return it.
  */
@@ -292,6 +304,7 @@ void Init_cap2(void) {
   VALUE rb_cCap2Process;
 
   rb_mCap2 = rb_define_module("Cap2");
+  rb_define_module_function(rb_mCap2, "allcaps", cap2_allcaps, 0);
 
   rb_cCap2Process = rb_define_class_under(rb_mCap2, "Process", rb_cObject);
   rb_define_method(rb_cCap2Process, "getcaps", cap2_process_getcaps, 0);

data/lib/cap2/file.rb

@@ -27,27 +27,27 @@ module Cap2
       !@caps[:effective].empty?
     end
 
-    # Permit processes executing this file to enable the given capability.
+    # Permit processes executing this file to enable the given capabilities.
     def permit(*capabilities)
-      @caps[:permitted].merge(capabilities)
+      @caps[:permitted].merge parse(capabilities)
       save
     end
 
-    # Dont permit processes executing this file to enable the given capability.
+    # Dont permit processes executing this file to enable the given capabilities.
     def unpermit(*capabilities)
-      @caps[:permitted].subtract(capabilities)
+      @caps[:permitted].subtract parse(capabilities)
       save
     end
 
-    # Allow processes executing this file to inherit the given capability.
+    # Allow processes executing this file to inherit the given capabilities.
     def allow_inherit(*capabilities)
-      @caps[:inheritable].merge(capabilities)
+      @caps[:inheritable].merge parse(capabilities)
       save
     end
 
-    # Dont allow processes executing this file to inherit the given capability.
+    # Dont allow processes executing this file to inherit the given capabilities.
     def disallow_inherit(*capabilities)
-      @caps[:inheritable].subtract(capabilities)
+      @caps[:inheritable].subtract parse(capabilities)
       save
     end
 
@@ -73,5 +73,29 @@ module Cap2
     def reload
       @caps = getcaps
     end
+
+    def parse(caps)
+      if (options = caps.first).is_a? Hash
+        if caps.size > 1
+          raise(
+            ArgumentError,
+            'cannot pass both a hash and a list of capabilities'
+          )
+        end
+
+        if options.has_key?(:only) && !options.has_key?(:except)
+          Array(options[:only])
+        elsif options.has_key?(:except) && !options.has_key?(:only)
+          Cap2.allcaps - Array(options[:except])
+        else
+          raise(
+            ArgumentError,
+            "expected exactly one of [:only, :except], got #{options.keys}"
+          )
+        end
+      else
+        caps
+      end
+    end
   end
 end

data/lib/cap2/version.rb

@@ -1,3 +1,3 @@
 module Cap2
-  Version = '0.2.1'
+  Version = '0.2.2'
 end

data/spec/file_spec.rb

@@ -52,14 +52,50 @@ describe Cap2::File do
   end
 
   describe '#permit' do
-    specify do
-      expect { running_as_root('permit(:fowner, :kill)') }.to \
-        change { subject.permitted?(:fowner) }.from(false).to(true)
+    context 'with a list of capability symbols' do
+      specify do
+        expect { running_as_root('permit(:fowner, :kill)') }.to \
+          change { subject.permitted?(:fowner) }.from(false).to(true)
+      end
+
+      specify do
+        expect { running_as_root('permit(:fowner, :kill)') }.to \
+          change { subject.permitted?(:kill) }.from(false).to(true)
+      end
     end
 
-    specify do
-      expect { running_as_root('permit(:fowner, :kill)') }.to \
-        change { subject.permitted?(:kill) }.from(false).to(true)
+    context 'with an :only option' do
+      specify do
+        expect { running_as_root('permit(:only => :fowner)') }.to \
+          change { subject.permitted?(:fowner) }.from(false).to(true)
+      end
+
+      specify do
+        expect { running_as_root('permit(:only => :fowner)') }.to_not \
+          change { subject.permitted?(:kill) }.from(false)
+      end
+
+      specify do
+        expect { running_as_root('permit(:only => [:fowner, :kill])') }.to \
+          change { subject.permitted?(:fowner, :kill) }.from(false).to(true)
+      end
+    end
+
+    context 'with an :except option' do
+      specify do
+        expect { running_as_root('permit(:except => :fowner)') }.to \
+          change { subject.permitted?(:kill) }.from(false).to(true)
+      end
+
+      specify do
+        expect { running_as_root('permit(:except => :fowner)') }.to_not \
+          change { subject.permitted?(:fowner) }.from(false)
+      end
+
+      specify do
+        expect { running_as_root('permit(:except => [:fowner, :kill])') }.to_not \
+          change { subject.permitted?(:fowner, :kill) }.from(false)
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cap2
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors: