capng_c 0.1.3 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bb0e5ea482272f6f1678202e013e2279429a8d8db9331560a0037d5d3affee5
-  data.tar.gz: d00913ec86725ff56ec782cec00ade00c12ce7583963dabe080d2ae7f43a6de2
+  metadata.gz: d8fb8b88d94a62f191e40dd68b4ec9b2e8c088de2d58d11eee06acee1fccff5a
+  data.tar.gz: fef4a3cfb603eb2399453adb308b3e573e07916504c63ac93fd65caab4455f13
 SHA512:
-  metadata.gz: 7fffbe03cb38e5237a24a4dacd9c0b0908d9d63692f04ef2c8e4e0181d96860f3ca0c6d2a7c35319123aaf6176b1faca303c8a6d4ddff1cd7c413250297112b6
-  data.tar.gz: 022ef6afb55bcaac0b83e8a31ae634f7839a2f8a6f49dc493328f0dd8ee44f04420227cf37eee3169142d6b5bbe8ee1c5df976f4e0158deffa225545c6c863c9
+  metadata.gz: b9852afd96a5821ec3133c8b72c783af1ea0a5a5cf85645a9491335a76d8eb03e50e170abec25b9e18255a66952bb1ae2aef4505d883981dd7a928f2c8f83be3
+  data.tar.gz: 4d4ea024e06ce6d55276bc4e87b227836a7eab13d75417e457ab1adec6cf4042e7f0a8b39494f484f164681fb46704eaeebf15aa5fd06e75d92aa7a73ec2f4f2

data/.clang-format

@@ -0,0 +1,5 @@
+BasedOnStyle: Mozilla
+ColumnLimit: 90
+BinPackParameters: true
+BinPackArguments: false
+AllowShortCaseLabelsOnASingleLine: false

data/.github/workflows/apt.yml

@@ -0,0 +1,35 @@
+name: Apt based Linux
+on:
+  push:
+  pull_request:
+jobs:
+  build:
+    name: Build
+    strategy:
+      fail-fast: false
+      matrix:
+        label:
+          - Debian GNU/Linux Buster amd64
+          - Ubuntu Bionic amd64
+          - Ubuntu Focal amd64
+        include:
+          - label: Debian GNU/Linux Buster amd64
+            test-docker-image: debian:buster
+            test-script: ci/apt-test.sh
+          - label: Ubuntu Bionic amd64
+            test-docker-image: ubuntu:bionic
+            test-script: ci/apt-test.sh
+          - label: Ubuntu Focal amd64
+            test-docker-image: ubuntu:focal
+            test-script: ci/apt-test.sh
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - name: rake compile & rake test
+        run: |
+          docker run \
+          --rm \
+          --tty \
+          --volume ${PWD}:/capng \
+          ${{ matrix.test-docker-image }} \
+          /capng/${{ matrix.test-script }}

data/.github/workflows/linux.yml

@@ -1,4 +1,4 @@
-name: Linux testing
+name: Multiple Ruby version tests
 on:
   - push
   - pull_request

data/.github/workflows/yum.yml

@@ -0,0 +1,39 @@
+name: Yum based Linux
+on:
+  push:
+  pull_request:
+jobs:
+  build:
+    name: Build
+    strategy:
+      fail-fast: false
+      matrix:
+        label:
+          - CentOS 7 x86_64
+          - CentOS 8 x86_64
+          - Fedora 33 x86_64
+          - AmazonLinux 2 x86_64
+        include:
+          - label: CentOS 7 x86_64
+            test-docker-image: centos:7
+            test-script: ci/yum-test.sh
+          - label: CentOS 8 x86_64
+            test-docker-image: centos:8
+            test-script: ci/yum-test.sh
+          - label: Fedora 33 x86_64
+            test-docker-image: fedora:33
+            test-script: ci/yum-test.sh
+          - label: AmazonLinux 2 x86_64
+            test-docker-image: amazonlinux:2
+            test-script: ci/yum-test.sh
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - name: rake compile & rake test
+        run: |
+          docker run \
+          --rm \
+          --tty \
+          --volume ${PWD}:/capng \
+          ${{ matrix.test-docker-image }} \
+          /capng/${{ matrix.test-script }}

data/Gemfile

@@ -1,4 +1,6 @@
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in ioext.gemspec
+# Specify your gem's dependencies in capng_c.gemspec
 gemspec
+
+gem "irb"

data/README.md

@@ -1,9 +1,21 @@
 # Capng_c
 
-![Linux testing](https://github.com/cosmo0920/capng_c/workflows/Linux%20testing/badge.svg?branch=main)
+![Multiple Ruby version tests](https://github.com/fluent-plugins-nursery/capng_c/workflows/Multiple%20Ruby%20version%20tests/badge.svg?branch=main)
+![Apt based Linux](https://github.com/fluent-plugins-nursery/capng_c/workflows/Apt%20based%20Linux/badge.svg?branch=main)
+![Yum based Linux](https://github.com/fluent-plugins-nursery/capng_c/workflows/Yum%20based%20Linux/badge.svg?branch=main)
 
 libcap-ng bindings for Ruby.
 
+## Prerequisites
+
+* pkg-config package for linking libcap-ng library
+* libcap-ng and its development packages
+  * libcap-ng-dev on Debian GNU/Linux and Ubuntu
+  * libcap-ng-devel on CentOS 7/8, Fedora 33, AmazonLinux 2
+* Ruby and its development packages
+  * ruby-dev on Debian GNU/Linux and Ubuntu
+  * ruby-devel on CentOS 7/8, Fedora 33, AmazonLinux 2
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,6 +32,10 @@ Or install it yourself as:
 
     $ gem install capng_c
 
+## Usage
+
+The usage examples are put in [example directory](example).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -28,4 +44,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/cosmo0920/capng_c.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fluent-plugins-nursery/capng_c.

data/capng_c.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{libcap-ng bindings for Ruby.}
   spec.description   = spec.summary
-  spec.homepage      = "https://github.com/cosmo0920/cap-ng_c"
-
+  spec.homepage      = "https://github.com/fluent-plugins-nursery/capng_c"
+  spec.license       = "Apache-2.0"
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] = spec.homepage
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 12.0"
   spec.add_development_dependency "rake-compiler", "~> 1.0"
   spec.add_development_dependency "test-unit", "~> 3.3.3"
+  spec.add_development_dependency "yard", "~> 0.9"
 end

data/ci/apt-test.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+set -exu
+
+export DEBIAN_FRONTEND=noninteractive
+
+apt update
+apt install -V -y lsb-release
+
+apt install -V -y ruby-dev git build-essential pkg-config
+apt install -V -y libcap-ng-dev
+cd /capng && \
+    gem install bundler --no-document && \
+    bundle install && \
+    bundle exec rake

data/ci/yum-test.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+set -exu
+
+distribution=$(cat /etc/system-release-cpe | awk '{print substr($0, index($1, "o"))}' | cut -d: -f2)
+version=$(cat /etc/system-release-cpe | awk '{print substr($0, index($1, "o"))}' | cut -d: -f4)
+USE_SCL=0
+USE_AMZN_EXT=0
+
+case ${distribution} in
+  amazon)
+    case ${version} in
+      2)
+        DNF=yum
+        USE_AMZN_EXT=1
+        ;;
+    esac
+    ;;
+  centos)
+    case ${version} in
+      7)
+        DNF=yum
+        USE_SCL=1
+        ;;
+      *)
+        DNF="dnf --enablerepo=PowerTools"
+        ;;
+    esac
+    ;;
+  fedoraproject)
+    case ${version} in
+      33)
+        DNF=yum
+        ;;
+    esac
+    ;;
+esac
+
+${DNF} groupinstall -y "Development Tools"
+
+if [ $USE_SCL -eq 1 ]; then
+    ${DNF} install -y centos-release-scl && \
+    ${DNF} install -y \
+    rh-ruby26-ruby-devel \
+    rh-ruby26-rubygems \
+    rh-ruby26-rubygem-rake \
+    rpm-build
+elif [ $USE_AMZN_EXT -eq 1 ]; then
+    amazon-linux-extras install -y ruby2.6 && \
+    ${DNF} install -y ruby-devel
+else
+    ${DNF} install -y ruby-devel \
+           rubygems \
+           rpm-build
+fi
+${DNF} install -y libcap-ng-devel
+
+if [ $USE_SCL -eq 1 ]; then
+    # For unbound variable error
+    export MANPATH=
+    cd /capng && source /opt/rh/rh-ruby26/enable && gem install bundler --no-document && bundle install && bundle exec rake
+else
+    cd /capng && gem install bundler --no-document && bundle install && bundle exec rake
+fi

data/example/file_capability.rb

@@ -0,0 +1,36 @@
+# Copyright 2020- Hiroshi Hatake
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capng'
+
+if ARGV.size != 1
+  puts "specify file path on ARGV."
+  exit 1
+end
+
+if Process.uid != 0
+  puts "Needed to run as root!"
+  exit 2
+end
+
+path = ARGV[0]
+capng = CapNG.new(:file, path)
+print = CapNG::Print.new
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+capng.clear(:caps)
+ret = capng.update(:add, CapNG::Type::EFFECTIVE | CapNG::Type::INHERITABLE | CapNG::Type::PERMITTED,
+                   [:dac_read_search, :dac_override])
+puts "updating capability: #{ret ? "success" : "fail"}"
+capng.apply_caps_file(path)
+puts "updated capability: #{print.caps_text(:buffer, :effective)}"

data/example/process_capability.rb

@@ -0,0 +1,59 @@
+# Copyright 2020- Hiroshi Hatake
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capng'
+
+if Process.uid != 0
+  puts "Needed to run as root!"
+  exit 2
+end
+
+capng = CapNG.new(:current_process)
+
+print = CapNG::Print.new
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+target_file = ARGV[0] || "/var/log/syslog"
+capng.clear(:caps)
+
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+ret = capng.update(:add, CapNG::Type::EFFECTIVE | CapNG::Type::INHERITABLE | CapNG::Type::PERMITTED, :dac_read_search)
+puts "CapNG#update: #{ret ? 'success' : 'fail'}"
+
+ret = capng.apply(:caps)
+puts "CapNG#apply(add): #{ret ? 'success' : 'fail'}"
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+path = "/var/log/syslog"
+unless File.readable?(path)
+  puts "-----unreadable!!!!-----\ntarget: #{target_file}"
+end
+contents = File.read(target_file)
+if contents.length >= 0
+  puts "succeeded to read: #{target_file}"
+end
+
+ret = capng.update(:drop, CapNG::Type::EFFECTIVE | CapNG::Type::INHERITABLE | CapNG::Type::PERMITTED, :dac_read_search)
+puts "CapNG#update(drop): #{ret ? 'success' : 'fail'}"
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+
+ret = capng.apply(:caps)
+puts "CapNG#apply(drop): #{ret ? 'success' : 'fail'}"
+
+unless File.readable?(path)
+  puts "-----unreadable!!!!-----\ntarget: #{target_file}"
+end
+begin
+  File.read(target_file)
+rescue Errno::EACCES
+  puts "permission denied even if run as root"
+end

data/example/process_capability_without_root.rb

@@ -0,0 +1,36 @@
+# Copyright 2020- Hiroshi Hatake
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capng'
+
+capng = CapNG.new(:current_process)
+unless capng.have_capability?(:effective, :dac_read_search)
+  puts "This example needs to setup :dac_read_search capability on running Ruby executable."
+  exit 2
+end
+
+print = CapNG::Print.new
+puts "capability: #{print.caps_text(:buffer, :effective)}"
+target_file = ARGV[0] || "/var/log/syslog"
+
+path = "/var/log/syslog"
+unless File.readable?(path)
+  puts "-----unreadable!!!!-----\ntarget: #{target_file}"
+end
+if capng.have_capability?(:effective, :dac_read_search)
+  contents = File.read(target_file)
+  if contents.length >= 0
+    puts "succeeded to read: #{target_file} w/o root user"
+  end
+end

data/ext/capng/capability.c

@@ -13,21 +13,37 @@
 
 #include <capng.h>
 
-struct CapNGCapability {};
-
-static void capng_capability_free(void* capng);
-
-static const rb_data_type_t rb_capng_capability_type = {
-  "capng_capability/c_runtime",
-  {
-    0,
-    capng_capability_free,
-    0,
-  },
-  NULL,
-  NULL,
-  RUBY_TYPED_FREE_IMMEDIATELY
-};
+/* clang-format off */
+/*
+ * Document-class: CapNG::Capability
+ *
+ * Check Linux capabilities and define its constants.
+ *
+ * @example
+ *  require 'capng'
+ *
+ *  @cap = CapNG::Capability.new
+ *
+ *  @cap.from_name(:dac_read_search) #=> 2
+ *  @cap.to_name(CapNG::Capability::DAC_READ_SEARCH) #=> "dac_read_search"
+ */
+/* clang-format on */
+
+struct CapNGCapability
+{};
+
+static void
+capng_capability_free(void* capng);
+
+static const rb_data_type_t rb_capng_capability_type = { "capng_capability/c_runtime",
+                                                         {
+                                                           0,
+                                                           capng_capability_free,
+                                                           0,
+                                                         },
+                                                         NULL,
+                                                         NULL,
+                                                         RUBY_TYPED_FREE_IMMEDIATELY };
 
 static void
 capng_capability_free(void* ptr)
@@ -45,16 +61,29 @@ rb_capng_capability_alloc(VALUE klass)
   return obj;
 }
 
+/*
+ * Initalize Capability class.
+ *
+ * @return [nil]
+ *
+ */
 static VALUE
 rb_capng_capability_initialize(VALUE self)
 {
   return Qnil;
 }
 
+/*
+ * Obtain capability name from capability value.
+ *
+ * @param rb_capability [Integer] Capability constant value.
+ * @return [String]
+ *
+ */
 static VALUE
 rb_capng_capability_to_name(VALUE self, VALUE rb_capability)
 {
-  const char *name = capng_capability_to_name(NUM2UINT(rb_capability));
+  const char* name = capng_capability_to_name(NUM2UINT(rb_capability));
 
   if (name)
     return rb_str_new2(name);
@@ -62,20 +91,28 @@ rb_capng_capability_to_name(VALUE self, VALUE rb_capability)
     return rb_str_new2("unknown");
 }
 
+/*
+ * Obtain capability value from capability name.
+ *
+ * @param rb_capability_name_or_symbol [String or Symbol] Capability constant value.
+ * @return [Integer]
+ *
+ */
 static VALUE
 rb_capng_capability_from_name(VALUE self, VALUE rb_capability_name_or_symbol)
 {
   unsigned int capability;
 
   switch (TYPE(rb_capability_name_or_symbol)) {
-  case T_SYMBOL:
-    capability = capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_name_or_symbol)));
-    break;
-  case T_STRING:
-    capability = capng_name_to_capability(StringValuePtr(rb_capability_name_or_symbol));
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance");
+    case T_SYMBOL:
+      capability =
+        capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_name_or_symbol)));
+      break;
+    case T_STRING:
+      capability = capng_name_to_capability(StringValuePtr(rb_capability_name_or_symbol));
+      break;
+    default:
+      rb_raise(rb_eArgError, "Expected a String or a Symbol instance");
   }
   return INT2NUM(capability);
 }
@@ -83,7 +120,7 @@ rb_capng_capability_from_name(VALUE self, VALUE rb_capability_name_or_symbol)
 void
 Init_capng_capability(VALUE rb_cCapNG)
 {
-  rb_cCapability = rb_define_class_under(rb_cCapNG, "Capability", rb_cObject);
+  VALUE rb_cCapability = rb_define_class_under(rb_cCapNG, "Capability", rb_cObject);
 
   rb_define_alloc_func(rb_cCapability, rb_capng_capability_alloc);
 
@@ -92,47 +129,300 @@ Init_capng_capability(VALUE rb_cCapNG)
   rb_define_method(rb_cCapability, "from_name", rb_capng_capability_from_name, 1);
 
   // Capability constants.
+
+  /* Make arbitrary changes to file UIDs and GIDs (see chown(2)). */
   rb_define_const(rb_cCapability, "CHOWN", INT2NUM(CAP_CHOWN));
+  /*
+   * Bypass file read, write, and execute permission checks.  (DAC
+   * is an abbreviation of "discretionary access control".) */
   rb_define_const(rb_cCapability, "DAC_OVERRIDE", INT2NUM(CAP_DAC_OVERRIDE));
+  /*
+   * * Bypass file read permission checks and directory read and execute permission
+   *   checks;
+   * * invoke open_by_handle_at(2);
+   * * use the linkat(2) AT_EMPTY_PATH flag to create a link to a file referred to by a
+   *   file descriptor.
+   */
   rb_define_const(rb_cCapability, "DAC_READ_SEARCH", INT2NUM(CAP_DAC_READ_SEARCH));
+  /*
+   * * Bypass permission checks on operations that normally require
+   *   the filesystem UID of the process to match the UID of the
+   *   file (e.g., chmod(2), utime(2)), excluding those operations
+   *   covered by CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH;
+   * * set inode flags (see ioctl_iflags(2)) on arbitrary files;
+   * * set Access Control Lists (ACLs) on arbitrary files;
+   * * ignore directory sticky bit on file deletion;
+   * * modify user extended attributes on sticky directory owned by
+   *   any user;
+   * * specify O_NOATIME for arbitrary files in open(2) and
+   *   fcntl(2).
+   */
   rb_define_const(rb_cCapability, "FOWNER", INT2NUM(CAP_FOWNER));
+  /*
+   * * Don't clear set-user-ID and set-group-ID mode bits when a
+   *   file is modified;
+   * * set the set-group-ID bit for a file whose GID does not match
+   *   the filesystem or any of the supplementary GIDs of the
+   *   calling process.
+   */
   rb_define_const(rb_cCapability, "FSETID", INT2NUM(CAP_FSETID));
+  /* Bypass permission checks for sending signals (see kill(2)).
+   * This includes use of the ioctl(2) KDSIGACCEPT operation. */
   rb_define_const(rb_cCapability, "KILL", INT2NUM(CAP_KILL));
+  /*
+   * * Make arbitrary manipulations of process GIDs and
+   *   supplementary GID list;
+   * * forge GID when passing socket credentials via UNIX domain
+   *   sockets;
+   * * write a group ID mapping in a user namespace (see
+   *   user_namespaces(7)).
+   */
   rb_define_const(rb_cCapability, "SETGID", INT2NUM(CAP_SETGID));
+  /*
+   * * Make arbitrary manipulations of process UIDs (setuid(2),
+   *   setreuid(2), setresuid(2), setfsuid(2));
+   * * forge UID when passing socket credentials via UNIX domain
+   *   sockets;
+   * * write a user ID mapping in a user namespace (see
+   *   user_namespaces(7)).
+   */
   rb_define_const(rb_cCapability, "SETUID", INT2NUM(CAP_SETUID));
+  /*
+   * If file capabilities are supported (i.e., since Linux 2.6.24):
+   * add any capability from the calling thread's bounding set to
+   * its inheritable set; drop capabilities from the bounding set
+   * (via prctl(2) PR_CAPBSET_DROP); make changes to the securebits
+   * flags.
+   *
+   * If file capabilities are not supported (i.e., kernels before
+   * Linux 2.6.24): grant or remove any capability in the caller's
+   * permitted capability set to or from any other process.  (This
+   * property of CAP_SETPCAP is not available when the kernel is
+   * configured to support file capabilities, since CAP_SETPCAP has
+   * entirely different semantics for such kernels.)
+   */
   rb_define_const(rb_cCapability, "SETPCAP", INT2NUM(CAP_SETPCAP));
+  /* Set the FS_APPEND_FL and FS_IMMUTABLE_FL inode flags (see ioctl_iflags(2)). */
   rb_define_const(rb_cCapability, "LINUX_IMMUTABLE", INT2NUM(CAP_LINUX_IMMUTABLE));
+  /* Bind a socket to Internet domain privileged ports (port numbers less than 1024).*/
   rb_define_const(rb_cCapability, "NET_BIND_SERIVCE", INT2NUM(CAP_NET_BIND_SERVICE));
+  /* (Unused)  Make socket broadcasts, and listen to multicasts. */
   rb_define_const(rb_cCapability, "NET_BROATCAST", INT2NUM(CAP_NET_BROADCAST));
+  /* Perform various network-related operations:
+   *
+   * * interface configuration;
+   * * administration of IP firewall, masquerading, and accounting;
+   * * modify routing tables;
+   * * bind to any address for transparent proxying;
+   * * set type-of-service (TOS);
+   * * clear driver statistics;
+   * * set promiscuous mode;
+   * * enabling multicasting;
+   * * use setsockopt(2) to set the following socket options:
+   *   * SO_DEBUG, SO_MARK, SO_PRIORITY (for a priority outside the
+   *   * range 0 to 6), SO_RCVBUFFORCE, and SO_SNDBUFFORCE.
+   */
   rb_define_const(rb_cCapability, "NET_ADMIN", INT2NUM(CAP_NET_ADMIN));
+  /*
+   * * Use RAW and PACKET sockets;
+   * * bind to any address for transparent proxying.
+   */
   rb_define_const(rb_cCapability, "NET_RAW", INT2NUM(CAP_NET_RAW));
+  /* Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). */
   rb_define_const(rb_cCapability, "IPC_LOCK", INT2NUM(CAP_IPC_LOCK));
+  /* Bypass permission checks for operations on System V IPC
+   * objects.
+   */
   rb_define_const(rb_cCapability, "IPC_OWNER", INT2NUM(CAP_IPC_OWNER));
+  /*
+   * * Load and unload kernel modules (see init_module(2) and
+   *   delete_module(2)) in kernels before 2.6.25
+   * * drop capabilities from the system-wide capability bounding set.
+   */
   rb_define_const(rb_cCapability, "SYS_MODULE", INT2NUM(CAP_SYS_MODULE));
+  /*
+   * * Perform I/O port operations (iopl(2) and ioperm(2));
+   * * access /proc/kcore;
+   * * employ the FIBMAP ioctl(2) operation;
+   * * open devices for accessing x86 model-specific registers
+   *   (MSRs, see msr(4));
+   * * update /proc/sys/vm/mmap_min_addr;
+   * * create memory mappings at addresses below the value
+   *   specified by /proc/sys/vm/mmap_min_addr;
+   * * map files in /proc/bus/pci;
+   * * open /dev/mem and /dev/kmem;
+   * * perform various SCSI device commands;
+   * * perform certain operations on hpsa(4) and cciss(4) devices;
+   * * perform a range of device-specific operations on other
+   *   devices.
+   */
   rb_define_const(rb_cCapability, "SYS_RAWIO", INT2NUM(CAP_SYS_RAWIO));
+  /*
+   * * Use chroot(2);
+   * * change mount namespaces using setns(2).
+   */
   rb_define_const(rb_cCapability, "SYS_CHROOT", INT2NUM(CAP_SYS_CHROOT));
+  /*
+   * * Trace arbitrary processes using ptrace(2);
+   * * apply get_robust_list(2) to arbitrary processes;
+   * * transfer data to or from the memory of arbitrary processes
+   *   using process_vm_readv(2) and process_vm_writev(2);
+   * * inspect processes using kcmp(2).
+   */
   rb_define_const(rb_cCapability, "SYS_PTRACE", INT2NUM(CAP_SYS_PTRACE));
+  /* Use acct(2). */
   rb_define_const(rb_cCapability, "SYS_PACCT", INT2NUM(CAP_SYS_PACCT));
+  /*
+   * Note:
+   *  this capability is overloaded; see Notes to kernel developers, below.
+   *
+   * * Perform a range of system administration operations
+   *   including: quotactl(2), mount(2), umount(2), pivot_root(2),
+   *   swapon(2), swapoff(2), sethostname(2), and setdomainname(2);
+   * * perform privileged syslog(2) operations (since Linux 2.6.37,
+   *   CAP_SYSLOG should be used to permit such operations);
+   * * perform VM86_REQUEST_IRQ vm86(2) command;
+   * * access the same checkpoint/restore functionality that is
+   *   governed by CAP_CHECKPOINT_RESTORE (but the latter, weaker
+   *   capability is preferred for accessing that functionality).
+   * * perform the same BPF operations as are governed by CAP_BPF
+   *   (but the latter, weaker capability is preferred for
+   *   accessing that functionality).
+   * * employ the same performance monitoring mechanisms as are
+   *   governed by CAP_PERFMON (but the latter, weaker capability
+   *   is preferred for accessing that functionality).
+   * * perform IPC_SET and IPC_RMID operations on arbitrary System
+   *   V IPC objects;
+   * * override RLIMIT_NPROC resource limit;
+   * * perform operations on trusted and security extended
+   *   attributes (see xattr(7));
+   * * use lookup_dcookie(2);
+   * * use ioprio_set(2) to assign IOPRIO_CLASS_RT and (before
+   *   Linux 2.6.25) IOPRIO_CLASS_IDLE I/O scheduling classes;
+   * * forge PID when passing socket credentials via UNIX domain
+   *   sockets;
+   * * exceed /proc/sys/fs/file-max, the system-wide limit on the
+   *   number of open files, in system calls that open files (e.g.,
+   *   accept(2), execve(2), open(2), pipe(2));
+   * * employ CLONE_* flags that create new namespaces with
+   *   clone(2) and unshare(2) (but, since Linux 3.8, creating user
+   *   namespaces does not require any capability);
+   * * access privileged perf event information;
+   * * call setns(2) (requires CAP_SYS_ADMIN in the target
+   *   namespace);
+   * * call fanotify_init(2);
+   * * perform privileged KEYCTL_CHOWN and KEYCTL_SETPERM keyctl(2)
+   *   operations;
+   * * perform madvise(2) MADV_HWPOISON operation;
+   * * employ the TIOCSTI ioctl(2) to insert characters into the
+   *   input queue of a terminal other than the caller's
+   *   controlling terminal;
+   * * employ the obsolete nfsservctl(2) system call;
+   * * employ the obsolete bdflush(2) system call;
+   * * perform various privileged block-device ioctl(2) operations;
+   * * perform various privileged filesystem ioctl(2) operations;
+   * * perform privileged ioctl(2) operations on the /dev/random
+   *   device (see random(4));
+   * * install a seccomp(2) filter without first having to set the
+   *   no_new_privs thread attribute;
+   * * modify allow/deny rules for device control groups;
+   * * employ the ptrace(2) PTRACE_SECCOMP_GET_FILTER operation to
+   *   dump tracee's seccomp filters;
+   * * employ the ptrace(2) PTRACE_SETOPTIONS operation to suspend
+   *   the tracee's seccomp protections (i.e., the
+   *   PTRACE_O_SUSPEND_SECCOMP flag);
+   * * perform administrative operations on many device drivers;
+   * * modify autogroup nice values by writing to
+   *   /proc/[pid]/autogroup (see sched(7)).
+   */
   rb_define_const(rb_cCapability, "SYS_ADMIN", INT2NUM(CAP_SYS_ADMIN));
+  /* Use reboot(2) and kexec_load(2). */
   rb_define_const(rb_cCapability, "SYS_BOOT", INT2NUM(CAP_SYS_BOOT));
+  /*
+   * * Lower the process nice value (nice(2), setpriority(2)) and
+   *   change the nice value for arbitrary processes;
+   * * set real-time scheduling policies for calling process, and
+   *   set scheduling policies and priorities for arbitrary
+   *   processes (sched_setscheduler(2), sched_setparam(2),
+   *   sched_setattr(2));
+   * * set CPU affinity for arbitrary processes
+   *   (sched_setaffinity(2));
+   * * set I/O scheduling class and priority for arbitrary
+   *   processes (ioprio_set(2));
+   * * apply migrate_pages(2) to arbitrary processes and allow
+   *   processes to be migrated to arbitrary nodes;
+   * * apply move_pages(2) to arbitrary processes;
+   * * use the MPOL_MF_MOVE_ALL flag with mbind(2) and
+   *   move_pages(2).
+   */
   rb_define_const(rb_cCapability, "SYS_NICE", INT2NUM(CAP_SYS_NICE));
+  /*
+   * * Use reserved space on ext2 filesystems;
+   * * make ioctl(2) calls controlling ext3 journaling;
+   * * override disk quota limits;
+   * * increase resource limits (see setrlimit(2));
+   * * override RLIMIT_NPROC resource limit;
+   * * override maximum number of consoles on console allocation;
+   * * override maximum number of keymaps;
+   * * allow more than 64hz interrupts from the real-time clock;
+   * * raise msg_qbytes limit for a System V message queue above
+   *   the limit in /proc/sys/kernel/msgmnb (see msgop(2) and
+   *   msgctl(2));
+   * * allow the RLIMIT_NOFILE resource limit on the number of "in-
+   *   flight" file descriptors to be bypassed when passing file
+   *   descriptors to another process via a UNIX domain socket (see
+   *   unix(7));
+   * * override the /proc/sys/fs/pipe-size-max limit when setting
+   *   the capacity of a pipe using the F_SETPIPE_SZ fcntl(2)
+   *   command;
+   * * use F_SETPIPE_SZ to increase the capacity of a pipe above
+   *   the limit specified by /proc/sys/fs/pipe-max-size;
+   * * override /proc/sys/fs/mqueue/queues_max,
+   *   /proc/sys/fs/mqueue/msg_max, and
+   *   /proc/sys/fs/mqueue/msgsize_max limits when creating POSIX
+   *   message queues (see mq_overview(7));
+   * * employ the prctl(2) PR_SET_MM operation;
+   * * set /proc/[pid]/oom_score_adj to a value lower than the
+   *   value last set by a process with CAP_SYS_RESOURCE.
+   */
   rb_define_const(rb_cCapability, "SYS_RESOURCE", INT2NUM(CAP_SYS_RESOURCE));
+  /* Set system clock (settimeofday(2), stime(2), adjtimex(2)); set
+   * real-time (hardware) clock.*/
   rb_define_const(rb_cCapability, "SYS_TIME", INT2NUM(CAP_SYS_TIME));
+  /* Use vhangup(2); employ various privileged ioctl(2) operations
+   * on virtual terminals.
+   */
   rb_define_const(rb_cCapability, "TTY_CONFIG", INT2NUM(CAP_SYS_TTY_CONFIG));
+  /* Create special files using mknod(2). (since Linux 2.4) */
   rb_define_const(rb_cCapability, "MKNOD", INT2NUM(CAP_MKNOD));
+  /* Establish leases on arbitrary files (see fcntl(2)). (since Linux 2.4) */
   rb_define_const(rb_cCapability, "LEASE", INT2NUM(CAP_LEASE));
+  /* Write records to kernel auditing log.  (since Linux 2.6.11) */
   rb_define_const(rb_cCapability, "AUDIT_WRITE", INT2NUM(CAP_AUDIT_WRITE));
+  /* Enable and disable kernel auditing; change auditing filter
+   * rules; retrieve auditing status and filtering rules.  (since Linux 2.6.11)*/
   rb_define_const(rb_cCapability, "AUDIT_CONTROL", INT2NUM(CAP_AUDIT_CONTROL));
 #ifdef CAP_SETFCAP
+  /* Set arbitrary capabilities on a file. since Linux 2.6.24) */
   rb_define_const(rb_cCapability, "SETFCAP", INT2NUM(CAP_SETFCAP));
 #endif
 #ifdef CAP_MAC_OVERRIDE
   rb_define_const(rb_cCapability, "MAC_OVERRIDE", INT2NUM(CAP_MAC_OVERRIDE));
 #endif
 #ifdef CAP_MAC_ADMIN
+  /* Allow MAC configuration or state changes.  Implemented for the
+   * Smack Linux Security Module (LSM). (since Linux 2.6.25)
+   */
   rb_define_const(rb_cCapability, "MAC_ADMIN", INT2NUM(CAP_MAC_ADMIN));
 #endif
 #ifdef CAP_SYSLOG
+  /*
+   * * Perform privileged syslog(2) operations.  See syslog(2) for
+   *   information on which operations require privilege.
+   * * View kernel addresses exposed via /proc and other interfaces
+   *   when /proc/sys/kernel/kptr_restrict has the value 1.  (See
+   *   the discussion of the kptr_restrict in proc(5).)
+   */
   rb_define_const(rb_cCapability, "SYSLOG", INT2NUM(CAP_SYSLOG));
 #endif
 #if defined(CAP_EPOLLWAKEUP) && defined(CAP_BLOCK_SUSPEND)
@@ -142,21 +432,59 @@ Init_capng_capability(VALUE rb_cCapNG)
   rb_define_const(rb_cCapability, "EPOLLWAKEUP", INT2NUM(CAP_EPOLLWAKEUP));
 #endif
 #ifdef CAP_WAKE_ALARM
+  /* Trigger something that will wake up the system (set
+   * CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM timers).
+   */
   rb_define_const(rb_cCapability, "WAKE_ALARM", INT2NUM(CAP_WAKE_ALARM));
 #endif
 #ifdef CAP_BLOCK_SUSPEND
+  /*
+    Employ features that can block system suspend (epoll(7)
+    EPOLLWAKEUP, /proc/sys/wake_lock). (since Linux 3.5)
+  */
   rb_define_const(rb_cCapability, "BLOCK_SUSPEND", INT2NUM(CAP_BLOCK_SUSPEND));
 #endif
 #ifdef CAP_AUDIT_READ
+  /* Allow reading the audit log via a multicast netlink socket. (since Linux 3.16) */
   rb_define_const(rb_cCapability, "AUDIT_READ", INT2NUM(CAP_AUDIT_READ));
 #endif
 #ifdef CAP_PERFMON
+  /*
+   * Employ various performance-monitoring mechanisms, including:
+   *
+   * * call perf_event_open(2)
+   * * employ various BPF operations that have performance
+   *   implications.
+   *
+   * This capability was added in Linux 5.8 to separate out
+   * performance monitoring functionality from the overloaded
+   * CAP_SYS_ADMIN capability.  See also the kernel source file
+   * Documentation/admin-guide/perf-security.rst.
+   */
   rb_define_const(rb_cCapability, "PERFMON", INT2NUM(CAP_PERFMON));
 #endif
 #ifdef CAP_BPF
+  /*
+   * Employ privileged BPF operations; see bpf(2) and
+   * bpf-helpers(7).
+   *
+   * This capability was added in Linux 5.8 to separate out BPF
+   * functionality from the overloaded CAP_SYS_ADMIN capability.
+   * (since Linux 5.8)
+   */
   rb_define_const(rb_cCapability, "BPF", INT2NUM(CAP_BPF));
 #endif
 #ifdef CAP_CHECKPOINT_RESTORE
+  /*
+   * * employ the set_tid feature of clone3(2);
+   * * read the contents of the symbolic links in
+   *   /proc/[pid]/map_files for other processes.
+   *
+   * This capability was added in Linux 5.9 to separate out
+   * checkpoint/restore functionality from the overloaded
+   * CAP_SYS_ADMIN capability.
+   * (since Linux 5.9)
+   */
   rb_define_const(rb_cCapability, "CHECKPOINT_RESTORE", INT2NUM(CAP_CHECKPOINT_RESTORE));
 #endif
 }