Bonebed

Observe file, network, and process capabilities used while installing or requiring Ruby gems.

Features · Installation · Quick Start · Commands · How It Works

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

Warning

Bonebed is an observation tool, not a security boundary. Pointer arguments can change between inspection and syscall continuation (TOCTOU), so the manifest describes what was observed rather than guaranteeing what happened.

Features

Profile both gem install and require
Observe open/openat, connect, and execve 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

Installation

Install Bonebed from RubyGems:

gem install bonebed

Requirements

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.

Quick Start

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/.

Commands

Command	Purpose
`bonebed doctor`	Check kernel, architecture, seccomp, and container support
`bonebed baseline [--refresh]`	Create or refresh the startup baseline
`bonebed dig GEM`	Observe a gem while it is required; common load paths are inferred, or use `--require PATH`
`bonebed dig GEM --phase install`	Install and observe a gem in disposable home and gem directories
`bonebed survey --top N`	Observe up to 100 gems from RubyGems.org's all-time ranking
`bonebed survey --file FILE`	Observe gems listed as `NAME [VERSION
`bonebed survey --gemfile Gemfile.lock`	Observe gems from a Bundler lockfile
`bonebed report results --format md`	Summarize collected manifests as Markdown

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. 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.

How It Works

A seccomp filter sends open/openat, connect, and execve notifications to Bonebed.
Bonebed decodes and records each call, then allows it to continue unless offline mode rejects a connection.
A matching empty-Ruby observation is subtracted as startup noise.
Target stdout and stderr are streamed while the remaining file paths, network endpoints, commands, installed gems, counts, timing, errors, and output are written as JSON. 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. 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.

Development

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

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

Contributing

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

License

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

bonebed

Runtime