cap2 0.0.1

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) 2012 Lewis Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+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.
+
+Installation
+------------
+
+To install this library, you will need to be running Linux and have the libcap2 library and header files installed.
+
+### Install libcap2
+
+#### Ubuntu
+
+```
+$ sudo apt-get install libcap2 libcap-dev
+```
+
+#### From source
+
+```
+$ curl -O http://ftp.de.debian.org/debian/pool/main/libc/libcap2/libcap2_2.22.orig.tar.gz
+$ tar xzf libcap2_2.22.orig.tar.gz
+$ cd libcap2-2.22
+$ make
+$ sudo make install
+```
+
+### Install the gem
+
+```
+$ gem install cap2
+```
+
+Querying Capabilities
+---------------------
+
+### Processes
+
+Suppose a process with pid 1000 exists with the following capabilities:
+
+```
+Permitted   - CAP_CHOWN, CAP_LEASE
+Effective   - CAP_CHOWN
+Inheritable - CAP_LEASE
+```
+
+Then:
+
+```
+process = Cap2.process(1000)  # => #<Cap2::Process>
+
+process.permitted?(:chown)    # => true
+process.permitted?(:lease)    # => true
+process.permitted?(:fowner)   # => false
+
+process.effective?(:chown)    # => true
+process.effective?(:lease)    # => false
+
+process.inheritable?(:chown)  # => false
+process.inheritable?(:lease)  # => true
+```
+
+### Files
+
+Suppose the file "/tmp/cap_test" exists with the following capabilities:
+
+```
+Permitted   - CAP_CHOWN, CAP_LEASE
+Effective   - CAP_CHOWN
+Inheritable - CAP_LEASE
+```
+
+Then:
+
+```
+file = Cap2.file('/tmp/cap_test')  # => #<Cap2::File>
+
+file.permitted?(:chown)            # => true
+file.permitted?(:lease)            # => true
+file.permitted?(:fowner)           # => false
+
+file.effective?(:chown)            # => true
+file.effective?(:lease)            # => false
+
+file.inheritable?(:chown)          # => false
+file.inheritable?(:lease)          # => true
+```

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rake/extensiontask'
+
+Rake::ExtensionTask.new('cap2')
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc 'Run all specs in the spec directory'
+RSpec::Core::RakeTask.new(:spec => [:clobber, :compile]) do |t|
+  t.pattern = FileList['spec/**/*_spec.rb']
+end

data/ext/cap2/cap2.c

@@ -0,0 +1,149 @@
+#include <ruby.h>
+#include <errno.h>
+#include <sys/capability.h>
+
+static VALUE cap2_has_cap(cap_t cap_d, cap_flag_t set, cap_value_t cap) {
+  cap_flag_value_t flag_value = CAP_CLEAR;
+
+  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) {
+  cap_t cap_d;
+  VALUE result;
+
+  int p = FIX2INT(pid);
+
+  cap_d = cap_get_pid(p);
+
+  if (cap_d == NULL) {
+    rb_raise(
+      rb_eRuntimeError,
+      "Failed to get capabilities for proccess %d: (%s)\n",
+      p, strerror(errno)
+    );
+  }
+
+  set = FIX2INT(set);
+  cap = FIX2INT(cap);
+
+  result = cap2_has_cap(
+    cap_d,
+    (cap_flag_t) set,
+    (cap_value_t) cap
+  );
+
+  cap_free(cap_d);
+
+  return result;
+}
+
+static VALUE cap2_file_has_cap(VALUE self, VALUE filename, VALUE set, VALUE cap) {
+  cap_t cap_d;
+  VALUE result;
+
+  char *f = StringValueCStr(filename);
+
+  cap_d = cap_get_file(f);
+
+  if (cap_d == NULL && errno != ENODATA) {
+    rb_raise(
+      rb_eRuntimeError,
+      "Failed to get capabilities for file %s: (%s)\n",
+      f, strerror(errno)
+    );
+  }
+
+  set = FIX2INT(set);
+  cap = FIX2INT(cap);
+
+  result = cap2_has_cap(
+    cap_d,
+    (cap_flag_t) set,
+    (cap_value_t) cap
+  );
+
+  cap_free(cap_d);
+
+  return result;
+}
+
+#define SetsHashSet(key,val) \
+  rb_hash_aset(sets_hash, rb_str_new2(key), INT2FIX(val))
+
+#define CapsHashSet(key,val) \
+  rb_hash_aset(caps_hash, rb_str_new2(key), INT2FIX(val))
+
+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;
+
+  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
+  );
+}

data/ext/cap2/extconf.rb

@@ -0,0 +1,23 @@
+require 'mkmf'
+
+unless have_header('sys/capability.h')
+  abort <<-EOS
+  -----
+  ERROR
+  -----
+  sys/capability.h is missing. You should install the libcap2 header files
+
+  EOS
+end
+
+unless have_library('cap')
+  abort <<-EOS
+  -----
+  ERROR
+  -----
+  libcap is missing. You should install the libcap2 library
+
+  EOS
+end
+
+create_makefile('cap2')

data/lib/cap2.rb

@@ -0,0 +1,82 @@
+require 'cap2.so'
+require 'cap2/entity'
+require 'cap2/process'
+require 'cap2/file'
+
+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)
+      check_pid! pid
+
+      Process.new(pid)
+    end
+
+    # Returns a Cap2::File initialized with the given filename
+    def file(filename)
+      check_file! filename
+
+      File.new(filename)
+    end
+
+    private
+    # Check that a process with the given pid exists by sending
+    # a 0 signal to the process via Process.kill
+    def check_pid!(pid)
+      ::Process.kill(0, pid)
+    rescue Exception => e
+      if Errno::ESRCH === e
+        raise ProcessNotFound
+      end
+    end
+
+    # Check that a file exists with the given filename
+    def check_file!(filename)
+      unless ::File.exists?(filename)
+        raise FileNotFound
+      end
+    end
+  end
+
+  class ProcessNotFound < StandardError; end
+  class FileNotFound < StandardError; end
+end

data/lib/cap2/entity.rb

@@ -0,0 +1,31 @@
+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/lib/cap2/file.rb

@@ -0,0 +1,11 @@
+module Cap2
+  class File < Entity
+    # = Cap2::File
+    #
+    # A class with methods for querying capabilities for the
+    # file with filename provided to the initialize method.
+    def initialize(filename)
+      @entity_id = filename
+    end
+  end
+end

data/lib/cap2/process.rb

@@ -0,0 +1,11 @@
+module Cap2
+  class Process < Entity
+    # = Cap2::Process
+    #
+    # A class with methods for querying capabilities for the
+    # process with pid provided to the initialize method.
+    def initialize(pid)
+      @entity_id = pid
+    end
+  end
+end

data/lib/cap2/version.rb

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

data/spec/cap2_spec.rb

@@ -0,0 +1,119 @@
+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' }
+
+    before(:each) do
+      Cap2::Process.stub(:new => process)
+    end
+
+    context 'called without a pid' do
+      it 'should initialize a Cap2::Process with the current pid' do
+        Cap2::Process.should_receive(:new).with(Process.pid)
+        Cap2.process
+      end
+
+      it 'should return the new Cap2::Process' do
+        Cap2.process.should == process
+      end
+    end
+
+    context 'called with a pid' do
+      let(:pid) { double 'pid' }
+
+      context "when a process with the given pid doesn't exist" do
+        before(:each) do
+          Process.stub(:kill).with(0, pid).and_raise(Errno::ESRCH)
+        end
+
+        it 'should raise a Cap2::ProcessNotFound' do
+          expect { Cap2.process(pid) }.to \
+            raise_error(Cap2::ProcessNotFound)
+        end
+      end
+
+      context 'when a process with the given pid does exist' do
+        before(:each) do
+          Process.stub(:kill).with(0, pid).and_return(1)
+        end
+
+        it 'should initialize a Cap2::Process with the pid' do
+          Cap2::Process.should_receive(:new).with(pid)
+          Cap2.process(pid)
+        end
+
+        it 'should return the new Cap2::Process' do
+          Cap2.process(pid).should == process
+        end
+      end
+    end
+  end
+
+  describe '.file' do
+    let(:file) { double 'file' }
+    let(:filename) { double 'filename' }
+
+    before(:each) do
+      Cap2::File.stub(:new => file)
+    end
+
+    context "when the file doesn't exist" do
+      before(:each) do
+        File.stub(:exists?).with(filename).and_return(false)
+      end
+
+      it 'should raise a Cap2::FileNotFound error' do
+        expect { Cap2.file(filename) }.to \
+          raise_error(Cap2::FileNotFound)
+      end
+    end
+
+    context 'when the file does exist' do
+      before(:each) do
+        File.stub(:exists?).with(filename).and_return(true)
+      end
+
+      it 'should initialize a Cap2::File with the filename' do
+        Cap2::File.should_receive(:new).with(filename)
+        Cap2.file(filename)
+      end
+
+      it 'should return the new Cap2::File' do
+        Cap2.file(filename).should == file
+      end
+    end
+  end
+end

data/spec/file_spec.rb

@@ -0,0 +1,6 @@
+require 'spec_helper'
+
+describe Cap2::File do
+  it_behaves_like 'an entity'
+end
+

data/spec/process_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe Cap2::Process do
+  it_behaves_like 'an entity'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'cap2'
+require 'tempfile'
+require 'support/entity'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/spec/support/entity.rb

@@ -0,0 +1,38 @@
+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

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: cap2
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Lewis Marshall
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-18 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"
+email:
+- lewismarshall86@gmail.com
+executables: []
+extensions:
+- ext/cap2/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- LICENSE
+- ext/cap2/extconf.rb
+- 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
+- spec/process_spec.rb
+- spec/cap2_spec.rb
+- spec/spec_helper.rb
+- spec/file_spec.rb
+homepage: https://github.com/lmars/cap2
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A Ruby library for managing Linux file and process capabilities
+test_files: []