brittle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b2628f2dc42bcd5afbb6586e92515cdbeee446aaa60fbbb4594321602068021
+  data.tar.gz: fbf4abf31d9875ddd1265ce49e3be162d7670d103ed9c06390fbf689a2355959
+SHA512:
+  metadata.gz: 4e638214991f9572b5c270a4261de60e631720e76b331177c2d1415fe077cd8cbba82b82fd7025b8157b3eb260891916c196faf0a0b1a96e8901c4eddcb15fff
+  data.tar.gz: 5d162c0bcc823769ac498e59ace9d1d7c510184ff7ae425778e47ccd5a1bfca9cee9c75f5a1087eafee69632f1da9814f917fc2c184296142955c92c664a919c

data/.dockerignore

@@ -0,0 +1,7 @@
+.git
+.idea
+.bundle
+Gemfile.lock
+pkg
+results
+*.gem

data/Dockerfile.dev

@@ -0,0 +1,11 @@
+FROM ruby:4.0
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends strace \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . .
+RUN bundle install
+
+CMD ["bash"]

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

@@ -0,0 +1,42 @@
+# Brittle experiment notes
+
+Measurements below were taken on 2026-09-09 in the development container: Ruby 4.0.6,
+Linux 6.8.0-117-generic, and aarch64.
+
+| Check | Result |
+| --- | --- |
+| `error!` argument | `Errno::ENOSPC` is accepted and Ruby receives `Errno::ENOSPC`. |
+| `allow!(10)` | Ruby reports the full 100-byte `File.write` as successful, but the file contains 90 bytes. The emulated first 10 bytes are not written. |
+| marker syscall | `File.exist?` emits `newfstatat(AT_FDCWD, path, ...)` for both marker paths. |
+| target output | Output while armed is also a `write`; every harness disarms before printing its result. |
+| notify overhead | 10,000 `/dev/null` writes took 2.32 ms normally and 316.89 ms when continued through notifications: about 31.46 us per write. |
+| kernel requirement | Pass-through notifications require `continue!`, so Brittle requires Linux 5.5 or newer despite errno responses being available since 5.0. |
+
+`allow!(n)` is useful for observing callers' response to a short return, but it is not a
+faithful partial-write emulator because the reported prefix is dropped. Such scenarios are marked
+`realistic: false` and must not be reported as an upstream data-corruption bug without reproduction
+under a real short write.
+
+## Finding: Logger leaks a descriptor when its header write fails
+
+`brittle sweep harness/logger.rb --syscall write --errno ENOSPC --at 1..8` found a one-fd
+increase at `at=1`. The generated journal recorded `fd_before=7`, `fd_after=8`, and `verdict=leak`.
+
+The behavior reproduces without seccomp on a full 64 KiB tmpfs. Five failed `Logger.new` calls
+increase the descriptor count from 6 to 11. `Logger::LogDevice#create_logfile` opens and locks the
+new file, then lets a header-write exception escape without closing the local `logdev`.
+
+See [`findings/logger-enospc-fd-leak.md`](findings/logger-enospc-fd-leak.md) for the upstream report
+draft and [`verify/logger_enospc.rb`](verify/logger_enospc.rb) for the real-condition check.
+
+## Catalog sweep
+
+The full `script/sweep_catalog` run completed all 500 deterministic cases (`at=1..20`):
+
+- Logger header writes leaked one fd for both `ENOSPC` and `EDQUOT` at occurrence 1.
+- Logger swallowed the same errors for the log-message write at occurrence 2, leaving the expected
+  message absent; the harness classified this as `corrupt`.
+- `Net::HTTP` translated `connect` `ETIMEDOUT` into `Net::OpenTimeout`, which its harness accepts.
+- Synthetic short `write` corrupted output and signal-less `EINTR` led to `ENOTCONN`; both scenarios
+  are marked unrealistic and were excluded from upstream findings.
+- All remaining scoped cases were classified as expected.

data/README.md

@@ -0,0 +1,147 @@
+# Brittle
+
+Brittle deterministically injects errno responses and synthetic return values into syscalls made
+by Ruby programs. It uses Linux seccomp user notifications through
+[`seccomp-notify`](https://github.com/ydah/seccomp-notify).
+
+> [!WARNING]
+> Brittle deliberately breaks its target process. Use it only in isolated development and test
+> environments, never in production.
+
+## Requirements
+
+- Linux 5.5 or newer
+- x86_64 or aarch64
+- Ruby 3.2 or newer
+- A container or host that permits seccomp user notifications
+
+Linux 5.0 can return synthetic errno values, but Brittle also needs `continue!` to pass unmatched
+syscalls through, which requires Linux 5.5.
+
+## Installation
+
+Install the gem after its first release:
+
+```bash
+gem install brittle
+```
+
+For development, build the included container once and run commands through `bin/dev`:
+
+```bash
+docker build -f Dockerfile.dev -t brittle-dev .
+bin/dev bundle exec exe/brittle doctor
+```
+
+## Usage
+
+Harnesses call `Brittle.arm!` immediately before the operation under test and always call
+`Brittle.disarm!` afterward. Startup, requires, and result output therefore pass through without
+fault injection.
+
+```ruby
+require "brittle/marker"
+
+result = nil
+Brittle.arm!
+begin
+  File.write(ENV.fetch("BRITTLE_SANDBOX") + "/out.txt", "hello")
+  result = "OK:out.txt:5"
+rescue => error
+  result = "ERR:#{error.class}:#{error.message}"
+ensure
+  Brittle.disarm!
+end
+puts result
+```
+
+Inject `ENOSPC` into the first armed `write`:
+
+```bash
+brittle run harness/file_write.rb --inject write --errno ENOSPC --at 1
+```
+
+Search every occurrence in a deterministic range:
+
+```bash
+brittle sweep harness/logger.rb \
+  --syscall write --errno ENOSPC --fd-path /brittle- --at 1..20
+```
+
+Other selectors and scopes are available:
+
+```bash
+# Multiple exact occurrences
+brittle run harness/file_write.rb --inject write --errno EDQUOT --at 3,7,11
+
+# Every fifth matching call
+brittle run harness/file_write.rb --inject write --errno ENOSPC --every 5
+
+# Seeded probability
+brittle run harness/file_write.rb \
+  --inject write --errno ENOSPC --probability 0.1 --seed 42
+
+# Path and destination scopes
+brittle run harness/file_write.rb --inject openat --errno EMFILE --path /brittle-
+brittle run harness/net_http.rb --inject connect --errno ECONNREFUSED --port 8080
+
+# Synthetic successful return without executing the syscall
+brittle run harness/syswrite_loop.rb --inject write --return-value 10 --at 1
+```
+
+Every run writes a JSON journal under `results/`. Journals include the scenario, environment,
+injection events, stdout/stderr, artifact sizes and SHA-256 hashes, fd counts, and verdict. They can
+be summarized or converted back into a command:
+
+```bash
+brittle report results/
+brittle reproduce results/file_write-write-ENOSPC-1-....json
+```
+
+Verdicts are `expected`, `crash`, `swallowed`, `corrupt`, `leak`, or `hang`. A harness may print
+`EXPECTED:`, `CORRUPT:`, or `SWALLOWED:` when it has a target-specific oracle that cannot be
+inferred from the injected errno alone.
+
+## Scenario DSL
+
+The same matching rules are available to Ruby callers:
+
+```ruby
+scenario = Brittle.scenario do
+  inject :write, errno: Errno::ENOSPC, at: 3, when_fd_path: /brittle-/
+  inject :connect, errno: Errno::ECONNREFUSED, port: 8080, every: 1
+end
+```
+
+## Reality checks
+
+Fault injection identifies candidates; it does not prove that a result is an upstream bug. Re-run
+every finding under the real failure condition before reporting it. The checks under `verify/`
+demonstrate this workflow.
+
+- `allow!(n)` reports success without performing the syscall. For `write`, the reported prefix is
+  not written, so this is not a faithful partial-write emulator. Such journals say
+  `realistic: false`.
+- An injected `EINTR` has no accompanying signal. Brittle marks that combination as unrealistic.
+- Pointer-based path and port scopes are for test targeting, not security decisions; target memory
+  may change before a continued syscall executes.
+
+See [NOTES.md](NOTES.md) for measurements and the first real-condition finding.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake
+
+# Linux integration tests
+docker build -f Dockerfile.dev -t brittle-dev .
+bin/dev bundle exec rake
+
+# Short catalog check; omit AT_RANGE for the full 1..20 sweep
+AT_RANGE=1..2 bin/dev script/sweep_catalog
+```
+
+## License
+
+Brittle is available under the [MIT License](LICENSE.txt).

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/exe/brittle

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "brittle/cli"
+
+exit Brittle::CLI.start

data/findings/logger-enospc-fd-leak.md

@@ -0,0 +1,51 @@
+# `Logger.new` leaks a file descriptor when writing the log header fails
+
+## Environment
+
+- logger 1.7.0
+- Ruby 4.0.6
+- Linux 6.8.0-117-generic, aarch64
+
+## Reproduction
+
+This repository includes a check that fills a small tmpfs, calls `Logger.new` five times, and
+counts `/proc/self/fd` before and after. It does not use seccomp or fault injection.
+
+```bash
+docker run --rm --tmpfs /full:rw,size=64k \
+  -v "$PWD:/app" -w /app brittle-dev \
+  bundle exec ruby verify/logger_enospc.rb /full
+```
+
+Actual output:
+
+```text
+logger=1.7.0 failures=5 fd_before=6 fd_after=11 delta=5
+```
+
+Expected: each descriptor opened by a failed initialization is closed.
+
+Actual: each failed initialization leaves one descriptor open until garbage collection.
+
+## Cause
+
+`Logger::LogDevice#create_logfile` stores the newly opened file only in its local `logdev`. If
+`add_log_header(logdev)` raises `Errno::ENOSPC`, initialization exits before the file reaches
+`@dev`, so callers cannot close it.
+
+## Proposed fix
+
+Close the local file for every exception other than the existing `EEXIST` retry:
+
+```diff
+       rescue Errno::EEXIST
+         # file is created by another process
+         open_logfile(filename)
++      rescue Exception
++        logdev&.close
++        raise
+       end
+```
+
+The corresponding regression test should make `add_log_header` raise, assert that the exception
+is preserved, and assert that the opened file is closed.

data/harness/csv_write.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "csv"
+require "digest"
+
+rows = [["name", "value"], ["brittle", "1"], ["ruby", "2"]]
+payload = rows.map { |row| CSV.generate_line(row) }.join
+path = File.join(ENV.fetch("BRITTLE_SANDBOX"), "data.csv")
+Brittle.arm!
+result = begin
+  CSV.open(path, "w") { |csv| rows.each { |row| csv << row } }
+  "OK:data.csv:#{payload.bytesize}:#{Digest::SHA256.hexdigest(payload)}"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  Brittle.disarm!
+end
+puts result

data/harness/file_write.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "digest"
+
+payload = "file-write\n" * 4096
+path = File.join(ENV.fetch("BRITTLE_SANDBOX"), "file-write.txt")
+Brittle.arm!
+result = begin
+  File.write(path, payload)
+  "OK:file-write.txt:#{payload.bytesize}:#{Digest::SHA256.hexdigest(payload)}"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  Brittle.disarm!
+end
+puts result

data/harness/gzip_writer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "zlib"
+
+payload = "gzip\n" * 4096
+path = File.join(ENV.fetch("BRITTLE_SANDBOX"), "data.gz")
+Brittle.arm!
+result = begin
+  Zlib::GzipWriter.open(path) { |gzip| gzip.write(payload) }
+  raise "gzip content mismatch" unless Zlib::GzipReader.open(path, &:read) == payload
+
+  "OK:gzip"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  Brittle.disarm!
+end
+puts result

data/harness/logger.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "logger"
+
+logger = nil
+path = File.join(ENV.fetch("BRITTLE_SANDBOX"), "app.log")
+message = "hello from brittle"
+Brittle.arm!
+result = begin
+  logger = Logger.new(path)
+  logger.info(message)
+  logger.close
+  File.read(path).include?(message) ? "OK:logger" : "CORRUPT:app.log:missing message"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  logger&.close
+  Brittle.disarm!
+end
+puts result

data/harness/net_http.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "net/http"
+require "socket"
+
+server = TCPServer.new("127.0.0.1", Integer(ENV.fetch("BRITTLE_PORT", "0")))
+port = server.local_address.ip_port
+thread = Thread.new do
+  socket = server.accept
+  loop do
+    line = socket.gets
+    break if line.nil? || line == "\r\n"
+  end
+  socket.write("HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nOK")
+  socket.close
+rescue IOError, Errno::EBADF
+  nil
+end
+
+Brittle.arm!
+result = begin
+  body = Net::HTTP.get(URI("http://127.0.0.1:#{port}/"))
+  raise "HTTP content mismatch" unless body == "OK"
+
+  "OK:http"
+rescue Net::OpenTimeout => error
+  "EXPECTED:#{error.class}:#{error.message}"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  Brittle.disarm!
+end
+server.close
+thread.join(1)
+puts result

data/harness/syswrite_loop.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "digest"
+
+payload = "syswrite\n" * 4096
+path = File.join(ENV.fetch("BRITTLE_SANDBOX"), "syswrite.txt")
+file = File.open(path, "w")
+Brittle.arm!
+result = begin
+  remaining = payload
+  remaining = remaining.byteslice(file.syswrite(remaining)..) until remaining.empty?
+  file.close
+  "OK:syswrite.txt:#{payload.bytesize}:#{Digest::SHA256.hexdigest(payload)}"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  file.close unless file.closed?
+  Brittle.disarm!
+end
+puts result

data/harness/tempfile.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "brittle/marker"
+require "digest"
+require "tempfile"
+
+payload = "tempfile\n" * 4096
+file = nil
+Brittle.arm!
+result = begin
+  file = Tempfile.create("brittle", ENV.fetch("BRITTLE_SANDBOX"))
+  file.write(payload)
+  file.flush
+  file.close
+  "OK:#{File.basename(file.path)}:#{payload.bytesize}:#{Digest::SHA256.hexdigest(payload)}"
+rescue => error
+  "ERR:#{error.class}:#{error.message}"
+ensure
+  file&.close
+  Brittle.disarm!
+end
+puts result

data/lib/brittle/arm_state.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Brittle
+  class ArmState
+    attr_reader :fd_before, :fd_after
+
+    def initialize
+      @armed = false
+    end
+
+    def armed? = @armed
+
+    def transition(path, fd_count: nil)
+      case path
+      when ARM_PATH
+        @armed = true
+        @fd_before = fd_count
+        :armed
+      when DISARM_PATH
+        @armed = false
+        @fd_after = fd_count
+        :disarmed
+      end
+    end
+
+    def fd_leak? = @fd_before && @fd_after ? @fd_after > @fd_before : false
+  end
+end

data/lib/brittle/cli.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "shellwords"
+require_relative "../brittle"
+require_relative "doctor"
+
+module Brittle
+  module CLI
+    module_function
+
+    def start(argv = ARGV, output: $stdout, error: $stderr)
+      case argv.shift
+      when "doctor"
+        Doctor.check(output:) ? 0 : 1
+      when "run"
+        run(argv, output:)
+      when "sweep"
+        sweep(argv, output:)
+      when "report"
+        report(argv, output:)
+      when "reproduce"
+        reproduce(argv, output:)
+      else
+        error.puts usage
+        1
+      end
+    rescue Error, JSON::ParserError, OptionParser::ParseError, SystemCallError, ArgumentError => exception
+      error.puts "brittle: #{exception.message}"
+      1
+    end
+
+    def run(argv, output:)
+      command = ["brittle", "run", *argv]
+      options, harness = parse_run_options(argv)
+      journal = Runner.new(harness, scenario(options), timeout: options[:timeout], command:).run
+      path = journal.write(options[:journal] || journal_path(harness, options))
+      result = journal.data.fetch(:result)
+      output.write(result.fetch(:stdout))
+      output.puts "verdict: #{result.fetch(:verdict)}"
+      output.puts "journal: #{path}"
+      0
+    end
+
+    def sweep(argv, output:)
+      options, harness = parse_run_options(argv, sweep: true)
+      options.fetch(:at).each do |at|
+        run_options = options.merge(at:, journal: nil)
+        command = reproduce_command(harness, run_options)
+        journal = Runner.new(harness, scenario(run_options), timeout: options[:timeout], command:).run
+        journal.write(journal_path(harness, run_options))
+        result = journal.data.fetch(:result)
+        detail = result.fetch(:stdout).lines.grep(/\A(?:OK|ERR|EXPECTED|CORRUPT|SWALLOWED):/).last&.strip
+        output.puts ["at=#{at}", result.fetch(:verdict), detail].compact.join("  ")
+      end
+      0
+    end
+
+    def report(argv, output:)
+      directory = argv.shift or raise ArgumentError, "usage: brittle report RESULTS_DIR"
+      raise ArgumentError, "unexpected arguments: #{argv.join(" ")}" unless argv.empty?
+
+      paths = Dir.glob(File.join(directory, "*.json")).sort
+      raise ArgumentError, "no journals found in #{directory}" if paths.empty?
+
+      paths.each do |path|
+        journal = JSON.parse(File.read(path))
+        result = journal.fetch("result")
+        output.puts [File.basename(path), result.fetch("verdict"), "exit=#{result["exit_status"]}"].join("  ")
+      end
+      0
+    end
+
+    def reproduce(argv, output:)
+      path = argv.shift or raise ArgumentError, "usage: brittle reproduce JOURNAL"
+      raise ArgumentError, "unexpected arguments: #{argv.join(" ")}" unless argv.empty?
+
+      command = JSON.parse(File.read(path)).fetch("reproduce")
+      output.puts Shellwords.join(command)
+      0
+    end
+
+    def parse_run_options(argv, sweep: false)
+      options = {timeout: 10}
+      parser = OptionParser.new do |opts|
+        opts.on("--inject SYSCALL", "--syscall SYSCALL") { |value| options[:syscall] = value.to_sym }
+        opts.on("--errno NAME") { |value| options[:errno] = errno(value) }
+        opts.on("--return-value INTEGER", Integer) { |value| options[:return_value] = value }
+        opts.on("--at SELECTOR") { |value| options[:at] = sweep ? occurrence_range(value) : occurrences(value) }
+        opts.on("--every INTEGER", Integer) { |value| options[:every] = value }
+        opts.on("--probability NUMBER", Float) { |value| options[:probability] = value }
+        opts.on("--seed INTEGER", Integer) { |value| options[:seed] = value }
+        opts.on("--fd-path PATTERN") { |value| options[:when_fd_path] = value }
+        opts.on("--path PATTERN") { |value| options[:when_path] = value }
+        opts.on("--port PORT", Integer) { |value| options[:port] = value }
+        opts.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+        opts.on("--journal PATH") { |value| options[:journal] = value } unless sweep
+      end
+      parser.parse!(argv)
+      harness = argv.shift or raise OptionParser::MissingArgument, "HARNESS"
+      raise OptionParser::InvalidArgument, "unexpected arguments: #{argv.join(" ")}" unless argv.empty?
+      raise OptionParser::MissingArgument, "--inject/--syscall" unless options[:syscall]
+      if options[:errno].nil? == options[:return_value].nil?
+        raise OptionParser::InvalidArgument, "choose exactly one of --errno or --return-value"
+      end
+      if sweep
+        raise OptionParser::MissingArgument, "--at FIRST..LAST" unless options[:at].is_a?(Range)
+        raise OptionParser::InvalidArgument, "sweep only supports --at" if options[:every] || options[:probability]
+      else
+        options[:at] ||= 1 unless options[:every] || options[:probability]
+      end
+
+      [options, harness]
+    end
+
+    def scenario(options)
+      Scenario.new.inject(options.fetch(:syscall), **options.slice(
+        :errno, :return_value, :at, :every, :probability, :seed, :when_fd_path, :when_path, :port
+      ))
+    end
+
+    def errno(value)
+      Errno.const_get(value.delete_prefix("Errno::"), false)
+    rescue NameError
+      raise OptionParser::InvalidArgument, "unknown errno: #{value}"
+    end
+
+    def occurrences(value)
+      value.split(",").map { |item| Integer(item, 10) }
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "--at must be a positive integer or comma-separated list"
+    end
+
+    def occurrence_range(value)
+      match = value.match(/\A(\d+)\.\.(\d+)\z/)
+      raise OptionParser::InvalidArgument, "--at must be FIRST..LAST" unless match
+
+      first, last = match.captures.map { |item| Integer(item, 10) }
+      raise OptionParser::InvalidArgument, "--at range must be ascending and positive" unless first.positive? && first <= last
+
+      first..last
+    end
+
+    def journal_path(harness, options)
+      action = options[:errno]&.name&.delete_prefix("Errno::") || "return-#{options[:return_value]}"
+      at = Array(options[:at]).join("-")
+      timestamp = Time.now.strftime("%Y%m%d-%H%M%S-%6N")
+      File.join("results", "#{File.basename(harness, ".rb")}-#{options.fetch(:syscall)}-#{action}-#{at}-#{timestamp}.json")
+    end
+
+    def reproduce_command(harness, options)
+      command = ["brittle", "run", harness, "--inject", options.fetch(:syscall).to_s]
+      command.concat(options[:errno] ? ["--errno", options[:errno].name.delete_prefix("Errno::")] : ["--return-value", options[:return_value].to_s])
+      command.concat(["--at", options.fetch(:at).to_s])
+      command.concat(["--fd-path", options[:when_fd_path]]) if options[:when_fd_path]
+      command.concat(["--path", options[:when_path]]) if options[:when_path]
+      command.concat(["--port", options[:port].to_s]) if options[:port]
+      command.concat(["--timeout", options[:timeout].to_s]) if options[:timeout] != 10
+      command
+    end
+
+    def usage
+      <<~USAGE
+        usage:
+          brittle doctor
+          brittle run HARNESS --inject SYSCALL --errno NAME --at N
+          brittle sweep HARNESS --syscall SYSCALL --errno NAME --at FIRST..LAST
+          brittle report RESULTS_DIR
+          brittle reproduce JOURNAL
+      USAGE
+    end
+  end
+end