Ruby bindings for capsicum(4)
Go to file
2024-07-12 05:24:38 -03:00
bin Add test/readme_test.rb 2024-06-24 23:36:09 -03:00
lib Fix type signature in docs 2024-07-12 05:24:38 -03:00
share/ruby-capsicum/examples Add parenthesis in examples 2024-06-27 05:36:37 -03:00
test Update example 2024-06-27 05:09:13 -03:00
.gitignore Initial commit. 2017-05-24 01:18:05 +01:00
.projectile Add .projectile 2024-06-25 04:38:14 -03:00
.rubocop.yml Update rubocop.yml 2024-07-12 04:29:46 -03:00
.travis.yml Initial commit. 2017-05-24 01:18:05 +01:00
bsdcapsicum.rb.gemspec gemspec: add MIT 2024-06-27 02:11:57 -03:00
Gemfile Initial commit. 2017-05-24 01:18:05 +01:00
LICENSE Add 0BSD license 2024-06-27 02:10:45 -03:00
LICENSE.ruby-capsicum Add 0BSD license 2024-06-27 02:10:45 -03:00
Rakefile Add test/readme_test.rb 2024-06-24 23:36:09 -03:00
README.md Update sources 2024-07-08 14:11:45 -03:00

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 full capabilities), 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 all capabilities)", "\n"
fork do
  BSD::Capsicum.set_rights!(file, %i[CAP_READ])
  print "[subprocess] Reduce capabilities to read", "\n"

  file.gets
  print "[subprocess] Read OK", "\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 OK", "\n"

##
# [parent] Obtain file descriptor (with all capabilities)
# [subprocess] Reduce capabilities to read
# [subprocess] Read OK
# [subprocess] Error: Capabilities insufficient @ io_write - /home/user/bsdcapsicum.txt (Errno::ENOTCAPABLE)
# [parent] Write OK

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

bsdcapsicum.rb
BSD Zero Clause
See LICENSE

ruby-capsicum
Freaky/ruby-capsicum is released under the terms of the MIT license
See LICENSE.ruby-capsicum