Bonebed

Bonebed uses Linux seccomp user notifications to observe the files, network addresses, external commands, and thread creation syscalls touched by a Ruby gem. It subtracts normal Ruby and Bundler startup activity, then writes the remaining observations to a JSON capability manifest.

• Profile both gem install and require
• Observe open/openat, connect, execve, clone, and clone3 calls
• Subtract cached Ruby and Bundler startup baselines
• Normalize project, home, gem, and temporary paths for comparable manifests
• Survey RubyGems rankings, gem lists, or Bundler lockfiles with resumable results
• Summarize failures, project file access, and commands by survey target as Markdown

Install Bonebed from RubyGems:

gem install bonebed

• Linux 5.5 or newer on x86_64 or aarch64
• Ruby 3.2 or newer
• Permission to install a seccomp user-notification filter

Docker must run with --security-opt seccomp=unconfined. Bonebed does not run directly on macOS; use the included development container instead.

Run Bonebed in its Linux development container so the gem under observation is not executed directly on the host:

docker build -f Dockerfile.dev -t bonebed-dev .
bin/dev bundle install
bin/dev bundle exec exe/bonebed doctor
bin/dev bundle exec exe/bonebed dig json

The manifest is written to results/. The first observation also caches a matching startup baseline in .bonebed/baselines/.

Use --offline with dig or survey to return ENETUNREACH for observed connections. This is a compatibility check, not a security sandbox. Existing successful survey results are skipped and failures are retried, so interrupted surveys can resume. Each survey entry runs in a fresh worker process so its memory and operating-system resources are released; a killed worker is recorded and the survey continues. A survey finishes every entry but exits with status 1 if any observation fails.

Use sinatra - sinatra/base in a survey file to set a require path without pinning a version. Require paths are ignored during install surveys.

dig still writes its manifest but exits with status 1 when the observed command fails.

1. A seccomp filter sends open/openat, connect, execve, clone, and clone3 notifications to Bonebed.
2. Bonebed decodes and records each call, then allows it to continue unless offline mode rejects a connection.
3. A matching empty-Ruby observation is subtracted as startup noise. Failed read probes for nonexistent paths are discarded; write and network attempts are retained because a notification arrives before the kernel result is known.
4. Target stdout and stderr are streamed while the remaining file paths, network endpoints, commands, thread creation calls, installed gems, counts, timing, errors, and output are written as JSON. Relative paths are resolved from the target process and project paths are normalized to $PWD; routine RubyGems cache writes stay in the file list but are excluded from notable.

Captured output is stored as UTF-8; invalid byte sequences are replaced so binary output cannot prevent manifest creation. Reports show network attempts by target and output emitted by successful require targets. Failure reports keep compact output previews in the table and the complete output in a folded section.

Implementation notes and measured notification overhead are recorded in NOTES.md.

bin/dev bundle exec rake
bin/dev bundle exec exe/bonebed doctor

The development image includes strace for cross-checking noteworthy observations.

Bug reports and pull requests are welcome at github.com/ydah/bonebed.

Bonebed is available as open source under the terms of the MIT License.