vanken 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ff6f270de34fbee27bb93839749a5105ece2667ef59e3281c28e37d5dee782a
-  data.tar.gz: cfb0118a6e6c0b1b6a026ca8254e58b2e20f260b11e75bedbbce21a6aa47755b
+  metadata.gz: 9db141f2b218a50e8cb5d228b14b35d6ff728e3fc48fbd6abddf18e56f903284
+  data.tar.gz: 65a40d15a931d59b2e618aab1cfbc9b8fd97bea13d0593b8b1938d611ba5bad2
 SHA512:
-  metadata.gz: d7913b548c7ce8fd8bb0531542b70d633c1c06525bb2be762230661ec2d2691a233c81116376ab3c6fa0857db76c8796c4e585271431fd6025af7c130fc55fab
-  data.tar.gz: 1de08c7960be93a43239e88564f3267622406597909a7bd18d7ca59f5bf77dab29526da4b2852405cf711a2066342bc332bad70121ad9f67bead285eb9b6812b
+  metadata.gz: 5b7de2090ab6735713dcb9855d67103339b2dfe75a94b51486b9d0bcb797e0b3c8286fcf3b531f50ea8375eaf732721d2124ffdcb32fd0940a69f03b6893c4ab
+  data.tar.gz: 3f4600b9db5305b86b35fa821f6dee78bdd323458b50359043f4e252481ba16d6414bfbfd8c8a22e8cec1566280d7933dbbc0df8612015ce4ea07b277a4ece43

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.0
+
+- Add `vanken-setup-permissions` to install Linux capture wrappers and polkit or sudoers policies, and configure macOS BPF access through a LaunchDaemon. Installation validates privileged runtime and destination ownership before granting access.
+- Include the Linux desktop entry, capture policies, fixed-path wrappers, and macOS setup files in the gem and downloadable GitHub release assets.
+
+Requires Ruby 3.3 or newer. Live capture supports Linux and macOS; Windows supports file inspection. See [capture permissions](https://github.com/ydah/vanken/blob/main/packaging/README.md).
+
+Live acquisition and redraw latency on slower systems retain the [documented performance limits](https://github.com/ydah/vanken/blob/main/docs/performance.md).
+
 ## 0.2.0
 
 - Add editable packet coloring, four search modes, marks, ignored packets, time references, and conversation navigation.

data/README.md

@@ -67,6 +67,8 @@ bundle exec exe/vanken-capture --check --interface lo
 
 Direct acquisition works when the account already has permission. Privileged launching requires a root-owned installation with a fixed interpreter and dependencies; see [capture helper setup](packaging/README.md). Run the desktop application as a regular user.
 
+The gem includes `vanken-setup-permissions` for administrator installation of Linux capture permissions and the macOS BPF LaunchDaemon. Review the platform-specific setup guide and the command's `--dry-run` output first. GitHub releases also include the permission policies, desktop entry, wrappers, and macOS script in a packaging archive.
+
 ## Command line
 
 ```sh

data/docs/performance.md

@@ -121,3 +121,46 @@ On 2026-10-02, Ruby 4.0.6 with YJIT on arm64 Darwin compared the same 20,000 com
 A separate one-million-packet run of the production document measured 0.5529 s for the existing fast filter, 6.2598 s for the four-worker `ip.ttl == 64` scan, and 2.7721 s for the four-worker address/port cBPF scan. Each matched all one million packets. Analysis took 115.6605 s (8,646 packets/s), with 67.2 B/frame retained parent heap before filtering and 81.08 B/frame after the worker scan. This run overlapped integration and UI tests and is not an isolated comparison with the earlier analysis-throughput result. RSS sampling was unavailable and is recorded as null; these heap figures do not establish the RSS target.
 
 The I/O graph check seeds actual frame metadata, packed columns, and annotations for 200,000 TCP frames, then times two series at each supported interval. It excludes packet parsing. The observed interval rebuilds took 0.30–0.33 s, each below the one-second target, with every packet counted in both series. Run `bundle exec ruby --yjit script/analysis-performance.rb` to repeat it. Nightly validation retains the one-million-packet benchmark, evaluator comparison, graph timings, and fuzz results as workflow artifacts.
+
+## Release 0.2 and 0.3 verification with public Zaniah 0.12.4
+
+The [final nightly run](https://github.com/ydah/vanken/actions/runs/36999466662) tested commit `6d05e2a` with Ruby 3.4.10, YJIT, public redhound 2.0.0.rc2, and public Zaniah 0.12.4 on the shared x86_64 Linux runner. The receiver, complete one-million-packet analysis, all filters, graph accounting, and 5,000 deterministic fuzz cases passed their functional checks. Commit `2169b6a` adds the administrator installer and packaging without changing this analysis or rendering code.
+
+| Measurement | Result | Target |
+| --- | ---: | ---: |
+| Receiver, 1,000,000 frames | 181,777 frames/s | ≥ 100,000 |
+| Ingest and analyze, 1,000,000 frames | 4,073 frames/s; 245.5186 s | ≥ 15,000; missed |
+| Parent / combined / after-filter RSS increment | 80.26 / 87.48 / 91.06 B per frame | ≤ 200 |
+| Fast / four-worker slow filter | 1.9499 / 22.9614 s | ≤ 3 / 60 s |
+| Four-worker address/port cBPF filter | 7.1322 s; 1,000,000 matches | Reported separately |
+| Static full application, total / scene render p95 | 73.154 / 71.903 ms | Scene ≤ 33 ms; missed |
+| Growing full application, total / scene render p95 | 44.370 / 42.490 ms | Scene ≤ 33 ms; missed |
+
+The growing full-application source produced only 427.6 frames/s during sampling, so that measurement does not establish responsiveness at 5,000 frames/s. The isolated virtual-table ingestion measurement similarly does not replace the complete application or live capture. Job success does not mean all numeric targets passed.
+
+The same nightly run compared VDF and cBPF over the same 20,000 packets, with three samples per evaluator. Median times were 1.239493 s and 0.055858 s respectively, a 22.19-fold improvement, with identical match counts. Two-series I/O graph rebuilds for 200,000 frames took 1.024516, 1.011629, 1.005382, 0.996721, and 0.996433 s at intervals 0.01, 0.1, 1, 10, and 60 s. The three shortest intervals narrowly exceeded the one-second target.
+
+On the Mac with Ruby 4.0.6, YJIT, and public Zaniah 0.12.4, the final 100,000,032-byte file check displayed its first verified row in 645.209 ms. Twenty distinct selections had p50 26.660 ms, p95 35.778 ms, and maximum 51.223 ms. The first-row target passed; the every-selection 50 ms target failed on the first selection. These are single-run headless production-window measurements with the same exclusions described above.
+
+A native Mac run with 120 samples verified opening, selection, filtering, and all 25,256 captured frames. Scene p95 was 28.804 ms and total native tick p95 was 47.850 ms. During sampling, the source delivered 19,453 frames in 4.40697 s, or 4,414.14 frames/s. The scene result meets 33 ms at that observed rate, but does not establish the requested 5,000 frames/s target.
+
+The [final five-minute Linux capture run](https://github.com/ydah/vanken/actions/runs/36999897569), at `2169b6a`, used Ruby 3.4.11 with YJIT and the public dependencies above. The actual administrator command installed 74 root-owned files, and capture-boundary tests verified the installation before running the UI with UID/EUID 1000. A real PTY additionally passed file opening, packet selection, filtering, the command palette, capture options, actual capture start/stop, and quit.
+
+The independent sender delivered 1,500,000 frames over 300.000066 s at 4,999.9989 frames/s. Kernel received, helper captured, durable, and final analyzed counts all equaled 1,500,000; drops, interface drops, and freezes were zero. Analysis drained 208.956 s after traffic ended, with a maximum sampled backlog of 578,656 frames. This establishes capture integrity and sender pacing while retaining the analysis-throughput limitation.
+
+During actual traffic, 2,492 frames rendered and 2,395 showed analyzed-row growth. Scene p95 was 78.807 ms and total render p95 was 81.711 ms, exceeding the 33 ms scene target. The file check in the same run displayed its first row in 788.282 ms, passing one second; selection p95 was 104.404 ms and maximum 111.676 ms, exceeding 50 ms. The earlier measurements remain above for comparison; shared-runner results do not establish a controlled before/after speedup.
+
+### Same-host analysis regression comparison
+
+The old Linux analysis time of 206.2345 s and the latest 245.5186 s came from different shared VMs. A separate same-host comparison checks the release procedure's 15% regression threshold without treating those environments as identical.
+
+The initial `26b3e7b` source and current `2169b6a` source were archived and run alternately on the same Mac. Both used the current public dependency lockfile, Ruby 4.0.6 with YJIT, a fresh Ruby process and analyzer child, the identical 58-byte UDP fixture and Enumerator, and a 50-frame warm-up. Each timed `Document.ingest(...).wait` with `process_analysis: true` over 100,000 frames. Initialization, warm-up, cleanup, kernel acquisition, and UI were excluded; no other local tests ran concurrently.
+
+| Sample | Initial source, seconds | Current source, seconds |
+| --- | ---: | ---: |
+| 1 | 11.307215 | 11.508561 |
+| 2 | 11.623641 | 12.657844 |
+| 3 | 12.123842 | 12.085011 |
+| Median | 11.623641 | 12.085011 |
+
+Median elapsed time increased 3.97%; median throughput changed from 8,603.16 to 8,274.71 frames/s, a 3.82% decrease. The 15% threshold was not exceeded for this workload. All six runs verified exactly 100,000 durable and analyzed frames, UDP decoding, no document error, and analyzer-child cleanup. This comparison does not explain the separate shared-VM Linux timing difference or establish the 15,000 frames/s target.

data/exe/vanken-setup-permissions

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vanken/capture/permission_setup"
+
+exit Vanken::Capture::PermissionSetup.run(ARGV)

data/lib/vanken/capture/permission_setup.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "etc"
+require "shellwords"
+require "tempfile"
+require "open3"
+
+module Vanken
+  module Capture
+    class PermissionSetup
+      PREFIX = "/usr/local/libexec/vanken"
+      SOURCE = File.expand_path("../../..", __dir__)
+
+      def self.run(argv, stdout: $stdout, stderr: $stderr)
+        options = {}
+        dry_run = false
+        parser = OptionParser.new do |flags|
+          flags.banner = "Usage: vanken-setup-permissions [--dry-run] [--ruby PATH --gem-home PATH] [--policy polkit|sudoers] [--group GROUP]"
+          flags.on("--platform VALUE", %w[linux darwin]) { |value| options[:platform] = value.to_sym }
+          flags.on("--ruby PATH") { |value| options[:ruby] = value }
+          flags.on("--gem-home PATH") { |value| options[:gem_home] = value }
+          flags.on("--policy VALUE", %w[polkit sudoers]) { |value| options[:policy] = value.to_sym }
+          flags.on("--group GROUP") { |value| options[:group] = value }
+          flags.on("--root DIRECTORY", "Stage files without activating system permissions") { |value| options[:root] = value }
+          flags.on("--dry-run") { dry_run = true }
+          flags.on("-h", "--help") { stdout.puts(flags); return 0 }
+        end
+        known = %w[--platform --ruby --gem-home --policy --group --root --dry-run --help]
+        argv.each do |value|
+          raise ArgumentError, "unknown option: #{value}" if value.start_with?("--") && !known.include?(value.split("=", 2).first)
+        end
+        remaining = parser.parse(argv.dup)
+        raise ArgumentError, "unexpected arguments: #{remaining.join(' ')}" unless remaining.empty?
+        setup = new(**options)
+        setup.install unless dry_run
+        stdout.puts(JSON.pretty_generate(platform: setup.platform, dry_run: dry_run, staged: setup.staged?,
+          files: setup.plan.keys, next_steps: setup.next_steps))
+        0
+      rescue ArgumentError, OptionParser::ParseError => error
+        stderr.puts(error.message)
+        2
+      rescue SystemCallError, IOError => error
+        stderr.puts(error.message)
+        1
+      end
+
+      attr_reader :platform
+
+      def initialize(platform: nil,
+                     ruby: nil, gem_home: nil, policy: :polkit, group: "vanken", root: "/")
+        platform ||= RUBY_PLATFORM.include?("darwin") ? :darwin : (RUBY_PLATFORM.include?("linux") ? :linux : :unsupported)
+        @platform, @ruby, @gem_home, @policy, @group = platform.to_sym, ruby, gem_home, policy.to_sym, group
+        raise ArgumentError, "unsupported platform" unless %i[linux darwin].include?(@platform)
+        raise ArgumentError, "invalid policy" unless %i[polkit sudoers].include?(@policy)
+        raise ArgumentError, "invalid capture group" unless @group.match?(/\A[a-z_][a-z0-9_-]{0,31}\z/)
+        if @platform == :linux
+          [@ruby, @gem_home].each do |path|
+            raise ArgumentError, "Linux setup requires absolute --ruby and --gem-home paths" unless path&.start_with?("/") && !path.include?("\n")
+          end
+        end
+        raise ArgumentError, "staging root must be an existing absolute directory" unless root.start_with?("/") && File.directory?(root) && !File.symlink?(root)
+        @root = File.realpath(root)
+      end
+
+      def staged? = @root != "/"
+
+      def plan
+        if @platform == :darwin
+          return {"#{PREFIX}/chmod-bpf" => asset("macos/chmod-bpf", mode: 0o755),
+                  "/Library/LaunchDaemons/org.vanken.chmod-bpf.plist" => asset("macos/org.vanken.chmod-bpf.plist")}
+        end
+        files = {"#{PREFIX}/vanken-capture" => asset("linux/vanken-capture.wrapper", mode: 0o755),
+                 "#{PREFIX}/helper" => {contents: File.binread(File.join(SOURCE, "exe/vanken-capture")), mode: 0o755},
+                 "/usr/share/applications/vanken.desktop" => asset("linux/vanken.desktop")}
+        if @policy == :polkit
+          files["/usr/share/polkit-1/actions/org.vanken.capture.policy"] = asset("linux/org.vanken.capture.policy")
+        else
+          files["/etc/sudoers.d/vanken"] = asset("linux/vanken.sudoers", mode: 0o440)
+        end
+        Dir.glob(File.join(SOURCE, "lib", "**", "*"), File::FNM_DOTMATCH).each do |path|
+          raise ArgumentError, "source library contains a symlink" if File.symlink?(path)
+          next if File.directory?(path)
+          files["#{PREFIX}/#{path.delete_prefix("#{SOURCE}/")}"] = {contents: File.binread(path), mode: 0o644}
+        end
+        files
+      end
+
+      def install
+        raise ArgumentError, "system installation requires root; use --dry-run or --root for review" unless staged? || Process.euid.zero?
+        raise ArgumentError, "use --root or --dry-run to prepare files for another platform" unless staged? || RUBY_PLATFORM.include?(@platform.to_s)
+        validate_runtime! if @platform == :linux && !staged?
+        validate_group! if @platform == :darwin || @policy == :sudoers
+        plan.each do |absolute, item|
+          destination = File.join(@root, absolute.delete_prefix("/"))
+          secure_directory!(File.dirname(destination))
+          safe_entry!(destination) if File.exist?(destination) || File.symlink?(destination)
+          Tempfile.create([".vanken-", ".tmp"], File.dirname(destination)) do |file|
+            file.binmode
+            file.write(item[:contents])
+            file.chmod(item[:mode])
+            file.flush
+            validate_sudoers!(file.path) if absolute == "/etc/sudoers.d/vanken" && !staged?
+            File.rename(file.path, destination)
+          end
+        end
+        self
+      end
+
+      def validate_runtime!
+        trusted_tree!(@ruby)
+        raise ArgumentError, "Ruby interpreter must be executable" unless File.file?(@ruby) && File.executable?(@ruby)
+        runtime_prefix = File.dirname(File.dirname(File.realpath(@ruby)))
+        trusted_tree!(runtime_prefix) unless ["/", "/usr"].include?(runtime_prefix)
+        paths, status = Open3.capture2({"PATH" => "/usr/bin:/bin"}, @ruby, "--disable-gems", "-e", "$LOAD_PATH.each { |path| puts path }", unsetenv_others: true, chdir: "/")
+        raise ArgumentError, "could not inspect the Ruby runtime" unless status.success?
+        paths.each_line { |path| trusted_tree!(path.strip) }
+        trusted_tree!(@gem_home)
+        raise ArgumentError, "gem home must be a directory" unless File.directory?(@gem_home)
+        trusted_tree!(SOURCE)
+        self
+      end
+
+      def validate_group!
+        Etc.getgrnam(@group)
+      rescue ArgumentError
+        raise ArgumentError, "create the #{@group} capture group and add the intended users before installing"
+      end
+
+      def next_steps
+        if @platform == :darwin
+          ["sudo launchctl bootstrap system /Library/LaunchDaemons/org.vanken.chmod-bpf.plist",
+           "Log out and log in after changing group membership, then run vanken-capture --check --interface lo0."]
+        else
+          ["Run vanken-capture --check --interface IF as a normal user, then start Vanken."]
+        end
+      end
+
+      private
+
+      def asset(relative, mode: 0o644)
+        contents = File.binread(File.join(SOURCE, "packaging", relative)).gsub("VANKEN_GROUP", @group)
+        contents = contents.gsub("VANKEN_RUBY", Shellwords.escape(@ruby.to_s)).gsub("VANKEN_GEM_HOME", Shellwords.escape(@gem_home.to_s))
+        {contents: contents, mode: mode}
+      end
+
+      def trusted_tree!(path, visited = {})
+        resolved = trusted_path!(path)
+        return if visited[resolved]
+        visited[resolved] = true
+        return unless File.directory?(resolved)
+        Dir.children(resolved).each { |name| trusted_tree!(File.join(resolved, name), visited) }
+      rescue SystemCallError => error
+        raise ArgumentError, "cannot verify root-owned privileged path: #{error.message}"
+      end
+
+      def trusted_path!(path)
+        resolved = File.realpath(path)
+        current = path
+        loop do
+          stat = File.lstat(current)
+          unless stat.uid.zero? && (stat.symlink? || (stat.mode & 0o022).zero?) && (stat.file? || stat.directory? || stat.symlink?)
+            raise ArgumentError, "privileged paths must be root-owned without group or other write access"
+          end
+          if stat.symlink?
+            target = File.readlink(current)
+            trusted_path!(target.start_with?("/") ? target : File.join(File.dirname(current), target))
+          end
+          break if current == "/"
+          current = File.dirname(current)
+        end
+        trusted_path!(resolved) if path != resolved
+        resolved
+      end
+
+      def safe_entry!(path)
+        stat = File.lstat(path)
+        raise ArgumentError, "unsafe installation path or symlink: #{path}" unless stat.uid == Process.euid && (stat.mode & 0o022).zero? && (stat.file? || stat.directory?)
+      end
+
+      def secure_directory!(path)
+        safe_entry!(@root)
+        current = @root
+        path.delete_prefix(@root).split("/").reject(&:empty?).each do |part|
+          current = File.join(current, part)
+          Dir.mkdir(current, 0o755) unless File.exist?(current) || File.symlink?(current)
+          safe_entry!(current)
+          raise ArgumentError, "installation parent is not a directory" unless File.directory?(current)
+        end
+      end
+
+      def validate_sudoers!(path)
+        executable = %w[/usr/sbin/visudo /sbin/visudo].find { |candidate| File.executable?(candidate) }
+        raise ArgumentError, "visudo is required to install sudoers permissions" unless executable
+        _, errors, status = Open3.capture3(executable, "-cf", path)
+        raise ArgumentError, "invalid sudoers configuration: #{errors}" unless status.success?
+      end
+    end
+  end
+end

data/lib/vanken/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vanken
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/packaging/README.md

@@ -1,5 +1,45 @@
 # Live capture permissions
 
+`vanken-setup-permissions` installs the files shipped in `packaging/linux/` or `packaging/macos/`. Review the macOS plan first:
+
+```sh
+vanken-setup-permissions --platform darwin --dry-run
+```
+
+On Linux, provide the canonical absolute paths of a root-owned Ruby 3.3 or newer runtime and its isolated gem home:
+
+```sh
+vanken-setup-permissions --platform linux --dry-run \
+  --ruby /opt/vanken-ruby/bin/ruby --gem-home /opt/vanken-ruby/gems
+```
+
+The following administrator installation assumes Ruby is already installed under `/opt/vanken-ruby`, with root-owned runtime files that are not writable by group or other users. Install Vanken into the isolated root-owned gem home, then run its packaged setup command with that same interpreter:
+
+```sh
+sudo /usr/bin/env -i PATH=/usr/bin:/bin GEM_HOME=/opt/vanken-ruby/gems GEM_PATH=/opt/vanken-ruby/gems \
+  /opt/vanken-ruby/bin/ruby /opt/vanken-ruby/bin/gem install vanken --version 0.3.0 --no-document
+sudo /usr/bin/env -i PATH=/usr/bin:/bin GEM_HOME=/opt/vanken-ruby/gems GEM_PATH=/opt/vanken-ruby/gems \
+  /opt/vanken-ruby/bin/ruby /opt/vanken-ruby/gems/bin/vanken-setup-permissions \
+  --ruby /opt/vanken-ruby/bin/ruby --gem-home /opt/vanken-ruby/gems --policy polkit
+```
+
+The installer checks the interpreter, its library paths, runtime tree, gem home, and source tree for root ownership and writable paths before copying anything. Root-owned runtime library aliases are allowed only when every link, target, and parent path passes the same checks. The wrapper clears all inherited environment variables, fixes the interpreter and gem paths, and runs only `/usr/local/libexec/vanken/helper`. The polkit policy authorizes that exact wrapper path. Launch Vanken as your ordinary user; polkit provides the administrator authentication dialog when capture requires elevation.
+
+For headless Linux or sudo instead of polkit, create a dedicated capture group and add only users who should inspect network traffic. Log out and log in after changing group membership, then use `--policy sudoers --group vanken` in the setup command. The installer requires `visudo` and validates the rule before installing `/etc/sudoers.d/vanken`. It never grants capabilities to a shared Ruby interpreter.
+
+On macOS, create the intended group, install the BPF daemon, and activate it:
+
+```sh
+sudo dseditgroup -o create vanken
+sudo dseditgroup -o edit -a "$USER" -t user vanken
+sudo "$(command -v vanken-setup-permissions)" --group vanken
+sudo launchctl bootstrap system /Library/LaunchDaemons/org.vanken.chmod-bpf.plist
+```
+
+Log out and log in after joining the group. The daemon grants the group mode `0660` on existing BPF devices at startup and every ten seconds, including devices added later. It runs the fixed root-owned shell script; Vanken and the capture helper run as the normal user. Verify access with `vanken-capture --check --interface lo0`. If Wireshark's ChmodBPF already manages these devices, use that configuration instead of installing a second daemon.
+
+Use `--root /absolute/staging-directory` to prepare files in an existing directory without activating system permissions. A staged tree is for review and packaging; it does not validate or grant trust to the runtime paths. Neither `--dry-run` nor staging loads the macOS daemon. To remove the installed macOS configuration, unload `org.vanken.chmod-bpf` with `launchctl bootout`, remove its plist and `chmod-bpf` script, and restore the BPF device ownership/permissions prescribed by your administrator.
+
 The application runs as your normal user. The capture helper opens the capture device, drops supplementary groups and both real and effective group/user IDs, and writes pcapng to stdout. The interpreter, helper, libraries, gems, and every parent directory of the privileged wrapper must be owned by root and must not be writable by group or other users.
 
 On macOS, grant the intended capture group access to `/dev/bpf*` using an administrator-managed startup configuration. Once `vanken-capture --check --interface lo0` reports `"direct":true`, Vanken can capture without sudo. Device permissions may need to be restored after a reboot.
@@ -30,4 +70,4 @@ Validate the rule with `visudo`. Members of this group can capture network traff
 sudo /usr/local/libexec/vanken/vanken-capture -i eth0 --drop-to "$(id -u):$(id -g)" > capture.pcapng
 ```
 
-For the isolated Linux integration check, run `script/capture-ci.sh` with Docker available. It creates a disposable privileged container, installs root-owned Ruby/gems and the fixed helper wrapper, creates the `vanken-test` namespace and a veth pair, then runs the tests as an unprivileged user. The tests verify UID dropping, packet capture, statistics, and clean shutdown. The nightly `Live capture` workflow runs this same command.
+For the isolated Linux integration check, run `script/capture-ci.sh` with Docker available. It creates a disposable privileged container, runs `vanken-setup-permissions` against its root-owned Ruby/gems to install the fixed wrapper and sudoers policy, creates the `vanken-test` namespace and a veth pair, then runs the tests as an unprivileged user. The tests verify environment isolation, UID dropping, packet capture, statistics, and clean shutdown. The installer plan is saved as `permission-install.json`. The nightly `Live capture` workflow runs this same command.

data/packaging/linux/org.vanken.capture.policy

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN" "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
+<policyconfig>
+  <action id="org.vanken.capture">
+    <description>Capture network packets with Vanken</description>
+    <message>Authentication is required to capture network packets.</message>
+    <defaults>
+      <allow_any>no</allow_any>
+      <allow_inactive>no</allow_inactive>
+      <allow_active>auth_admin_keep</allow_active>
+    </defaults>
+    <annotate key="org.freedesktop.policykit.exec.path">/usr/local/libexec/vanken/vanken-capture</annotate>
+  </action>
+</policyconfig>

data/packaging/linux/vanken-capture.wrapper

@@ -0,0 +1,6 @@
+#!/bin/sh
+cd / || exit 1
+exec /usr/bin/env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin \
+  GEM_HOME=VANKEN_GEM_HOME GEM_PATH=VANKEN_GEM_HOME \
+  VANKEN_RUBY -I /usr/local/libexec/vanken/lib \
+  /usr/local/libexec/vanken/helper "$@"

data/packaging/linux/vanken.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=Vanken
+Comment=Capture and inspect network packets
+Exec=vanken %f
+Icon=network-workgroup
+Terminal=false
+Categories=Network;Development;
+MimeType=application/vnd.tcpdump.pcap;application/x-pcapng;

data/packaging/linux/vanken.sudoers

@@ -0,0 +1,2 @@
+# Members of this group can inspect network traffic. Validate with visudo -cf.
+%VANKEN_GROUP ALL=(root) NOPASSWD: /usr/local/libexec/vanken/vanken-capture

data/packaging/macos/chmod-bpf

@@ -0,0 +1,6 @@
+#!/bin/sh
+for device in /dev/bpf[0-9]*; do
+  [ -c "$device" ] || continue
+  /usr/bin/chgrp VANKEN_GROUP "$device" || exit 1
+  /bin/chmod 660 "$device" || exit 1
+done

data/packaging/macos/org.vanken.chmod-bpf.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>org.vanken.chmod-bpf</string>
+  <key>ProgramArguments</key><array><string>/usr/local/libexec/vanken/chmod-bpf</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>StartInterval</key><integer>10</integer>
+</dict></plist>

data/sig/generated/vanken/capture/permission_setup.rbs

@@ -0,0 +1,43 @@
+# Generated from lib/vanken/capture/permission_setup.rb with RBS::Inline
+
+module Vanken
+  module Capture
+    class PermissionSetup
+      PREFIX: ::String
+
+      SOURCE: untyped
+
+      def self.run: (untyped argv, ?stdout: untyped, ?stderr: untyped) -> untyped
+
+      attr_reader platform: untyped
+
+      def initialize: (?platform: untyped, ?ruby: untyped, ?gem_home: untyped, ?policy: untyped, ?group: untyped, ?root: untyped) -> untyped
+
+      def staged?: () -> untyped
+
+      def plan: () -> untyped
+
+      def install: () -> untyped
+
+      def validate_runtime!: () -> untyped
+
+      def validate_group!: () -> untyped
+
+      def next_steps: () -> untyped
+
+      private
+
+      def asset: (untyped relative, ?mode: untyped) -> untyped
+
+      def trusted_tree!: (untyped path, ?untyped visited) -> untyped
+
+      def trusted_path!: (untyped path) -> untyped
+
+      def safe_entry!: (untyped path) -> untyped
+
+      def secure_directory!: (untyped path) -> untyped
+
+      def validate_sudoers!: (untyped path) -> untyped
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vanken
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -58,6 +58,7 @@ email:
 executables:
 - vanken
 - vanken-capture
+- vanken-setup-permissions
 extensions: []
 extra_rdoc_files: []
 files:
@@ -72,6 +73,7 @@ files:
 - docs/usage.md
 - exe/vanken
 - exe/vanken-capture
+- exe/vanken-setup-permissions
 - lib/vanken.rb
 - lib/vanken/app/capture_controller.rb
 - lib/vanken/app/document.rb
@@ -91,6 +93,7 @@ files:
 - lib/vanken/capture/helper_main.rb
 - lib/vanken/capture/helper_options.rb
 - lib/vanken/capture/launcher.rb
+- lib/vanken/capture/permission_setup.rb
 - lib/vanken/capture/privileges.rb
 - lib/vanken/capture/receiver.rb
 - lib/vanken/cli.rb
@@ -142,6 +145,12 @@ files:
 - lib/vanken/ui/settings_operations.rb
 - lib/vanken/version.rb
 - packaging/README.md
+- packaging/linux/org.vanken.capture.policy
+- packaging/linux/vanken-capture.wrapper
+- packaging/linux/vanken.desktop
+- packaging/linux/vanken.sudoers
+- packaging/macos/chmod-bpf
+- packaging/macos/org.vanken.chmod-bpf.plist
 - sig/generated/vanken/app/capture_controller.rbs
 - sig/generated/vanken/app/document.rbs
 - sig/generated/vanken/app/document_analysis.rbs
@@ -160,6 +169,7 @@ files:
 - sig/generated/vanken/capture/helper_main.rbs
 - sig/generated/vanken/capture/helper_options.rbs
 - sig/generated/vanken/capture/launcher.rbs
+- sig/generated/vanken/capture/permission_setup.rbs
 - sig/generated/vanken/capture/privileges.rbs
 - sig/generated/vanken/capture/receiver.rbs
 - sig/generated/vanken/cli.rbs