straycall 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3148046a174ba55ee9edf9d943c9e834391ec89f16684df60bae3b3bcecbfcf4
+  data.tar.gz: ed337c7d5cf746f9384f9ee9d6397aa53926ecd3e770adf162e43996a820bda4
+SHA512:
+  metadata.gz: 7e8833fbe0ec64716d1ca1bf179b2b7572006e0ea4743d351f1813e10d16a9de61e9ca7d192adffab6e239b610c290b86a247db844b82c18b6cc92f5a0b54611
+  data.tar.gz: 27df7b94480aaeb6c99742b55a32ad0f212b988fabcea451fbe8d6a1063baad91719060e14efb104c32849a25fa1cf458a42b7a0dd41097232b1b3ed5612eef0

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to Straycall are documented here.
+
+## v0.1.0 - 2026-08-23
+
+- Initial release.

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,125 @@
+# Straycall
+
+Straycall reports and blocks unintended network, filesystem, and process access from Ruby builds and test suites. It runs an unfiltered supervisor over Linux `seccomp` user notifications and includes the responsible Ruby backtrace in its report.
+
+> [!WARNING]
+> Straycall detects accidents; it is not a security boundary for hostile code. Pointer-based policy checks, symbolic links, existing file descriptors, and kernel interfaces outside seccomp's reach leave intentional escape routes.
+
+On macOS, Windows, non-MRI Ruby, an unsupported kernel, or with `STRAYCALL=0`, requiring and configuring Straycall is a no-op. The wrapped command runs normally.
+
+## Requirements
+
+- Linux x86_64 or aarch64 with seccomp user notifications and `CONTINUE` (Linux 5.5+)
+- MRI Ruby 3.1+
+- `seccomp-notify` 0.2.x
+
+Container runtimes may block `seccomp(2)` in their own profile. Use an isolated container with `--security-opt seccomp=unconfined` when needed.
+
+## Installation
+
+```ruby
+gem "straycall"
+```
+
+## CLI (recommended)
+
+The CLI keeps the supervisor outside the filtered command, so it does not interfere with the command's `Process.wait` calls.
+
+```sh
+straycall --config .straycall.yml -- bundle exec rspec
+straycall --report-path tmp/straycall.json -- ruby script.rb
+straycall --record --policy-path .straycall.yml -- bundle exec rspec
+straycall --preset=bundle-install -- bundle install
+```
+
+`--warn` and `--record` allow the syscall after reporting it. `--prompt` asks through `/dev/tty`; without a TTY it denies. The default `fail` mode and a denied prompt return `EPERM` and make the CLI exit nonzero.
+
+## YAML policy
+
+```yaml
+network:
+  default: deny
+  allow:
+    - host: 127.0.0.1
+      ports: [5432, 6379]
+    - unix: /var/run/postgresql/.s.PGSQL.5432
+write:
+  default: deny
+  allow: [tmp, log, coverage, /tmp]
+  deny_read: [/etc/shadow, ~/.ssh, ~/.aws, ~/.gem/credentials]
+exec:
+  default: allow
+  deny: [/usr/bin/curl, /usr/bin/wget]
+on_violation: fail
+report_backtrace: true
+report_path: tmp/straycall.json
+```
+
+Hosts are resolved once while loading the configuration. Paths are expanded but symbolic links are deliberately not resolved.
+
+## Ruby configuration
+
+```ruby
+require "straycall"
+
+Straycall.configure do |config|
+  config.deny_network!
+  config.allow_loopback ports: [5432, 6379]
+  config.allow_host "registry.internal.example", ports: [443]
+  config.allow_unix "/var/run/postgresql/.s.PGSQL.5432"
+
+  config.allow_write_under "tmp", "log", "coverage", Dir.tmpdir
+  config.deny_write_elsewhere!
+  config.deny_read "/etc/shadow", "~/.ssh"
+
+  config.allow_exec "/usr/bin/git", "/usr/bin/make"
+  config.deny_exec_elsewhere!
+  # config.allow_io_uring! # disables complete syscall coverage
+  config.report_path = "tmp/straycall.json"
+end
+```
+
+## RSpec and Minitest
+
+Load the integration at the top of the test helper:
+
+```ruby
+# RSpec
+require "straycall/rspec"
+
+# Minitest
+require "straycall/minitest"
+```
+
+This in-process mode starts a clean detached supervisor with `Process.spawn`, associates violations with the current test, and checks the supervisor health pipe. Prefer the CLI if tests use broad `Process.wait` calls or fork heavily; filters are inherited and cannot be removed.
+
+## Reports
+
+Console output includes the syscall, target, current test, Ruby backtrace (MRI), a `/proc/<tid>/maps` native-library fallback, and an allow-list suggestion. `report_path` writes a versioned JSON document:
+
+```json
+{"version":1,"violations":[{"syscall":"connect","tid":123,"target":{"type":"inet","host":"192.0.2.1","port":443},"action":"denied"}]}
+```
+
+## Known limitations
+
+1. This is not a security boundary. Allowing a pointer-based syscall with `continue!` is subject to TOCTOU.
+2. vDSO calls such as normal clock reads cannot be intercepted.
+3. File descriptors opened before filter installation are outside the policy.
+4. `io_uring_setup` is denied so io_uring cannot bypass monitored syscalls. `allow_io_uring!` opts out, but network and filesystem coverage is then incomplete.
+5. Ruby backtraces require MRI 3.1+; native calls fall back to `/proc/<tid>/maps`.
+6. Filesystem checks use the unresolved path string. A symlink can point outside an allowed root.
+7. If the supervisor dies, the kernel returns `ENOSYS`; integrations detect the health-pipe closure as soon as they regain control.
+8. A connected `sendto`/`sendmsg`/`sendmmsg` without an explicit destination relies on the earlier monitored `connect`; Straycall cannot recover a peer address from the target file descriptor.
+9. Listener tracking observes an allowed `bind` before the kernel returns. It prevents accidental auto-bind listeners, but it is not a hostile-code boundary.
+
+## Development
+
+```sh
+ruby -Ilib -S rspec
+gem build straycall.gemspec
+```
+
+Real seccomp integration examples skip automatically outside supported Linux environments.
+
+On Linux, `ruby benchmark/require_overhead.rb` checks that read-only `openat` overhead stays below 10% across 100,000 generated require files, using the median ratio of five alternating pairs after warmup. Set `STRAYCALL_BENCHMARK_FILES` to scale the workload.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/require_overhead.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require "rbconfig"
+require "tmpdir"
+
+abort "straycall is unavailable" unless RUBY_PLATFORM.include?("linux")
+
+Dir.mktmpdir do |directory|
+  files = File.join(directory, "files")
+  Dir.mkdir(files)
+  count = Integer(ENV.fetch("STRAYCALL_BENCHMARK_FILES", "100000"))
+  source = <<~RUBY
+    # frozen_string_literal: true
+
+    module StraycallRequireBenchmark
+      def self.loaded?
+        true
+      end
+
+      def self.call(value)
+        value
+      end
+    end
+  RUBY
+  count.times { |index| File.write(File.join(files, "f#{index}.rb"), source) }
+  script = "Dir[#{files.inspect} + '/*.rb'].each { |file| require file }"
+  config = File.join(directory, "config.yml")
+  File.write(config, <<~YAML)
+    network: {default: deny}
+    write:
+      default: deny
+      allow: [#{directory}]
+  YAML
+
+  clean_environment = ENV.keys.grep(/\A(?:BUNDLE|BUNDLER|RUBY(?:OPT|LIB))/).to_h { |name| [name, nil] }
+  plain_command = [RbConfig.ruby, "-e", script]
+  guarded_command = [
+    RbConfig.ruby,
+    "-I#{File.expand_path("../lib", __dir__)}",
+    "-I#{File.expand_path("../../seccomp-notify/lib", __dir__)}",
+    File.expand_path("../exe/straycall", __dir__),
+    "--config", config, "--", RbConfig.ruby, "-e", script
+  ]
+  measure = lambda do |command|
+    Benchmark.realtime { system(clean_environment, *command, out: File::NULL, exception: true) }
+  end
+
+  measure.call(plain_command)
+  measure.call(guarded_command)
+  samples = {plain_command => [], guarded_command => []}
+  ratios = []
+  5.times do |index|
+    first, second = index.even? ? [plain_command, guarded_command] : [guarded_command, plain_command]
+    first_time = measure.call(first)
+    second_time = measure.call(second)
+    samples.fetch(first) << first_time
+    samples.fetch(second) << second_time
+    timings = {first => first_time, second => second_time}
+    ratios << timings.fetch(guarded_command) / timings.fetch(plain_command)
+  end
+  plain = samples.fetch(plain_command).sort.fetch(2)
+  guarded = samples.fetch(guarded_command).sort.fetch(2)
+  overhead = (ratios.sort.fetch(2) - 1) * 100
+  puts format("files=%d plain=%.3fs guarded=%.3fs overhead=%.1f%%", count, plain, guarded, overhead)
+  abort "overhead exceeded 10%" if overhead > 10
+end

data/docs/index.html

@@ -0,0 +1,186 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="description" content="Straycall reports and blocks unintended network, filesystem, and process access from Ruby builds and test suites.">
+    <meta name="theme-color" content="#07111b">
+    <meta property="og:title" content="Straycall — Catch unintended syscalls in Ruby tests">
+    <meta property="og:description" content="Report and block unintended network, filesystem, and process access from Ruby builds and test suites.">
+    <meta property="og:type" content="website">
+    <meta property="og:url" content="https://ydah.github.io/straycall/">
+    <title>Straycall — Syscall guard for Ruby tests</title>
+    <link rel="canonical" href="https://ydah.github.io/straycall/">
+    <link rel="stylesheet" href="styles.css">
+  </head>
+  <body id="top">
+    <a class="skip-link" href="#main">Skip to content</a>
+
+    <header class="site-header">
+      <a class="brand" href="#top" aria-label="Straycall home">
+        <span class="brand-mark" aria-hidden="true">S/</span>
+        <span>Straycall</span>
+      </a>
+      <nav aria-label="Primary navigation">
+        <a href="#features">Guardrails</a>
+        <a href="#quick-start">Quick start</a>
+        <a href="#policy">Policy</a>
+        <a class="nav-cta" href="https://github.com/ydah/straycall">View on GitHub</a>
+      </nav>
+    </header>
+
+    <main id="main">
+      <section class="hero" aria-labelledby="hero-title">
+        <div class="hero-copy">
+          <p class="eyebrow">Linux syscall guard for Ruby</p>
+          <h1 id="hero-title">Catch the calls your tests <em>didn't mean to make.</em></h1>
+          <p class="hero-lede">
+            Straycall reports and blocks unintended network, filesystem, and process access from Ruby builds and test suites—then points to the responsible Ruby code.
+          </p>
+          <div class="hero-actions">
+            <a class="button button-primary" href="#quick-start">Get started</a>
+            <a class="button button-secondary" href="https://rubygems.org/gems/straycall">View on RubyGems</a>
+          </div>
+          <ul class="support-list" aria-label="Platform support">
+            <li>Linux 5.5+</li>
+            <li>MRI Ruby 3.1+</li>
+            <li>x86_64 &amp; arm64</li>
+          </ul>
+        </div>
+
+        <div class="terminal" aria-label="Example Straycall violation report">
+          <div class="terminal-bar" aria-hidden="true">
+            <p>bundle exec rspec</p>
+          </div>
+          <pre><code><span class="prompt">$</span> straycall -- bundle exec rspec
+
+<span class="accent">straycall:</span> connect(2) → 192.0.2.1:443
+    spec/services/sync_spec.rb:27:in &#96;fetch'
+    app/services/sync.rb:14:in &#96;call'
+
+  <span class="hint">hint:</span> allow_host "192.0.2.1", ports: [443]
+
+<span class="failure">1 example, 1 syscall violation</span></code></pre>
+        </div>
+      </section>
+
+      <section class="section" id="features" aria-labelledby="features-title">
+        <div class="section-heading">
+          <p class="kicker">Guardrails</p>
+          <h2 id="features-title">Three boundaries. One useful report.</h2>
+          <p>Keep accidental side effects out of builds and tests without losing the context needed to fix them.</p>
+        </div>
+        <div class="feature-grid">
+          <article class="feature-card">
+            <span class="feature-index" aria-hidden="true">01</span>
+            <h3>Network</h3>
+            <p>Control outbound connections, Unix sockets, binds, and listeners by host and port.</p>
+            <code>deny_network!</code>
+          </article>
+          <article class="feature-card">
+            <span class="feature-index" aria-hidden="true">02</span>
+            <h3>Filesystem</h3>
+            <p>Allow writes only below known roots and report reads of sensitive paths.</p>
+            <code>deny_write_elsewhere!</code>
+          </article>
+          <article class="feature-card">
+            <span class="feature-index" aria-hidden="true">03</span>
+            <h3>Processes</h3>
+            <p>Restrict executables to an explicit allow list and see where each launch began.</p>
+            <code>deny_exec_elsewhere!</code>
+          </article>
+        </div>
+      </section>
+
+      <section class="section split" id="quick-start" aria-labelledby="quick-start-title">
+        <div class="section-heading">
+          <p class="kicker">Quick start</p>
+          <h2 id="quick-start-title">Install. Wrap. Inspect.</h2>
+          <p>The CLI keeps the supervisor outside the filtered command, so it stays out of your test runner's process handling.</p>
+        </div>
+        <ol class="steps">
+          <li>
+            <div class="step-heading"><span>1</span><h3>Add the gem</h3></div>
+            <pre><code><span class="muted"># Gemfile</span>
+gem "straycall"</code></pre>
+          </li>
+          <li>
+            <div class="step-heading"><span>2</span><h3>Wrap a command</h3></div>
+            <pre><code>straycall --config .straycall.yml -- bundle exec rspec</code></pre>
+          </li>
+          <li>
+            <div class="step-heading"><span>3</span><h3>Choose the response</h3></div>
+            <div class="mode-list">
+              <p><code>fail</code><span>Block and exit nonzero</span></p>
+              <p><code>warn</code><span>Allow and report</span></p>
+              <p><code>record</code><span>Generate a reviewable policy</span></p>
+              <p><code>prompt</code><span>Ask through the terminal</span></p>
+            </div>
+          </li>
+        </ol>
+      </section>
+
+      <section class="section policy-section" id="policy" aria-labelledby="policy-title">
+        <div class="policy-copy">
+          <p class="kicker">Policy as code</p>
+          <h2 id="policy-title">Specific enough to trust.<br>Small enough to review.</h2>
+          <p>Keep the policy beside the project. Hosts resolve once at load time; paths expand without silently resolving symbolic links.</p>
+          <a class="text-link" href="https://github.com/ydah/straycall#yaml-policy">Read the configuration reference <span aria-hidden="true">→</span></a>
+        </div>
+        <div class="code-panel">
+          <p>.straycall.yml</p>
+          <pre><code><span class="key">network:</span>
+  <span class="key">default:</span> deny
+  <span class="key">allow:</span>
+    - <span class="key">host:</span> 127.0.0.1
+      <span class="key">ports:</span> [5432, 6379]
+
+<span class="key">write:</span>
+  <span class="key">default:</span> deny
+  <span class="key">allow:</span> [tmp, log, coverage]
+  <span class="key">deny_read:</span> [~/.ssh, ~/.aws]
+
+<span class="key">exec:</span>
+  <span class="key">default:</span> allow
+  <span class="key">deny:</span> [/usr/bin/curl]
+
+<span class="key">on_violation:</span> fail</code></pre>
+        </div>
+      </section>
+
+      <section class="section" aria-labelledby="how-title">
+        <div class="section-heading">
+          <p class="kicker">How it works</p>
+          <h2 id="how-title">Outside the process. Close to the call.</h2>
+        </div>
+        <div class="flow" role="list">
+          <div role="listitem"><span>01</span><h3>Observe</h3><p>Linux pauses selected syscalls through seccomp user notifications.</p></div>
+          <div role="listitem"><span>02</span><h3>Decide</h3><p>An unfiltered supervisor evaluates the target against your policy.</p></div>
+          <div role="listitem"><span>03</span><h3>Explain</h3><p>The report joins the syscall target with the responsible Ruby backtrace.</p></div>
+        </div>
+      </section>
+
+      <aside class="boundary" aria-labelledby="boundary-title">
+        <p class="kicker">An honest boundary</p>
+        <h2 id="boundary-title">Built to catch accidents—not hostile code.</h2>
+        <p>Pointer-based checks, symbolic links, existing file descriptors, and kernel interfaces outside seccomp's reach leave intentional escape routes. Use Straycall as a test guardrail, not a security sandbox.</p>
+      </aside>
+
+      <section class="cta" aria-labelledby="cta-title">
+        <p class="kicker">Ready to listen?</p>
+        <h2 id="cta-title">Make unintended calls visible.</h2>
+        <p>Install Straycall and wrap your next Ruby build or test run.</p>
+        <div class="hero-actions">
+          <a class="button button-primary" href="https://rubygems.org/gems/straycall">Install from RubyGems</a>
+          <a class="button button-secondary" href="https://github.com/ydah/straycall">Explore the source</a>
+        </div>
+      </section>
+    </main>
+
+    <footer>
+      <a class="brand" href="#top"><span class="brand-mark" aria-hidden="true">S/</span><span>Straycall</span></a>
+      <p>Open source under the MIT License.</p>
+      <div><a href="https://github.com/ydah/straycall">GitHub</a><a href="https://rubygems.org/gems/straycall">RubyGems</a></div>
+    </footer>
+  </body>
+</html>