endpoint_security 0.1.0-universal-darwin

data/ext/endpoint_security/watchdog.c

@@ -0,0 +1,243 @@
+/* watchdog.c
+ * Calling threads: arm = ES handler without the GVL; heap owner = dedicated pthread without the GVL.
+ * The handler only publishes to a bounded lock-free queue. Ruby APIs are forbidden.
+ */
+#include "client.h"
+
+#include <mach/mach_time.h>
+#include <stdlib.h>
+#include <time.h>
+
+static void
+heap_swap(esrb_watchdog_t *watchdog, size_t left, size_t right)
+{
+    esrb_watchdog_entry_t temporary = watchdog->heap[left];
+    watchdog->heap[left] = watchdog->heap[right];
+    watchdog->heap[right] = temporary;
+    watchdog->heap[left].slot->watchdog_index = left;
+    watchdog->heap[right].slot->watchdog_index = right;
+}
+
+static void
+heap_up(esrb_watchdog_t *watchdog, size_t index)
+{
+    while (index > 0) {
+        size_t parent = (index - 1) / 2;
+        if (watchdog->heap[parent].fire_at <= watchdog->heap[index].fire_at) {
+            break;
+        }
+        heap_swap(watchdog, parent, index);
+        index = parent;
+    }
+}
+
+static void
+heap_down(esrb_watchdog_t *watchdog, size_t index)
+{
+    for (;;) {
+        size_t left = index * 2 + 1;
+        if (left >= watchdog->heap_size) {
+            return;
+        }
+        size_t right = left + 1;
+        size_t smallest = right < watchdog->heap_size && watchdog->heap[right].fire_at < watchdog->heap[left].fire_at
+            ? right
+            : left;
+        if (watchdog->heap[index].fire_at <= watchdog->heap[smallest].fire_at) {
+            return;
+        }
+        heap_swap(watchdog, index, smallest);
+        index = smallest;
+    }
+}
+
+static void
+heap_remove(esrb_watchdog_t *watchdog, size_t index)
+{
+    esrb_slot_t *removed = watchdog->heap[index].slot;
+    removed->watchdog_index = SIZE_MAX;
+    watchdog->heap_size--;
+    if (index == watchdog->heap_size) {
+        return;
+    }
+    watchdog->heap[index] = watchdog->heap[watchdog->heap_size];
+    watchdog->heap[index].slot->watchdog_index = index;
+    esrb_slot_t *moved = watchdog->heap[index].slot;
+    heap_up(watchdog, index);
+    heap_down(watchdog, moved->watchdog_index);
+}
+
+static void
+heap_set(esrb_watchdog_t *watchdog, const esrb_watchdog_request_t *request)
+{
+    size_t index = request->slot->watchdog_index;
+    if (index >= watchdog->heap_size || watchdog->heap[index].slot != request->slot) {
+        if (watchdog->heap_size >= watchdog->capacity) {
+            return;
+        }
+        index = watchdog->heap_size++;
+        request->slot->watchdog_index = index;
+    }
+    watchdog->heap[index] = (esrb_watchdog_entry_t){
+        .slot = request->slot, .position = request->position, .fire_at = request->fire_at
+    };
+    heap_up(watchdog, index);
+    heap_down(watchdog, request->slot->watchdog_index);
+}
+
+static bool
+request_pop(esrb_watchdog_t *watchdog, esrb_watchdog_request_t *output)
+{
+    size_t position = atomic_load_explicit(&watchdog->dequeue_position, memory_order_relaxed);
+    esrb_watchdog_request_t *request = &watchdog->requests[position & watchdog->mask];
+    if (atomic_load_explicit(&request->sequence, memory_order_acquire) != position + 1) {
+        return false;
+    }
+    atomic_store_explicit(&watchdog->dequeue_position, position + 1, memory_order_relaxed);
+    output->slot = request->slot;
+    output->position = request->position;
+    output->fire_at = request->fire_at;
+    atomic_store_explicit(&request->sequence, position + watchdog->capacity, memory_order_release);
+    return true;
+}
+
+bool
+esrb_watchdog_init(esrb_watchdog_t *watchdog, size_t capacity)
+{
+    watchdog->capacity = capacity;
+    watchdog->mask = capacity - 1;
+    watchdog->heap_size = 0;
+    watchdog->requests = calloc(capacity, sizeof(*watchdog->requests));
+    watchdog->heap = calloc(capacity, sizeof(*watchdog->heap));
+    if (watchdog->requests == NULL || watchdog->heap == NULL) {
+        free(watchdog->requests);
+        free(watchdog->heap);
+        watchdog->requests = NULL;
+        watchdog->heap = NULL;
+        return false;
+    }
+    atomic_init(&watchdog->enqueue_position, 0);
+    atomic_init(&watchdog->dequeue_position, 0);
+    for (size_t index = 0; index < capacity; index++) {
+        atomic_init(&watchdog->requests[index].sequence, index);
+    }
+    if (pthread_mutex_init(&watchdog->mutex, NULL) != 0) {
+        free(watchdog->requests);
+        free(watchdog->heap);
+        watchdog->requests = NULL;
+        watchdog->heap = NULL;
+        return false;
+    }
+    if (pthread_cond_init(&watchdog->condition, NULL) != 0) {
+        pthread_mutex_destroy(&watchdog->mutex);
+        free(watchdog->requests);
+        free(watchdog->heap);
+        watchdog->requests = NULL;
+        watchdog->heap = NULL;
+        return false;
+    }
+    return true;
+}
+
+void
+esrb_watchdog_destroy(esrb_watchdog_t *watchdog)
+{
+    if (watchdog->requests == NULL) {
+        return;
+    }
+    pthread_cond_destroy(&watchdog->condition);
+    pthread_mutex_destroy(&watchdog->mutex);
+    free(watchdog->requests);
+    free(watchdog->heap);
+    watchdog->requests = NULL;
+    watchdog->heap = NULL;
+}
+
+void
+esrb_watchdog_abandon(esrb_watchdog_t *watchdog)
+{
+    free(watchdog->requests);
+    free(watchdog->heap);
+    watchdog->requests = NULL;
+    watchdog->heap = NULL;
+}
+
+bool
+esrb_watchdog_arm(esrb_watchdog_t *watchdog, esrb_slot_t *slot)
+{
+    size_t position = atomic_load_explicit(&watchdog->enqueue_position, memory_order_relaxed);
+    for (;;) {
+        esrb_watchdog_request_t *request = &watchdog->requests[position & watchdog->mask];
+        size_t sequence = atomic_load_explicit(&request->sequence, memory_order_acquire);
+        intptr_t difference = (intptr_t)sequence - (intptr_t)position;
+        if (difference == 0) {
+            if (atomic_compare_exchange_weak_explicit(&watchdog->enqueue_position, &position, position + 1,
+                    memory_order_relaxed, memory_order_relaxed)) {
+                request->slot = slot;
+                request->position = slot->position;
+                request->fire_at = slot->fire_at;
+                atomic_store_explicit(&request->sequence, position + 1, memory_order_release);
+                return true;
+            }
+        } else if (difference < 0) {
+            return false;
+        } else {
+            position = atomic_load_explicit(&watchdog->enqueue_position, memory_order_relaxed);
+        }
+    }
+}
+
+static void
+answer_due(esrb_client_t *client, esrb_watchdog_entry_t entry)
+{
+    esrb_slot_t *slot = entry.slot;
+    if (!atomic_load_explicit(&slot->occupied, memory_order_acquire)) {
+        return;
+    }
+    atomic_fetch_add_explicit(&slot->readers, 1, memory_order_acquire);
+    if (!atomic_load_explicit(&slot->occupied, memory_order_acquire) || slot->position != entry.position) {
+        atomic_fetch_sub_explicit(&slot->readers, 1, memory_order_release);
+        return;
+    }
+    uint32_t expected = ESRB_ANSWER_PENDING;
+    if (atomic_compare_exchange_strong_explicit(
+            &slot->answer_state, &expected, ESRB_ANSWER_ANSWERED, memory_order_acq_rel, memory_order_acquire)) {
+        esrb_send_response(client, slot->client, slot->message, client->default_auth,
+            client->default_auth == ES_AUTH_RESULT_ALLOW ? UINT32_MAX : 0, client->default_cache);
+        atomic_fetch_add_explicit(&client->timeouts, 1, memory_order_relaxed);
+        esrb_notify(client);
+    }
+    atomic_fetch_sub_explicit(&slot->readers, 1, memory_order_release);
+}
+
+void *
+esrb_watchdog_main(void *argument)
+{
+    esrb_client_t *client = argument;
+    esrb_watchdog_t *watchdog = &client->watchdog;
+    while (atomic_load_explicit(&client->watchdog_running, memory_order_acquire)) {
+        esrb_watchdog_request_t request;
+        while (request_pop(watchdog, &request)) {
+            heap_set(watchdog, &request);
+        }
+        uint64_t now = mach_absolute_time();
+        while (watchdog->heap_size > 0 && watchdog->heap[0].fire_at <= now) {
+            esrb_watchdog_entry_t entry = watchdog->heap[0];
+            heap_remove(watchdog, 0);
+            answer_due(client, entry);
+            now = mach_absolute_time();
+        }
+
+        struct timespec wake;
+        clock_gettime(CLOCK_REALTIME, &wake);
+        wake.tv_nsec += 1000000;
+        if (wake.tv_nsec >= 1000000000) {
+            wake.tv_sec++;
+            wake.tv_nsec -= 1000000000;
+        }
+        pthread_mutex_lock(&watchdog->mutex);
+        pthread_cond_timedwait(&watchdog->condition, &watchdog->mutex, &wake);
+        pthread_mutex_unlock(&watchdog->mutex);
+    }
+    return NULL;
+}

data/lib/endpoint_security/availability.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module EndpointSecurity
+  # Checks whether events exist on the running macOS version.
+  module Availability
+    @probe_cache = {}
+
+    module_function
+
+    # @return [Gem::Version] running macOS version
+    def runtime_version
+      @runtime_version ||= Gem::Version.new(Open3.capture2("sw_vers", "-productVersion").first.strip)
+    end
+
+    # @return [Boolean] whether +event+ is available on this macOS version
+    def supported_event?(event)
+      runtime_version >= Gem::Version.new(EVENT_MIN_OS.fetch(event.to_sym))
+    end
+
+    # Results of native one-event subscription probes.
+    # @return [Hash<Symbol, Boolean>]
+    def probe_cache = @probe_cache
+
+    # Clears native subscription probe results.
+    # @return [Hash] emptied cache
+    def clear_probe_cache! = @probe_cache.clear
+  end
+end

data/lib/endpoint_security/client.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module EndpointSecurity
+  # Owns an Endpoint Security client and dispatches subscribed messages.
+  class Client
+    class << self
+      # @yield [client]
+      # @return [Object]
+      def open(**)
+        client = new(**)
+        return client unless block_given?
+
+        yield client
+      ensure
+        client&.close if block_given?
+      end
+    end
+
+    # Calls the native constructor.
+    # @api private
+    alias __native_initialize initialize
+    # Calls the native close implementation.
+    # @api private
+    alias __native_close close
+    # Calls the native statistics implementation.
+    # @api private
+    alias __native_stats stats
+
+    # @return [Client]
+    def initialize(mute_self: true, subscribe: nil, probe: :lazy, **)
+      raise ArgumentError, "probe must be :lazy, :eager, or :off" unless %i[lazy eager off].include?(probe.to_sym)
+
+      __native_initialize(mute_self: mute_self, **)
+      initialized = false
+      begin
+        @probe = probe.to_sym
+        @handlers = {}
+        @subscriptions = []
+        @errors = 0
+        @reported_timeouts = 0
+        @running = false
+        mute_process(pid: ::Process.pid) if mute_self
+        if @probe == :eager
+          EventType.all.each do |event|
+            Availability.probe_cache[event] = probe_event(event) if Availability.supported_event?(event)
+          end
+        end
+        self.subscribe(subscribe) if subscribe
+        initialized = true
+      ensure
+        __native_close unless initialized
+      end
+    end
+
+    # @return [Array<Symbol>]
+    def subscribe(*events, skip_unsupported: true, **_options)
+      events = events.flatten.map(&:to_sym) - @subscriptions
+      unsupported = events.reject { |event| supported_event?(event) }
+      if !skip_unsupported && !unsupported.empty?
+        raise UnsupportedEventError, "unsupported events: #{unsupported.join(", ")}"
+      end
+
+      events -= unsupported
+      return @subscriptions if events.empty?
+
+      begin
+        __subscribe(events.map { |event| EventType.value(event) })
+      rescue SubscriptionError => e
+        failed = events.reject { |event| probe_event(event) }
+        failed = events if failed.empty?
+        raise SubscriptionError, "failed to subscribe: #{failed.join(", ")} (#{e.message})"
+      end
+      @subscriptions |= events
+    end
+
+    # @return [Array<Symbol>] remaining subscriptions
+    def unsubscribe(*events)
+      events = events.flatten.map(&:to_sym)
+      return @subscriptions if events.empty?
+
+      __unsubscribe(events.map { |event| EventType.value(event) })
+      @subscriptions -= events
+    end
+
+    # @return [Array] empty subscription list
+    def unsubscribe_all
+      __unsubscribe(nil)
+      @subscriptions.clear
+    end
+
+    # @return [Array<Symbol>] subscriptions reported by Endpoint Security
+    def subscriptions = __subscriptions
+
+    # @return [Client]
+    def on(event, &handler)
+      raise ArgumentError, "handler block is required" unless handler
+
+      @handlers[event.to_sym] = handler
+      self
+    end
+
+    # @return [Client]
+    def on_error(&handler)
+      @error_handler = handler
+      self
+    end
+
+    # @return [Client]
+    def on_timeout(&handler)
+      @timeout_handler = handler
+      self
+    end
+
+    # Mutes other Endpoint Security clients when their first event is observed.
+    # @return [Client]
+    def mute_all_es_clients!
+      @mute_es_clients = true
+      self
+    end
+
+    # @return [Client]
+    def run
+      @running = true
+      wakeup = IO.for_fd(__wakeup_fd, autoclose: false)
+      while @running && !closed?
+        wakeup.wait_readable(0.1)
+        __drain.each { |message| dispatch(message) }
+        report_timeouts
+      end
+      self
+    ensure
+      @running = false
+    end
+
+    # @return [Thread]
+    def start
+      return @thread if @thread&.alive?
+
+      @thread = ::Thread.new { run }
+    end
+
+    # @return [Client]
+    def stop
+      @running = false
+      __wake unless closed?
+      @thread&.join unless @thread == ::Thread.current
+      self
+    end
+
+    # @return [nil]
+    def close
+      if @thread == ::Thread.current && @dispatching
+        @running = false
+        @close_after_dispatch = true
+        return
+      end
+
+      stop
+      __native_close
+    end
+
+    # @return [Hash]
+    def stats
+      __native_stats.merge(errors: @errors)
+    end
+
+    # Native values for path mute kinds.
+    # @api private
+    PATH_TYPES = { prefix: 0, literal: 1, target_prefix: 2, target_literal: 3 }.freeze
+    # Native values for mute inversion kinds.
+    # @api private
+    INVERSION_TYPES = { process: 0, path: 1, target_path: 2 }.freeze
+
+    # Mutes events for +path+.
+    def mute_path(path, type: :prefix) = change_path_mute(:mute, path, type, [])
+    # Removes a path mute.
+    def unmute_path(path, type: :prefix) = change_path_mute(:unmute, path, type, [])
+    # Mutes selected +events+ for +path+.
+    def mute_path_events(path, *events, type: :prefix) = change_path_mute(:mute, path, type, events)
+    # Removes selected event mutes for +path+.
+    def unmute_path_events(path, *events, type: :prefix) = change_path_mute(:unmute, path, type, events)
+
+    # Mutes a process by audit token or PID.
+    def mute_process(token = nil, pid: nil)
+      change_process_mute(:mute, token || (__audit_token_for_pid(pid) if pid), [])
+    end
+
+    # Removes a process mute by audit token or PID.
+    def unmute_process(token = nil, pid: nil)
+      change_process_mute(:unmute, token || (__audit_token_for_pid(pid) if pid), [])
+    end
+
+    # Mutes selected +events+ for a process.
+    def mute_process_events(token, *events) = change_process_mute(:mute, token, events)
+    # Removes selected event mutes for a process.
+    def unmute_process_events(token, *events) = change_process_mute(:unmute, token, events)
+    # Removes every source-path mute.
+    def unmute_all_paths = __unmute_all_paths(false)
+    # Removes every target-path mute.
+    def unmute_all_target_paths = __unmute_all_paths(true)
+    # Clears the Endpoint Security authorization cache.
+    def clear_cache = __clear_cache
+
+    # Inverts muting for +type+.
+    def invert_muting(type)
+      __invert_muting(INVERSION_TYPES.fetch(type.to_sym))
+    end
+
+    # @return [Boolean] whether muting for +type+ is inverted
+    def muting_inverted?(type)
+      __muting_inverted(INVERSION_TYPES.fetch(type.to_sym))
+    end
+
+    # @return [Array<Hash>] copied path mute entries
+    def muted_paths
+      __muted_paths.map { |item| item.merge(type: PATH_TYPES.key(item[:type]) || item[:type]) }
+    end
+
+    # @return [Array<Hash>] copied process mute entries
+    def muted_processes = __muted_processes
+
+    private
+
+    def supported_event?(event)
+      return false unless Availability.supported_event?(event)
+      return true if @probe == :off
+
+      Availability.probe_cache.fetch(event) { Availability.probe_cache[event] = probe_event(event) }
+    end
+
+    def probe_event(event)
+      value = EventType.value(event)
+      __subscribe([value])
+      __unsubscribe([value])
+      true
+    rescue SubscriptionError
+      false
+    end
+
+    def change_path_mute(action, path, type, events)
+      __mute_path(action, String(path), PATH_TYPES.fetch(type.to_sym), events.map { |event| EventType.value(event) })
+    end
+
+    def change_process_mute(action, token, events)
+      raise ArgumentError, "audit token or pid is required" unless token
+
+      __mute_process(action, token, events.map { |event| EventType.value(event) })
+    end
+
+    def dispatch(message)
+      @dispatching = true
+      if @mute_es_clients && message.process.es_client?
+        mute_process(message.process.audit_token)
+        return
+      end
+
+      handler = @handlers[message.event_type]
+      handler&.call(message)
+    rescue StandardError => e
+      @errors += 1
+      message.__respond_default! if message.auth? && !message.answered?
+      @error_handler&.call(e)
+    ensure
+      message.__auto_release!
+      @dispatching = false
+      if @close_after_dispatch
+        @close_after_dispatch = false
+        __native_close
+      end
+    end
+
+    def report_timeouts
+      count = __native_stats[:timeouts]
+      (count - @reported_timeouts).times { @timeout_handler&.call }
+      @reported_timeouts = count
+    end
+  end
+end

data/lib/endpoint_security/diagnostics.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module EndpointSecurity
+  # Turns native client creation results into actionable messages.
+  module Diagnostics
+    # Human-readable explanations keyed by native result.
+    EXPLANATIONS = {
+      success: "Endpoint Security client created successfully.",
+      err_invalid_argument: "Endpoint Security rejected an invalid argument; this is likely a binding bug.",
+      err_internal: "Endpoint Security reported an internal error; retry after checking system logs.",
+      err_not_entitled: "The host Ruby executable lacks the Endpoint Security client entitlement.",
+      err_not_permitted: "Grant Full Disk Access to the host Ruby executable.",
+      err_not_privileged: "Run the signed host Ruby executable as root.",
+      err_too_many_clients: "Close another Endpoint Security client and retry."
+    }.freeze
+
+    module_function
+
+    # @return [String] explanation for +result+
+    def explain(result)
+      EXPLANATIONS.fetch(result.respond_to?(:to_sym) ? result.to_sym : result) do
+        "Unknown es_new_client result: #{result.inspect}."
+      end
+    end
+  end
+end

data/lib/endpoint_security/doctor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module EndpointSecurity
+  # Reports whether a development host meets Endpoint Security requirements.
+  module Doctor
+    module_function
+
+    # Prints development host checks to +out+.
+    # @return [void]
+    def run(out: $stdout)
+      out.puts "Endpoint Security development host diagnosis"
+      check(out, "macOS 13+", Gem::Version.new(`sw_vers -productVersion`.strip) >= Gem::Version.new("13"))
+      check(out, "root", Process.euid.zero?)
+      check(out, "SIP disabled", command("csrutil", "status").include?("disabled"))
+      check(out, "AMFI development boot arg", command("nvram", "boot-args").include?("amfi_get_out_of_my_way=0x1"))
+      out.puts "WARNING: Disable SIP only on a dedicated development machine."
+    end
+
+    # @api private
+    # @return [String] captured command output
+    def command(*argv)
+      Open3.capture2e(*argv).first
+    rescue Errno::ENOENT
+      ""
+    end
+
+    # @api private
+    # @return [void]
+    def check(out, label, available)
+      out.puts format("%<label>-28s %<status>s", label: label, status: available ? "OK" : "MISSING")
+    end
+  end
+end

data/lib/endpoint_security/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module EndpointSecurity
+  # Base error for this library.
+  class Error < StandardError; end
+  # Endpoint Security client creation failed.
+  class ClientError < Error; end
+  # The host executable lacks the Endpoint Security entitlement.
+  class NotEntitledError < ClientError; end
+  # The host executable lacks Full Disk Access.
+  class NotPermittedError < ClientError; end
+  # The host process is not privileged.
+  class NotPrivilegedError < ClientError; end
+  # The system has reached its Endpoint Security client limit.
+  class TooManyClientsError < ClientError; end
+  # Endpoint Security rejected an invalid argument.
+  class InvalidArgumentError < ClientError; end
+  # Endpoint Security reported an internal error.
+  class InternalError < ClientError; end
+  # An event subscription operation failed.
+  class SubscriptionError < Error; end
+  # An event is unavailable on the running macOS version.
+  class UnsupportedEventError < SubscriptionError; end
+  # A mute operation failed.
+  class MuteError < Error; end
+  # Base error for message operations.
+  class MessageError < Error; end
+  # A lazy message view outlived its native message.
+  class MessageInvalidatedError < MessageError; end
+  # An authorization message has already been answered.
+  class AlreadyAnsweredError < MessageError; end
+  # A field is absent from this message version.
+  class FieldUnavailableError < MessageError; end
+  # Caching was requested for a non-cacheable event.
+  class NonCacheableEventError < MessageError; end
+  # The running macOS version lacks a requested native API.
+  class UnsupportedAPIError < Error; end
+  # A client created before fork was used by the child process.
+  class ForkedClientError < Error; end
+  # SDK metadata generation failed.
+  class CodegenError < Error; end
+end