fanotify 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ecffc5a3eb865058ceb950305ba888e3734dc665e660d951304db99c49b3fd05
+  data.tar.gz: 07fe42885faa0a6f290013ab1be64dbed9b4ebf9a39bbcbb35ae60b1e20dbcc4
+SHA512:
+  metadata.gz: 706d77daac3e9e4b96e85e41e006717b049b243d86641d73499baf883101644336a2df40c96ffc07b244e687f441a8781aaa96e5ffb50f70f5af7050cb6f2ee3
+  data.tar.gz: 3b1289e2e338479c385670b93a6740b77a61c4cf35c2752f79b7a170cb03a1492aaa73388283b500f75f3ebcd75cfe0dd33041eb933fffc854ea271d5e268fd8

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--readme README.md
+lib/**/*.rb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# Fanotify
+
+> [!WARNING]
+> Permission events block the process that opened a file until userspace responds.
+> A missing response or filesystem access from the handler can deadlock a process or
+> the machine. `Fanotify::Notifier#each_event` fails open and closes event descriptors,
+> but handlers must still follow the safety rules below.
+
+Ruby 3.2+ C bindings for Linux `fanotify(7)`. The gem supports ordinary
+notifications, permission decisions, FID/name records, PIDFD records, rename
+records, filesystem errors, and queue-overflow detection.
+
+## Requirements
+
+- Linux 5.1+ and a kernel built with `CONFIG_FANOTIFY`.
+- `CAP_SYS_ADMIN` for mount/filesystem marks and all permission events.
+- Linux 5.9+ for FID reporting, 5.13+ for unprivileged FID notification groups,
+  5.15+ for PIDFD reports, 5.17+ for rename/target FID reports, and 6.14+ for
+  experimental pre-access events.
+- A C compiler and Linux UAPI headers when installing the gem.
+
+`Fanotify.supported?` checks whether the syscall exists. It does not prove that the
+current process has permission for a particular class or mark.
+
+## Installation
+
+```ruby
+gem "fanotify"
+```
+
+Then run `bundle install`. The native extension is built during installation.
+
+## Notifications
+
+The high-level API uses the unprivileged-compatible FID/name mode:
+
+```ruby
+require "fanotify"
+
+Fanotify.watch("/data", events: %i[create delete modify]) do |event|
+  puts "#{event.mask.inspect} #{event.name}"
+end
+```
+
+Use `Notifier` for explicit classes and marks:
+
+```ruby
+Fanotify::Notifier.open(class: :notif, report: %i[fid dfid_name]) do |notifier|
+  notifier.mark(:add, "/data", events: %i[create delete event_on_child], only_dir: true)
+  notifier.each_event { |event| puts event.name }
+end
+```
+
+`Event#fid`, `#dfid`, `#old_dfid`, and `#new_dfid` are `Fanotify::FileHandle`
+values. Handles are comparable and printable as hex, but v1 does not open them with
+`open_by_handle_at(2)`.
+
+Linux 6.14 pre-access events expose the requested byte range as
+`Event#range_offset` and `Event#range_count`; see `examples/lazy_fetch.rb`.
+
+## Permission decisions
+
+Permission marks require `CAP_SYS_ADMIN`:
+
+```ruby
+Fanotify::Notifier.open(class: :content, response_timeout: 5.0) do |notifier|
+  notifier.exclude_self!
+  notifier.mark(:add, "/data", events: %i[open_perm event_on_child], only_dir: true)
+
+  notifier.each_event do |event|
+    event.deny! if event.path&.end_with?(".secret")
+    # No explicit decision means allow! when the block exits.
+  end
+end
+```
+
+The default behavior is fail-open:
+
+- A permission event without `allow!` or `deny!` is allowed after the block.
+- A handler exception allows the event before the same exception is raised again.
+- `defer!` registers an asynchronous decision. The default watchdog allows it after
+  five seconds; `response_timeout: nil` disables the deadline, while GC fail-open
+  cleanup remains active.
+- `pending_events` exposes live deferred events.
+- `close` allows an unanswered event before closing its descriptors.
+- If a response cannot be written, the notifier closes the whole group to release
+  every process still waiting on it.
+- `close` interrupts threads blocked in `read_events` with `Fanotify::Error`.
+
+`on_error: :deny` changes only the handler-exception decision. It is intentionally
+opt-in because application bugs then deny access.
+
+### Handler safety
+
+- Load code, resolve configuration, and open log destinations before adding a
+  permission mark. Do not call `require`, open logs, or lazily load files in a handler.
+- `exclude_self!` filters self-generated events already read by the notifier. It cannot
+  rescue a handler that blocks itself while opening another marked file on the same
+  thread.
+- Inspect `event.file`, which duplicates the kernel-opened descriptor and is closed
+  with the event. Do not reopen `event.path` for a security decision.
+- `event.path` comes from `/proc/self/fd/N` and is informational. Reopening it has a
+  TOCTOU race. Deleted paths retain the kernel's `" (deleted)"` suffix.
+- Keep handlers bounded. The kernel has no response timeout; the gem watchdog covers
+  only events explicitly deferred through this notifier.
+
+## Unsupported and restricted environments
+
+- macOS, BSD, and Windows: `require "fanotify"` succeeds and `supported?` is false;
+  constructing a notifier raises `Fanotify::UnsupportedError`.
+- Docker/Podman containers: permission events and mount/filesystem marks normally fail
+  without `CAP_SYS_ADMIN`; Docker Desktop also runs inside a Linux VM.
+- GitHub-hosted runners: unit tests work normally, but system tests need the included
+  virtme-ng VM runner.
+- WSL2: availability depends on its kernel configuration and the capabilities granted
+  to the process.
+- Older Linux kernels accept only the flags available in that kernel; unsupported new
+  flag combinations fail with the kernel's `Errno::*` exception.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test:unit
+bundle exec rake rbs
+sudo bundle exec rake test:system  # Linux with CAP_SYS_ADMIN
+```
+
+The system suite has hard timeouts and covers notification, allow/deny, exception
+fail-open, deferred timeout, FID names, unprivileged mode, queue overflow, and 10,000
+permission events without fd growth.
+
+Run the same suite in a kernel VM with:
+
+```sh
+tools/vm/run.sh              # Linux 6.12
+KVER=6.1 tools/vm/run.sh
+```
+
+`bundle exec rake gen:constants` regenerates the Ruby constant bindings. Values are
+still resolved from the target system's UAPI headers at extension build time.
+
+Reference throughput for 10,000 distinct `FAN_OPEN` FID events was 266,374 events/s
+on Ruby 3.4.10, Linux 6.8 arm64 in a Docker Desktop VM. Run
+`bundle exec ruby benchmark/events.rb` on the deployment host; handler work and event
+shape dominate real throughput.
+
+See `examples/` for audit logging, malware scanning, and experimental pre-access programs.
+
+## License
+
+[MIT](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+require "rbconfig"
+require "rspec/core/rake_task"
+require "yard"
+
+Rake::ExtensionTask.new("fanotify") do |extension|
+  extension.lib_dir = "lib/fanotify"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+task spec: :compile
+YARD::Rake::YardocTask.new
+
+namespace :test do
+  RSpec::Core::RakeTask.new(:unit) do |task|
+    task.pattern = "spec/**/*_spec.rb"
+    task.exclude_pattern = "spec/system/**/*_spec.rb"
+  end
+
+  RSpec::Core::RakeTask.new(:system) do |task|
+    task.pattern = "spec/system/**/*_spec.rb"
+  end
+
+  task unit: :compile
+  task system: :compile
+end
+
+namespace :gen do
+  desc "Regenerate the C constant bindings"
+  task :constants do
+    sh RbConfig.ruby, "tools/generate_constants.rb"
+  end
+end
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "bundle", "exec", "rbs", "-I", "sig", "validate"
+end
+
+task default: "test:unit"

data/benchmark/events.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "fanotify"
+require "tmpdir"
+
+count = Integer(ENV.fetch("EVENTS", "10000"))
+
+Dir.mktmpdir("fanotify-benchmark-") do |directory|
+  paths = Array.new(count) do |index|
+    File.join(directory, index.to_s).tap { |path| File.write(path, "") }
+  end
+
+  Fanotify::Notifier.open(class: :notif, report: [:fid]) do |notifier|
+    notifier.mark(:add, directory, events: %i[open event_on_child], only_dir: true)
+    child = fork { paths.each { |path| File.open(path, &:read) } }
+    received = 0
+    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    until received >= count
+      events = notifier.read_events
+      received += events.length
+      events.each(&:close)
+    end
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+    Process.wait(child)
+    puts format("%d events in %.3fs (%.0f events/s)", received, elapsed, received / elapsed)
+  end
+end

data/examples/audit_logger.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "fanotify"
+
+path = ARGV.fetch(0) { abort "usage: #{$PROGRAM_NAME} PATH [LOG]" }
+log = File.open(ARGV[1] || "/dev/stdout", "a")
+log.sync = true
+
+Fanotify::Notifier.open(class: :notif, report: %i[fid dfid_name]) do |notifier|
+  notifier.mark(:add, path, events: %i[open create delete modify event_on_child], only_dir: true)
+  notifier.each_event do |event|
+    log.puts "pid=#{event.pid} events=#{event.mask.join(',')} name=#{event.name || '-'}"
+  end
+end

data/examples/lazy_fetch.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "fanotify"
+
+path = ARGV.fetch(0) { abort "usage: sudo #{$PROGRAM_NAME} FILE" }
+payload = ENV.fetch("LAZY_PAYLOAD", "materialized by fanotify\n").b
+abort "LAZY_PAYLOAD must not be empty" if payload.empty?
+
+Fanotify::Notifier.open(
+  class: :pre_content,
+  event_flags: %i[rdwr largefile cloexec],
+  response_timeout: 5.0
+) do |notifier|
+  notifier.mark(:add, path, events: [:pre_access])
+  notifier.each_event do |event|
+    file = event.file
+    next unless file&.stat&.zero?
+
+    remaining = event.range_count || payload.bytesize
+    file.seek(event.range_offset || 0)
+    while remaining.positive?
+      chunk = payload.byteslice(0, [remaining, payload.bytesize].min)
+      file.write(chunk)
+      remaining -= chunk.bytesize
+    end
+    file.flush
+    event.allow!
+  end
+end

data/examples/malware_scan.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "fanotify"
+
+path = ARGV.fetch(0) { abort "usage: sudo #{$PROGRAM_NAME} PATH" }
+signature = ENV.fetch("MALWARE_SIGNATURE", "EICAR-STANDARD-ANTIVIRUS-TEST-FILE").b
+log = File.open("/dev/stderr", "w")
+log.sync = true
+
+Fanotify::Notifier.open(class: :content, response_timeout: 5.0) do |notifier|
+  notifier.exclude_self!
+  notifier.mark(:add, path, events: %i[open_perm event_on_child], only_dir: true)
+  notifier.each_event do |event|
+    sample = event.file&.read(1024 * 1024)
+    next unless sample&.include?(signature)
+
+    log.puts "denied pid=#{event.pid} path=#{event.path}"
+    event.deny!
+  end
+end

data/ext/fanotify/compat.h

@@ -0,0 +1,235 @@
+#ifndef FANOTIFY_COMPAT_H
+#define FANOTIFY_COMPAT_H
+
+#include <fcntl.h>
+#include <stdint.h>
+
+#ifdef _WIN32
+#include <io.h>
+#define close _close
+#define read _read
+#define write _write
+#endif
+
+#ifndef O_LARGEFILE
+#define O_LARGEFILE 0
+#endif
+#ifndef O_CLOEXEC
+#define O_CLOEXEC 0
+#endif
+#ifndef O_NONBLOCK
+#define O_NONBLOCK 0
+#endif
+#ifndef AT_FDCWD
+#define AT_FDCWD -100
+#endif
+
+#ifdef __linux__
+#include <linux/fanotify.h>
+#include <sys/syscall.h>
+#else
+struct fanotify_event_metadata {
+    uint32_t event_len;
+    uint8_t vers;
+    uint8_t reserved;
+    uint16_t metadata_len;
+    uint64_t mask;
+    int32_t fd;
+    int32_t pid;
+};
+struct fanotify_response { int32_t fd; uint32_t response; };
+#endif
+
+#ifndef FAN_ACCESS
+#define FAN_ACCESS 0x00000001
+#endif
+#ifndef FAN_MODIFY
+#define FAN_MODIFY 0x00000002
+#endif
+#ifndef FAN_ATTRIB
+#define FAN_ATTRIB 0x00000004
+#endif
+#ifndef FAN_CLOSE_WRITE
+#define FAN_CLOSE_WRITE 0x00000008
+#endif
+#ifndef FAN_CLOSE_NOWRITE
+#define FAN_CLOSE_NOWRITE 0x00000010
+#endif
+#ifndef FAN_OPEN
+#define FAN_OPEN 0x00000020
+#endif
+#ifndef FAN_MOVED_FROM
+#define FAN_MOVED_FROM 0x00000040
+#endif
+#ifndef FAN_MOVED_TO
+#define FAN_MOVED_TO 0x00000080
+#endif
+#ifndef FAN_CREATE
+#define FAN_CREATE 0x00000100
+#endif
+#ifndef FAN_DELETE
+#define FAN_DELETE 0x00000200
+#endif
+#ifndef FAN_DELETE_SELF
+#define FAN_DELETE_SELF 0x00000400
+#endif
+#ifndef FAN_MOVE_SELF
+#define FAN_MOVE_SELF 0x00000800
+#endif
+#ifndef FAN_OPEN_EXEC
+#define FAN_OPEN_EXEC 0x00001000
+#endif
+#ifndef FAN_Q_OVERFLOW
+#define FAN_Q_OVERFLOW 0x00004000
+#endif
+#ifndef FAN_FS_ERROR
+#define FAN_FS_ERROR 0x00008000
+#endif
+#ifndef FAN_OPEN_PERM
+#define FAN_OPEN_PERM 0x00010000
+#endif
+#ifndef FAN_ACCESS_PERM
+#define FAN_ACCESS_PERM 0x00020000
+#endif
+#ifndef FAN_OPEN_EXEC_PERM
+#define FAN_OPEN_EXEC_PERM 0x00040000
+#endif
+#ifndef FAN_PRE_ACCESS
+#define FAN_PRE_ACCESS 0x00100000
+#endif
+#ifndef FAN_EVENT_ON_CHILD
+#define FAN_EVENT_ON_CHILD 0x08000000
+#endif
+#ifndef FAN_RENAME
+#define FAN_RENAME 0x10000000
+#endif
+#ifndef FAN_ONDIR
+#define FAN_ONDIR 0x40000000
+#endif
+
+#ifndef FAN_CLOEXEC
+#define FAN_CLOEXEC 0x00000001
+#endif
+#ifndef FAN_NONBLOCK
+#define FAN_NONBLOCK 0x00000002
+#endif
+#ifndef FAN_CLASS_NOTIF
+#define FAN_CLASS_NOTIF 0x00000000
+#endif
+#ifndef FAN_CLASS_CONTENT
+#define FAN_CLASS_CONTENT 0x00000004
+#endif
+#ifndef FAN_CLASS_PRE_CONTENT
+#define FAN_CLASS_PRE_CONTENT 0x00000008
+#endif
+#ifndef FAN_UNLIMITED_QUEUE
+#define FAN_UNLIMITED_QUEUE 0x00000010
+#endif
+#ifndef FAN_UNLIMITED_MARKS
+#define FAN_UNLIMITED_MARKS 0x00000020
+#endif
+#ifndef FAN_ENABLE_AUDIT
+#define FAN_ENABLE_AUDIT 0x00000040
+#endif
+#ifndef FAN_REPORT_PIDFD
+#define FAN_REPORT_PIDFD 0x00000080
+#endif
+#ifndef FAN_REPORT_TID
+#define FAN_REPORT_TID 0x00000100
+#endif
+#ifndef FAN_REPORT_FID
+#define FAN_REPORT_FID 0x00000200
+#endif
+#ifndef FAN_REPORT_DIR_FID
+#define FAN_REPORT_DIR_FID 0x00000400
+#endif
+#ifndef FAN_REPORT_NAME
+#define FAN_REPORT_NAME 0x00000800
+#endif
+#ifndef FAN_REPORT_DFID_NAME
+#define FAN_REPORT_DFID_NAME (FAN_REPORT_DIR_FID | FAN_REPORT_NAME)
+#endif
+#ifndef FAN_REPORT_TARGET_FID
+#define FAN_REPORT_TARGET_FID 0x00001000
+#endif
+
+#ifndef FAN_MARK_ADD
+#define FAN_MARK_ADD 0x00000001
+#endif
+#ifndef FAN_MARK_REMOVE
+#define FAN_MARK_REMOVE 0x00000002
+#endif
+#ifndef FAN_MARK_DONT_FOLLOW
+#define FAN_MARK_DONT_FOLLOW 0x00000004
+#endif
+#ifndef FAN_MARK_ONLYDIR
+#define FAN_MARK_ONLYDIR 0x00000008
+#endif
+#ifndef FAN_MARK_MOUNT
+#define FAN_MARK_MOUNT 0x00000010
+#endif
+#ifndef FAN_MARK_IGNORED_MASK
+#define FAN_MARK_IGNORED_MASK 0x00000020
+#endif
+#ifndef FAN_MARK_IGNORED_SURV_MODIFY
+#define FAN_MARK_IGNORED_SURV_MODIFY 0x00000040
+#endif
+#ifndef FAN_MARK_FLUSH
+#define FAN_MARK_FLUSH 0x00000080
+#endif
+#ifndef FAN_MARK_FILESYSTEM
+#define FAN_MARK_FILESYSTEM 0x00000100
+#endif
+#ifndef FAN_MARK_EVICTABLE
+#define FAN_MARK_EVICTABLE 0x00000200
+#endif
+#ifndef FAN_MARK_IGNORE
+#define FAN_MARK_IGNORE 0x00000400
+#endif
+#ifndef FAN_MARK_INODE
+#define FAN_MARK_INODE 0x00000000
+#endif
+
+#ifndef FAN_ALLOW
+#define FAN_ALLOW 0x01
+#endif
+#ifndef FAN_DENY
+#define FAN_DENY 0x02
+#endif
+#ifndef FAN_AUDIT
+#define FAN_AUDIT 0x10
+#endif
+#ifndef FANOTIFY_METADATA_VERSION
+#define FANOTIFY_METADATA_VERSION 3
+#endif
+#ifndef FAN_NOFD
+#define FAN_NOFD -1
+#endif
+
+#ifndef FAN_EVENT_INFO_TYPE_FID
+#define FAN_EVENT_INFO_TYPE_FID 1
+struct fanotify_event_info_header { uint8_t info_type; uint8_t pad; uint16_t len; };
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_DFID_NAME
+#define FAN_EVENT_INFO_TYPE_DFID_NAME 2
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_DFID
+#define FAN_EVENT_INFO_TYPE_DFID 3
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_PIDFD
+#define FAN_EVENT_INFO_TYPE_PIDFD 4
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_ERROR
+#define FAN_EVENT_INFO_TYPE_ERROR 5
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_RANGE
+#define FAN_EVENT_INFO_TYPE_RANGE 6
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
+#define FAN_EVENT_INFO_TYPE_OLD_DFID_NAME 10
+#endif
+#ifndef FAN_EVENT_INFO_TYPE_NEW_DFID_NAME
+#define FAN_EVENT_INFO_TYPE_NEW_DFID_NAME 12
+#endif
+
+#endif

data/ext/fanotify/constants.c

@@ -0,0 +1,12 @@
+/* Generated by tools/generate_constants.rb. */
+#include "ruby.h"
+#include "compat.h"
+
+void fanotify_define_constants(VALUE module)
+{
+#define X(name) rb_define_const(module, #name, ULL2NUM((unsigned long long)(name)));
+#include "../../tools/constants.def"
+#undef X
+    rb_define_const(module, "FAN_NOFD", INT2NUM(FAN_NOFD));
+    rb_define_const(module, "AT_FDCWD", INT2NUM(AT_FDCWD));
+}

data/ext/fanotify/extconf.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+have_header("linux/fanotify.h")
+have_const("SYS_fanotify_init", "sys/syscall.h")
+have_func("syscall", "unistd.h")
+have_func("rb_thread_call_without_gvl", "ruby/thread.h")
+create_header
+create_makefile("fanotify/fanotify")