4.4 KiB
About
bsdcapsicum.rb provides Ruby bindings for capsicum(4).
Examples
Capability mode
A process can enter into capability mode by calling BSD::Capsicum.enter!. After entering capability mode, the process has limited abilities. File descriptors acquired before entering into capability mode remain accessible and unrestricted, but their capabilites can be reduced. See the cap_enter(2) manual page for more details:
#!/usr/bin/env ruby
require "bsd/capsicum"
print "In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
print "Enter capability mode: ", BSD::Capsicum.enter! ? "ok" : "error", "\n"
print "In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
begin
File.new(File::NULL)
rescue Errno::ECAPMODE => ex
print "Error: #{ex.message} (#{ex.class})", "\n"
end
##
# In capability mode: no
# Enter capability mode: ok
# In capability mode: yes
# Error: Not permitted in capability mode @ rb_sysopen - /dev/null (Errno::ECAPMODE)
IPC
By spawning a child process and then entering capability mode, restrictions can be limited to a child process (and its child processes, if any). This can be helpful in an architecture where a parent process can spawn one or more child processes to handle certain tasks but with restrictions in place:
#!/usr/bin/env ruby
require "bsd/capsicum"
print "[parent] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
fork do
print "[subprocess] Enter capability mode: ", BSD::Capsicum.enter! ? "ok" : "error", "\n"
print "[subprocess] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
print "[subprocess] Exit", "\n"
exit 42
end
Process.wait
print "[parent] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
##
# [parent] In capability mode: no
# [subprocess] Enter capability mode: ok
# [subprocess] In capability mode: yes
# [subprocess] Exit
# [parent] In capability mode: no
Rights
The BSD::Capsicum.set_rights! method can reduce the capabilities of a file descriptor. The following example obtains a file descriptor in a parent process (with both read and write permissions), then limits the capabilities of the file descriptor in a child process to allow only read operations. See the rights(4) man page for a full list of capabilities:
#!/usr/bin/env ruby
require "bsd/capsicum"
path = File.join(Dir.home, "bsdcapsicum.txt")
file = File.open(path, File::CREAT | File::TRUNC | File::RDWR)
file.sync = true
print "[parent] obtain file descriptor (with read+write permissions)", "\n"
fork do
BSD::Capsicum.set_rights!(file, %i[CAP_READ])
print "[subprocess] reduce rights to read-only", "\n"
file.gets
print "[subprocess] read successful", "\n"
begin
file.write "foo"
rescue Errno::ENOTCAPABLE => ex
print "[subprocess] Error: #{ex.message} (#{ex.class})", "\n"
end
end
Process.wait
file.write "[parent] Hello from #{Process.pid}", "\n"
print "[parent] write successful", "\n"
##
# [parent] obtain file descriptor (with read+write permissions)
# [subprocess] reduce rights to read-only
# [subprocess] read successful
# [subprocess] Error: Capabilities insufficient @ io_write - /home/user/bsdcapsicum.txt (Errno::ENOTCAPABLE)
# [parent] write successful
Documentation
A complete API reference is available at 0x1eef.github.io/x/bsdcapsicum.rb
Install
bsdcapsicum.rb is available via rubygems.org:
gem install bsdcapsicum.rb
Sources
See also
- Freaky/ruby-capsicum
bsdcapsicum.rb is a fork of this project. It was a huge help both in terms of code and documentation.
License
The gem is available as open source under the terms of the MIT License.