bsdcontrol.rb 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90a98e28b884d5183cefa9e1edc521feca8a6a2b36244deb3cebd3832cc0ca88
+  data.tar.gz: bdb8514fce915c367f8750ee20de5106c7f0e54ad437c55af8895f4123cae4a3
+SHA512:
+  metadata.gz: 179433d4c7fb138be1a572b732a17062375f3153b069459e1fe75dee7db9f8a3c6737d82d5709bd8f91f220380ec429c5f75d99183f0f6d1558a28c0932bf1e4
+  data.tar.gz: 45384e9aee1f2b8ddb12376049611a83769e9b4c7b78086eb5927a41e7b50abce29fdc56aa14cd17734b5c7efd2aa0ff99a7c3c04db67d44a57cc894b08287af

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2023 by 0x1eef <0x1eef@protonmail.com>
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+## About
+
+bsdcontrol.rb provides Ruby bindings for libhbsdcontrol from the
+[HardenedBSD](https://HardenedBSD.org) project.
+
+## Examples
+
+__Features__
+
+The first example prints a list of HardenedBSD features that
+can be enabled, disabled or restored to the system default
+setting:
+
+``` ruby
+#!/usr/bin/env ruby
+# Required privileges: user, superuser
+require "bsdcontrol"
+BSD::Control
+  .available_features
+  .each do
+  print "The ", _1.name, " feature is available", "\n"
+end
+```
+
+__Enable__
+
+The following example enables the mprotect feature for the emacs binary. When
+a feature is enabled for a given file, that setting takes precendence
+over the system default. The system default can be restored with
+[BSD::Control::Feature#sysdef!](http://0x1eef.github.io/x/bsdcontrol.rb/BSD/Control/Feature.html#sysdef!-instance_method):
+
+``` ruby
+#!/usr/bin/env ruby
+# Required privileges: superuser
+require "bsdcontrol"
+BSD::Control
+  .feature(:mprotect)
+  .enable!("/usr/local/bin/emacs-29.2")
+```
+
+__Status__
+
+There are five recognized statuses: `unknown`, `enabled`, `disabled`,
+`sysdef`, and `invalid`. The `sysdef` status indicates that a feature
+is configured to use the system default, and it is the most common
+status:
+
+``` ruby
+#!/usr/bin/env ruby
+# Required privileges: superuser
+require "bsdcontrol"
+BSD::Control
+  .feature(:mprotect)
+  .status("/bin/ls") # => :sysdef
+```
+
+## Documentation
+
+A complete API reference is available at
+[0x1eef.github.io/x/bsdcontrol.rb](https://0x1eef.github.io/x/bsdcontrol.rb).
+
+## Install
+
+**Rubygems.org**
+
+bsdcontrol.rb can be installed via rubygems.org:
+
+    gem install bsdcontrol.rb
+
+## Sources
+
+* [GitHub](https://github.com/0x1eef/bsdcontrol.rb)
+* [GitLab](https://gitlab.com/0x1eef/bsdcontrol.rb)
+* [git.HardenedBSD.org](https://git.HardenedBSD.org/0x1eef/bsdcontrol.rb)
+
+## License
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
+<br>
+See [LICENSE](./LICENSE).
+

data/ext/bsdcontrol.rb/bsdcontrol.c

@@ -0,0 +1,24 @@
+#include <ruby.h>
+#include "context.h"
+#include "feature.h"
+
+void
+Init_bsdcontrol(void)
+{
+    VALUE rb_mBSD     = rb_const_get(rb_cObject, rb_intern("BSD")),
+          rb_mControl = rb_const_get(rb_mBSD, rb_intern("Control")),
+          rb_cFeature = rb_const_get(rb_mControl, rb_intern("Feature")),
+          rb_cContext = rb_const_get(rb_mControl, rb_intern("Context"));
+    rb_define_alloc_func(rb_cContext, bsdcontrol_context_alloc);
+    rb_define_method(
+        rb_cContext, "library_version", bsdcontrol_context_library_version, 0);
+    rb_define_method(rb_cContext,
+                     "available_features",
+                     bsdcontrol_context_available_features,
+                     0);
+    rb_define_method(rb_cFeature, "status", bsdcontrol_feature_status, 1);
+    rb_define_method(rb_cFeature, "sysdef!", bsdcontrol_feature_sysdef, 1);
+    rb_define_private_method(rb_cFeature, "set!", bsdcontrol_feature_set, 2);
+    rb_define_const(rb_cFeature, "ENABLED", INT2NUM(HBSDCTRL_STATE_ENABLED));
+    rb_define_const(rb_cFeature, "DISABLED", INT2NUM(HBSDCTRL_STATE_DISABLED));
+}

data/ext/bsdcontrol.rb/context.c

@@ -0,0 +1,64 @@
+#include <ruby.h>
+#include <libhbsdcontrol.h>
+#include "context.h"
+#include "glue.h"
+
+static int FLAGS             = HBSDCTRL_FEATURE_STATE_FLAG_NONE;
+static const char *NAMESPACE = LIBHBSDCONTROL_DEFAULT_NAMESPACE;
+static void bsdcontrol_context_free(hbsdctrl_ctx_t *);
+
+VALUE
+bsdcontrol_context_alloc(VALUE klass)
+{
+    hbsdctrl_ctx_t *ctx;
+    ctx = hbsdctrl_ctx_new(FLAGS, NAMESPACE);
+    if (ctx == NULL)
+    {
+        rb_raise(rb_eSystemCallError, "hbsdctrl_ctx_new");
+    }
+    return Data_Wrap_Struct(klass, NULL, bsdcontrol_context_free, ctx);
+}
+
+static void
+bsdcontrol_context_free(hbsdctrl_ctx_t *ctx)
+{
+    hbsdctrl_ctx_free(&ctx);
+}
+
+/*
+ * BSD::Control::Context#available_features
+ * BSD::Control.available_features
+ * BSD::Control::Feature.available
+ */
+VALUE
+bsdcontrol_context_available_features(VALUE self)
+{
+    VALUE rb_mBSD     = rb_const_get(rb_cObject, rb_intern("BSD")),
+          rb_mControl = rb_const_get(rb_mBSD, rb_intern("Control")),
+          rb_cFeature = rb_const_get(rb_mControl, rb_intern("Feature")),
+          feature = 0, features = rb_ary_new();
+    hbsdctrl_ctx_t *ctx;
+    char **name;
+    ctx  = bsdcontrol_unwrap(self);
+    name = hbsdctrl_ctx_all_feature_names(ctx);
+    while (*name != NULL)
+    {
+        feature = rb_funcall(
+            rb_cFeature, rb_intern("new"), 2, rb_str_new2(*name), self);
+        rb_ary_push(features, feature);
+        name++;
+    }
+    return features;
+}
+
+/*
+ * BSD::Control::Context#library_version
+ * BSD::Control.library_version
+ */
+VALUE
+bsdcontrol_context_library_version(VALUE self)
+{
+    hbsdctrl_ctx_t *ctx;
+    ctx = bsdcontrol_unwrap(self);
+    return ULONG2NUM(ctx->hc_version);
+}

data/ext/bsdcontrol.rb/context.h

@@ -0,0 +1,6 @@
+#include <ruby.h>
+#include <libhbsdcontrol.h>
+
+VALUE bsdcontrol_context_alloc(VALUE);
+VALUE bsdcontrol_context_library_version(VALUE);
+VALUE bsdcontrol_context_available_features(VALUE);

data/ext/bsdcontrol.rb/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+$LIBS << ' -lhbsdcontrol'
+create_makefile("bsdcontrol.rb")

data/ext/bsdcontrol.rb/feature.c

@@ -0,0 +1,96 @@
+#include <ruby.h>
+#include <libhbsdcontrol.h>
+#include <fcntl.h>
+#include <errno.h>
+#include "feature.h"
+#include "context.h"
+#include "glue.h"
+
+/*
+ * BSD::Control::Feature#status
+ */
+VALUE
+bsdcontrol_feature_status(VALUE self, VALUE path)
+{
+    int fd;
+    VALUE rbcontext;
+    hbsdctrl_feature_t *feature;
+    hbsdctrl_feature_state_t state;
+    hbsdctrl_ctx_t *ctx;
+    rbcontext = rb_funcall(self, rb_intern("context"), 0);
+    fd        = bsdcontrol_open(path);
+    ctx       = bsdcontrol_unwrap(rbcontext);
+    feature   = bsdcontrol_find_feature(ctx, self);
+    errno     = 0;
+    if (feature->hf_get(ctx, feature, &fd, &state) == RES_FAIL)
+    {
+        close(fd);
+        errno == 0 ? rb_raise(rb_eSystemCallError, "hf_get")
+                   : rb_syserr_fail(errno, "hf_get");
+    }
+    else
+    {
+        const char *str;
+        close(fd);
+        str = hbsdctrl_feature_state_to_string(&state);
+        return ID2SYM(rb_intern(str));
+    }
+}
+
+/*
+ * BSD::Control::Feature#set!
+ */
+VALUE
+bsdcontrol_feature_set(VALUE self, VALUE path, VALUE rbstate)
+{
+    int fd;
+    VALUE rbcontext;
+    hbsdctrl_feature_t *feature;
+    hbsdctrl_ctx_t *ctx;
+    int state;
+    rbcontext = rb_funcall(self, rb_intern("context"), 0);
+    fd        = bsdcontrol_open(path);
+    ctx       = bsdcontrol_unwrap(rbcontext);
+    feature   = bsdcontrol_find_feature(ctx, self);
+    state     = NUM2INT(rbstate);
+    errno     = 0;
+    if (feature->hf_apply(ctx, feature, &fd, &state) == RES_FAIL)
+    {
+        close(fd);
+        errno == 0 ? rb_raise(rb_eSystemCallError, "hf_apply")
+                   : rb_syserr_fail(errno, "hf_apply");
+    }
+    else
+    {
+        close(fd);
+        return Qtrue;
+    }
+}
+
+/*
+ * BSD::Control::Feature#sysdef!
+ */
+VALUE
+bsdcontrol_feature_sysdef(VALUE self, VALUE path)
+{
+    int fd;
+    VALUE rbcontext;
+    hbsdctrl_feature_t *feature;
+    hbsdctrl_ctx_t *ctx;
+    rbcontext = rb_funcall(self, rb_intern("context"), 0);
+    fd        = bsdcontrol_open(path);
+    ctx       = bsdcontrol_unwrap(rbcontext);
+    feature   = bsdcontrol_find_feature(ctx, self);
+    errno     = 0;
+    if (feature->hf_unapply(ctx, feature, &fd, NULL) == RES_FAIL)
+    {
+        close(fd);
+        errno == 0 ? rb_raise(rb_eSystemCallError, "hf_unapply")
+                   : rb_syserr_fail(errno, "hf_unapply");
+    }
+    else
+    {
+        close(fd);
+        return Qtrue;
+    }
+}

data/ext/bsdcontrol.rb/feature.h

@@ -0,0 +1,4 @@
+#include <ruby.h>
+VALUE bsdcontrol_feature_status(VALUE, VALUE);
+VALUE bsdcontrol_feature_set(VALUE,VALUE,VALUE);
+VALUE bsdcontrol_feature_sysdef(VALUE, VALUE);

data/ext/bsdcontrol.rb/glue.c

@@ -0,0 +1,35 @@
+#include <ruby.h>
+#include <libhbsdcontrol.h>
+#include <fcntl.h>
+#include "glue.h"
+#include "context.h"
+
+int
+bsdcontrol_open(VALUE path)
+{
+    int fd;
+    Check_Type(path, T_STRING);
+    fd = open(RSTRING_PTR(path), O_PATH);
+    if (fd == -1)
+    {
+        rb_syserr_fail(errno, "open");
+    }
+    return fd;
+}
+
+hbsdctrl_ctx_t *
+bsdcontrol_unwrap(VALUE rbcontext)
+{
+    hbsdctrl_ctx_t *ctx;
+    Data_Get_Struct(rbcontext, hbsdctrl_ctx_t, ctx);
+    return ctx;
+}
+
+hbsdctrl_feature_t *
+bsdcontrol_find_feature(hbsdctrl_ctx_t *ctx, VALUE rbfeature)
+{
+    VALUE name;
+    name = rb_funcall(rbfeature, rb_intern("name"), 0);
+    Check_Type(name, T_STRING);
+    return hbsdctrl_ctx_find_feature_by_name(ctx, RSTRING_PTR(name));
+}

data/ext/bsdcontrol.rb/glue.h

@@ -0,0 +1,7 @@
+#pragma once
+#include <ruby.h>
+#include <libhbsdcontrol.h>
+
+int bsdcontrol_open(VALUE);
+hbsdctrl_ctx_t* bsdcontrol_unwrap(VALUE);
+hbsdctrl_feature_t* bsdcontrol_find_feature(hbsdctrl_ctx_t*, VALUE);

data/lib/bsd/control/context.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BSD::Control
+  ##
+  # The {BSD::Control::Context BSD::Control::Context} class encapsulates
+  # and persists a clang data structure (hbsdctrl_ctx_t).
+  class Context
+  end
+end

data/lib/bsd/control/feature.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module BSD::Control
+  class Feature < Struct.new(:name, :context)
+    ##
+    # @return [Array<BSD::Control::Feature>]
+    #  Returns an array of available features
+    def self.available
+      BSD::Control.available_features
+    end
+
+    ##
+    # @group Actions
+
+    ##
+    # Enables a feature for a given file
+    #
+    # @param [String] path
+    #  The path to a file
+    #
+    # @raise [SystemCallError]
+    #  Might raise a number of Errno exceptions
+    #
+    # @return [Boolean]
+    #  Returns true on success
+    def enable!(path)
+      set!(path, ENABLED)
+    end
+
+    ##
+    # Disables a feature for a given file
+    #
+    # @param [String] path
+    #  The path to a file
+    #
+    # @raise [SystemCallError]
+    #  Might raise a number of Errno exceptions
+    #
+    # @return [Boolean]
+    #  Returns true on success
+    def disable!(path)
+      set!(path, DISABLED)
+    end
+
+    ##
+    # @!method sysdef!(path)
+    #   Restores the system default for a given file
+    #
+    #   @param [String] path
+    #     The path to a file
+    #
+    #   @raise [SystemCallError]
+    #     Might raise a number of Errno exceptions
+    #
+    #   @return [Boolean]
+    #     Returns true on success
+
+    # @endgroup
+
+    ##
+    # @group Queries
+
+    ##
+    # @param [String] path
+    #  The path to a file
+    #
+    # @return [Boolean]
+    #  Returns true when a feature is enabled
+    def enabled?(path)
+      status(path) == :enabled
+    end
+
+    ##
+    # @param [String] path
+    #  The path to a file.
+    #
+    # @return [Boolean]
+    #  Returns true when a feature is disabled
+    def disabled?(path)
+      status(path) == :disabled
+    end
+
+    ##
+    # @param [String] path
+    #  The path to a file
+    #
+    # @return [Boolean]
+    #  Returns true when the system default setting is used
+    def sysdef?(path)
+      status(path) == :sysdef
+    end
+
+    ##
+    # @param [String] path
+    #  The path to a file
+    #
+    # @return [Boolean]
+    #  Returns true when a feature is in an invalid state
+    #  (eg: the feature is both enabled and disabled at the same time)
+    def invalid?(path)
+      status(path) == :invalid
+    end
+
+    ##
+    # @!method status(path)
+    #   @param [String] path
+    #     The path to a file
+    #
+    #   @raise [SystemCallError]
+    #     Might raise a number of Errno exceptions
+    #
+    #   @return [Symbol]
+    #     Returns the status of a feature for a given file.
+    #     Status could be: `:unknown`, `:enabled`, `:disabled`,
+    #     `:sysdef`, or `:invalid`.
+
+    # @endgroup
+
+    ##
+    # @group Predicates
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `pageexec`
+    def pageexec?
+      name == "pageexec"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `mprotect`
+    def mprotect?
+      name == "mprotect"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `segvguard`
+    def segvguard?
+      name == "segvguard"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `aslr`
+    def aslr?
+      name == "aslr"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `shlibrandom`
+    def shlibrandom?
+      name == "shlibrandom"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `disallow_map32bit`
+    def disallow_map32bit?
+      name == "disallow_map32bit"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `insecure_kmod`
+    def insecure_kmod?
+      name == "insecure_kmod"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `harden_shm`
+    def harden_shm?
+      name == "harden_shm"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true for `prohibit_ptrace_capsicum`
+    def prohibit_ptrace_capsicum?
+      name == "prohibit_ptrace_capsicum"
+    end
+
+    # @endgroup
+  end
+end

data/lib/bsd/control/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BSD
+  module Control
+    VERSION = "0.2.0"
+  end
+end

data/lib/bsd/control.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BSD
+end unless defined?(BSD)
+
+module BSD::Control
+  Error = Class.new(RuntimeError)
+
+  ##
+  # @return [BSD::Control::Context]
+  #  Returns an instance of {BSD::Control::Context BSD::Control::Context}
+  def self.context
+    @context ||= BSD::Control::Context.new
+  end
+
+  ##
+  # @return [String]
+  #  Returns the version of libhbsdcontrol
+  def self.library_version
+    context.library_version
+  end
+
+  ##
+  # @return [Array<BSD::Control::Feature>]
+  #  Returns an array of available features
+  def self.available_features
+    context.available_features
+  end
+
+  ##
+  # @example
+  #   BSD::Control
+  #     .feature(:mprotect)
+  #     .enable!("/usr/local/bin/emacs-29.2")
+  #
+  # @param [String] name
+  #  The name of a feature
+  #
+  # @raise [BSD::Control::Error]
+  #  When a feature wasn't found
+  #
+  # @return [BSD::Control::Feature]
+  #  Returns an instance of {BSD::Control::Feature BSD::Control::Feature}
+  def self.feature(name)
+    feature = available_features.find { _1.name == name.to_s }
+    feature || raise(Error, "'#{name}' wasn't found")
+  end
+
+  require_relative "control/context"
+  require_relative "control/feature"
+  require_relative "../bsdcontrol.rb.so"
+end

data/lib/bsdcontrol.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require_relative "bsd/control"

data/share/bsdcontrol.rb/examples/1_available_features.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Required privileges: user, superuser
+require "bsdcontrol"
+BSD::Control
+  .available_features
+  .each do
+  print "The ", _1.name, " feature is available", "\n"
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: bsdcontrol.rb
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- '0x1eef'
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+- !ruby/object:Gem::Dependency
+  name: test-cmd.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: Ruby bindings for libhbsdcontrol
+email:
+- 0x1eef@protonmail.com
+executables: []
+extensions:
+- ext/bsdcontrol.rb/extconf.rb
+extra_rdoc_files: []
+files:
+- "./ext/bsdcontrol.rb/bsdcontrol.c"
+- "./ext/bsdcontrol.rb/context.c"
+- "./ext/bsdcontrol.rb/context.h"
+- "./ext/bsdcontrol.rb/extconf.rb"
+- "./ext/bsdcontrol.rb/feature.c"
+- "./ext/bsdcontrol.rb/feature.h"
+- "./ext/bsdcontrol.rb/glue.c"
+- "./ext/bsdcontrol.rb/glue.h"
+- "./lib/bsd/control.rb"
+- "./lib/bsd/control/context.rb"
+- "./lib/bsd/control/feature.rb"
+- "./lib/bsd/control/version.rb"
+- "./lib/bsdcontrol.rb"
+- "./share/bsdcontrol.rb/examples/1_available_features.rb"
+- LICENSE
+- README.md
+- ext/bsdcontrol.rb/extconf.rb
+homepage: https://git.hardenedbsd.org/0x1eef/bsdcontrol.rb#readme
+licenses:
+- 0BSD
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Ruby bindings for libhbsdcontrol
+test_files: []