seccomp-tools 1.6.1 → 1.7.0

data/lib/seccomp-tools/cli/cli.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require 'seccomp-tools/cli/asm'
+require 'seccomp-tools/cli/audit'
+require 'seccomp-tools/cli/completion'
 require 'seccomp-tools/cli/disasm'
 require 'seccomp-tools/cli/dump'
 require 'seccomp-tools/cli/emu'
+require 'seccomp-tools/cli/explain'
 require 'seccomp-tools/version'
 
 module SeccompTools
@@ -12,9 +15,12 @@ module SeccompTools
     # Handled commands
     COMMANDS = {
       'asm' => SeccompTools::CLI::Asm,
+      'audit' => SeccompTools::CLI::Audit,
+      'completion' => SeccompTools::CLI::Completion,
       'disasm' => SeccompTools::CLI::Disasm,
       'dump' => SeccompTools::CLI::Dump,
-      'emu' => SeccompTools::CLI::Emu
+      'emu' => SeccompTools::CLI::Emu,
+      'explain' => SeccompTools::CLI::Explain
     }.freeze
 
     # Main usage message.
@@ -57,14 +63,12 @@ EOS
       COMMANDS[cmd].new(argv).handle
     end
 
-    # Just write message to stdout.
+    # Writes a message to stdout, followed by a newline.
     # @param [String] msg
-    #   The message.
-    # @return [false]
-    #   Always return +false+.
+    #   The message to be written.
+    # @return [void]
     def show(msg)
       puts msg
-      false
     end
 
     class << self

data/lib/seccomp-tools/cli/completion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'completion' command.
+    class Completion < Base
+      # Summary of this command.
+      SUMMARY = 'Print a shell completion script.'
+      # Usage of this command.
+      USAGE = "completion - #{SUMMARY}\n\nUsage: seccomp-tools completion <bash|zsh|fish>".freeze
+
+      # Maps a shell name to the completion script that ships with the gem.
+      SCRIPTS = { 'bash' => 'seccomp-tools.bash', 'zsh' => '_seccomp-tools', 'fish' => 'seccomp-tools.fish' }.freeze
+
+      # Define option parser.
+      # @return [OptionParser]
+      #   The parser of this command's options.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = usage
+        end
+      end
+
+      # Writes the completion script for the requested shell to stdout.
+      # @return [void]
+      def handle
+        return unless super
+
+        shell = argv.shift
+        file = SCRIPTS[shell]
+        return CLI.show(parser.help) if file.nil?
+
+        output { File.read(File.join(__dir__, '..', '..', '..', 'completions', file)) }
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/disasm.rb

@@ -10,8 +10,11 @@ module SeccompTools
       # Summary of this command.
       SUMMARY = 'Disassemble seccomp bpf.'
       # Usage of this command.
-      USAGE = "disasm - #{SUMMARY}\n\nUsage: seccomp-tools disasm BPF_FILE [options]"
+      USAGE = "disasm - #{SUMMARY}\n\nUsage: seccomp-tools disasm BPF_FILE [options]".freeze
 
+      # Instantiate a {Disasm} object, showing raw BPF and inferred arguments by default.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:bpf] = true
@@ -20,10 +23,11 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.') do |o|
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.') do |o|
             option[:ofile] = o
           end
           option_arch(opt)
@@ -35,9 +39,9 @@ module SeccompTools
                  'Default: true') do |f|
                    option[:arg_infer] = f
                  end
-          opt.on('--asm-able', 'Output with this flag is a valid input of "seccomp-tools asm".',
-                 'By default, "seccomp-tools disasm" is in a human-readable format that easy for analysis.',
-                 'Passing this flag can have the output be simplified to a valid input for "seccomp-tools asm".',
+          opt.on('--asm-able', 'Make the output valid input for "seccomp-tools asm".',
+                 'By default, "seccomp-tools disasm" outputs a human-readable format meant for analysis.',
+                 'With this flag the output is simplified so it can be fed back to "seccomp-tools asm".',
                  'This flag implies "--no-bpf --no-arg-infer".',
                  'Default: false') do |_f|
                    option[:bpf] = false
@@ -46,7 +50,7 @@ module SeccompTools
         end
       end
 
-      # Handle options.
+      # Disassembles the input file and writes the result.
       # @return [void]
       def handle
         return unless super

data/lib/seccomp-tools/cli/dump.rb

@@ -1,39 +1,37 @@
 # frozen_string_literal: true
 
-require 'shellwords'
-
 require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
 require 'seccomp-tools/disasm/disasm'
 require 'seccomp-tools/dumper'
-require 'seccomp-tools/logger'
 
 module SeccompTools
   module CLI
     # Handle 'dump' command.
     class Dump < Base
+      include FilterInput
+
       # Summary of this command.
-      SUMMARY = 'Automatically dump seccomp bpf from execution file(s).'
+      SUMMARY = 'Automatically dump seccomp bpf from executable(s).'
       # Usage of this command.
-      USAGE = "dump - #{SUMMARY}\nNOTE : This function is only available on Linux." \
-              "\n\nUsage: seccomp-tools dump [exec] [options]"
+      USAGE = "dump - #{SUMMARY}\nNOTE: This command is only available on Linux." \
+              "\n\nUsage: seccomp-tools dump [EXEC] [options]".freeze
 
+      # Instantiate a {Dump} object, dumping the first filter as disassembly by default.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:format] = :disasm
-        option[:limit] = 1
-        option[:pid] = nil
       end
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-c', '--sh-exec <command>', 'Executes the given command (via sh).',
-                 'Use this option if want to pass arguments or do pipe things to the execution file.',
-                 'e.g. use `-c "./bin > /dev/null"` to dump seccomp without being mixed with stdout.') do |command|
-            option[:command] = command
-          end
+          option_filter_source(opt, 'dump')
 
           opt.on('-f', '--format FORMAT', %i[disasm raw inspect],
                  'Output format. FORMAT can only be one of <disasm|raw|inspect>.',
@@ -41,55 +39,42 @@ module SeccompTools
                    option[:format] = f
                  end
 
-          opt.on('-l', '--limit LIMIT', 'Limit the number of calling "prctl(PR_SET_SECCOMP)".',
-                 'The target process will be killed whenever its calling times reaches LIMIT.',
-                 'Default: 1', Integer) do |l|
-                   option[:limit] = l
-                 end
-
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.',
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.',
                  'If multiple seccomp syscalls have been invoked (see --limit),',
-                 'results will be written to FILE, FILE_1, FILE_2.. etc.',
-                 'For example, "--output out.bpf" and the output files are out.bpf, out_1.bpf, ...') do |o|
+                 'results are written to FILE, FILE_1, FILE_2, etc.',
+                 'For example, with "--output out.bpf" the output files are out.bpf, out_1.bpf, ...') do |o|
                    option[:ofile] = o
                  end
-
-          opt.on('-p', '--pid PID', 'Dump installed seccomp filters of the existing process.',
-                 'You must have CAP_SYS_ADMIN (e.g. be root) in order to use this option.',
-                 Integer) do |p|
-            option[:pid] = p
-          end
         end
       end
 
-      # Handle options.
+      # Traces the target process and writes out the seccomp filters it installs.
+      #
+      # Only available on Linux, logs an error and returns otherwise.
       # @return [void]
       def handle
-        return Logger.error('Dump is only available on Linux.') unless Dumper::SUPPORTED
+        return unless dumping_supported?
         return unless super
 
-        block = lambda do |bpf, arch|
-          case option[:format]
-          when :inspect then output { "\"#{bpf.bytes.map { |b| format('\\x%02X', b) }.join}\"\n" }
-          when :raw then output { bpf }
-          when :disasm then output { SeccompTools::Disasm.disasm(bpf, arch: arch) }
-          end
-        end
-        if option[:pid].nil?
-          option[:command] = argv.shift unless argv.empty?
-          SeccompTools::Dumper.dump('/bin/sh', '-c', option[:command], limit: option[:limit], &block)
-        else
-          begin
-            SeccompTools::Dumper.dump_by_pid(option[:pid], option[:limit], &block)
-          rescue Errno::EPERM, Errno::EACCES => e
-            Logger.error(<<~EOS)
-            #{e}
-            PTRACE_SECCOMP_GET_FILTER requires CAP_SYS_ADMIN
-            Try:
-                sudo env "PATH=$PATH" #{(%w[seccomp-tools] + ARGV).shelljoin}
-            EOS
-            exit(1)
-          end
+        collect_filters.each { |bpf, arch| emit(bpf, arch) }
+      end
+
+      private
+
+      # A positional argument is always an executable to trace, never a raw BPF blob to read: that is
+      # +disasm+'s job, and a non-ELF executable (a shell script wrapping the target) must still run.
+      # @return [Boolean]
+      def accepts_raw_bpf?
+        false
+      end
+
+      # Writes one dumped filter in the requested format.
+      # @return [void]
+      def emit(bpf, arch)
+        case option[:format]
+        when :inspect then output { "\"#{bpf.bytes.map { |b| format('\\x%02X', b) }.join}\"\n" }
+        when :raw then output { bpf }
+        when :disasm then output { SeccompTools::Disasm.disasm(bpf, arch:) }
         end
       end
     end

data/lib/seccomp-tools/cli/dumpable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+require 'seccomp-tools/dumper'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Shared helpers for the commands that dump seccomp filters via ptrace ({Dump} and {Explain}).
+    module Dumpable
+      # Dumps the seccomp filters from a command run via +sh+, or from an existing process, yielding
+      # each installed filter.
+      #
+      # When +pid+ is given the process is traced (requiring +CAP_SYS_ADMIN+); otherwise +command+
+      # is executed. On a permission error while tracing a pid, {#dump_permission_error} exits.
+      # Warns when nothing was installed, so a caller that produces no output still tells the user why.
+      # @param [String?] command
+      #   The command to run, when +pid+ is +nil+.
+      # @param [Integer?] pid
+      #   The process to trace, or +nil+ to run +command+.
+      # @param [Integer] limit
+      #   Stop after this many installed filters.
+      # @param [Float?] timeout
+      #   Seconds to wait for +command+, ignored when tracing a pid.
+      # @yieldparam [String] bpf
+      #   One installed filter, as raw bytes.
+      # @yieldparam [Symbol?] arch
+      #   The architecture of the traced process, if known.
+      # @return [Array]
+      #   One entry per filter: the block's return values. Empty when nothing was installed.
+      def dump_seccomp(command:, pid:, limit:, timeout:, &)
+        filters = if pid
+                    dump_seccomp_by_pid(pid, limit, &)
+                  else
+                    SeccompTools::Dumper.dump('/bin/sh', '-c', command, limit:, timeout:, &)
+                  end
+        Logger.warn('No seccomp filter was installed.') if filters.empty?
+        filters
+      end
+
+      # Whether tracer-based dumping is available on this platform (Linux only). Logs an error when
+      # it is not, so callers can guard with +return unless dumping_supported?+.
+      # @return [Boolean]
+      def dumping_supported?
+        return true if SeccompTools::Dumper::SUPPORTED
+
+        Logger.error('Dumping a filter from an executable or process is only available on Linux.')
+        false
+      end
+
+      private
+
+      # Traces +pid+, translating a permission error into the standard hint.
+      def dump_seccomp_by_pid(pid, limit, &)
+        SeccompTools::Dumper.dump_by_pid(pid, limit, &)
+      rescue Errno::EPERM, Errno::EACCES => e
+        dump_permission_error(e)
+      end
+
+      # Reports a permission error from tracing a process and exits.
+      #
+      # Dumping a filter by pid needs +CAP_SYS_ADMIN+ for +PTRACE_SECCOMP_GET_FILTER+.
+      # @param [SystemCallError] err
+      #   The +Errno::EPERM+ or +Errno::EACCES+ that was raised.
+      # @raise [SystemExit]
+      #   Always; the process is terminated with exit status 1.
+      def dump_permission_error(err)
+        Logger.error(<<~EOS)
+          #{err}
+          PTRACE_SECCOMP_GET_FILTER requires CAP_SYS_ADMIN
+          Try:
+              sudo env "PATH=$PATH" #{(%w[seccomp-tools] + ARGV).shelljoin}
+        EOS
+        exit(1)
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/emu.rb

@@ -15,8 +15,11 @@ module SeccompTools
       # Summary of this command.
       SUMMARY = 'Emulate seccomp rules.'
       # Usage of this command.
-      USAGE = "emu - #{SUMMARY}\n\nUsage: seccomp-tools emu [options] BPF_FILE [sys_nr [arg0 [arg1 ... arg5]]]"
+      USAGE = "emu - #{SUMMARY}\n\nUsage: seccomp-tools emu [options] BPF_FILE [sys_nr [arg0 [arg1 ... arg5]]]".freeze
 
+      # Instantiate an {Emu} object, defaulting to verbose output.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:verbose] = 1
@@ -24,6 +27,7 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
@@ -33,10 +37,14 @@ module SeccompTools
           opt.on('-q', '--[no-]quiet', 'Run quietly, only show emulation result.') do |v|
             option[:verbose] = 0 if v
           end
+
+          opt.on('-i', '--ip=VAL', Integer, 'Set instruction pointer.') do |val|
+            option[:instruction_pointer] = val
+          end
         end
       end
 
-      # Handle options.
+      # Emulates the filter against the given syscall and shows the resulting action.
       # @return [void]
       def handle
         return unless super
@@ -50,9 +58,13 @@ module SeccompTools
         sys = evaluate_sys_nr(sys) if sys
         args.map! { |v| Integer(v) }
         trace = Set.new
-        res = SeccompTools::Emulator.new(insts, sys_nr: sys, args: args, arch: option[:arch]).run do |ctx|
-          trace << ctx[:pc]
-        end
+        res = SeccompTools::Emulator.new(
+          insts,
+          sys_nr: sys,
+          args:,
+          instruction_pointer: option[:instruction_pointer] && Integer(option[:instruction_pointer]),
+          arch: option[:arch]
+        ).run
 
         if option[:verbose] >= 1
           disasm = SeccompTools::Disasm.disasm(raw, arch: option[:arch]).lines
@@ -67,17 +79,28 @@ module SeccompTools
 
       private
 
+      # Resolves a syscall given on the command line, by name or by number.
+      #
       # @param [String] str
+      #   A syscall name valid for +option[:arch]+, or an integer literal.
       # @return [Integer]
+      #   The syscall number.
+      # @raise [ArgumentError]
+      #   If +str+ is neither a known syscall name nor a valid integer.
       def evaluate_sys_nr(str)
         consts = SeccompTools::Const::Syscall.const_get(option[:arch].to_s.upcase)
         consts[str.to_sym] || Integer(str)
       end
 
-      # output the path during emulation
+      # Outputs the disassembly, highlighting the lines that were executed during emulation.
+      #
       # @param [Array<String>] disasm
-      # @param [Set] trace
-      # @param [{Symbol => Object}] result
+      #   Lines of the disassembly, including the two header lines.
+      # @param [Set<Integer>] trace
+      #   Line numbers that were reached.
+      # @param [{Symbol => Integer}] result
+      #   The emulation result, as returned by {SeccompTools::Emulator#run}.
+      # @return [void]
       def output_emulate_path(disasm, trace, result)
         output { disasm.shift }
         output { disasm.shift }
@@ -87,7 +110,7 @@ module SeccompTools
 
             Util.colorize(line, t: :gray)
           end
-          # Too much remain, omit them.
+          # Too many lines remain; omit them.
           rem = disasm.size - idx - 1
           break output { Util.colorize("... (omitting #{rem} lines)\n", t: :gray) } if rem > 3 && idx > result[:pc] + 4
         end

data/lib/seccomp-tools/cli/explain.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
+require 'seccomp-tools/disasm/disasm'
+require 'seccomp-tools/explain'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'explain' command.
+    class Explain < Base
+      include FilterInput
+
+      # Summary of this command.
+      SUMMARY = 'Summarize a seccomp filter as a per-action policy.'
+      # Usage of this command.
+      USAGE = "explain - #{SUMMARY}\n\nUsage: seccomp-tools explain [options] [BPF_FILE|EXEC]".freeze
+
+      # Define option parser.
+      # @return [OptionParser]
+      #   The parser of this command's options.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = usage
+
+          option_filter_source(opt, 'explain')
+          option_arch(opt, 'With an executable or --pid the architecture is auto-detected instead.')
+        end
+      end
+
+      # Reads the filter(s) from a BPF file, an executable, or an existing process, then prints the
+      # policy of each.
+      # @return [void]
+      def handle
+        return unless super
+
+        filters = collect_filters
+        if filters.size > 1
+          Logger.warn("#{filters.size} filters are installed; they stack, so a syscall must pass every one " \
+                      '(most restrictive wins). Each is explained separately below.')
+        end
+        filters.each_with_index do |(raw, arch, source), idx|
+          label = filters.size > 1 ? "#{source} (filter ##{idx})" : source
+          insts = SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)
+          output { SeccompTools::Explain.new(insts, arch:, source: label).summarize.to_s }
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/filter_input.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/dumpable'
+require 'seccomp-tools/logger'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  module CLI
+    # Shared input handling for the commands that take a seccomp filter from a BPF file, stdin, an
+    # executable, or a running process ({Explain} and {Audit}): it resolves the positional argument
+    # and options into +[raw_bpf, arch, source]+ tuples, dumping via ptrace ({Dumpable}) when the
+    # input is a command or +--pid+. The including command must provide +option+, +argv+, +parser+,
+    # +input+ and +warn_ignored_arguments+ (all from {Base}).
+    module FilterInput
+      include Dumpable
+
+      private
+
+      # Registers the options every command taking its filter from a process shares - +-c/--sh-exec+,
+      # +-l/--limit+, +-p/--pid+ and +-t/--timeout+ - and their defaults, so the four stay described
+      # and parsed the same way wherever they appear. The counterpart of {Base#option_arch}.
+      #
+      # The descriptions hold for every including command, because the behaviour they describe lives
+      # in the shared code: {#collect_filters} gives +-c+ precedence, and {Dumpable#dump_seccomp}
+      # passes +--timeout+ only when running an executable, never when attaching to a +--pid+.
+      # @param [OptionParser] opt
+      # @param [String] action
+      #   What the command does with each filter, woven into the descriptions.
+      # @return [void]
+      # @example
+      #   option_filter_source(opt, 'explain')
+      def option_filter_source(opt, action)
+        option[:limit] = 1
+        opt.on('-c', '--sh-exec <command>', "Executes the given command (via sh) and #{action}s its seccomp.",
+               'Use this to pass arguments or pipe things to the executable.',
+               'e.g. use `-c "./bin > /dev/null"` to keep the program output out of the result.',
+               'Takes precedence over the positional argument.') { |command| option[:command] = command }
+
+        opt.on('-l', '--limit LIMIT', Integer, "#{action.capitalize} only the first LIMIT installed filters.",
+               'Only meaningful when the input is an executable or --pid. Default: 1',
+               'An executable is killed once it reaches LIMIT.') { |l| option[:limit] = l }
+
+        opt.on('-p', '--pid PID', Integer, "#{action.capitalize} the seccomp filters installed on an existing process.",
+               'You must have CAP_SYS_ADMIN (e.g. be root) to use this option.') { |p| option[:pid] = p }
+
+        opt.on('-t', '--timeout SEC', Float, 'Timeout (seconds) for the execution. Default: no timeout',
+               'This option is ignored when --pid is given.') { |t| option[:timeout] = t }
+      end
+
+      # Resolves the input into an array of +[raw_bpf, arch, source]+ tuples, empty when there is
+      # nothing to process (help shown, or an error was logged).
+      #
+      # The input is one of three kinds:
+      # * a running process, when +--pid+ is given;
+      # * a raw BPF file (or stdin), when the positional argument is not an executable;
+      # * a command to run and trace - either +-c+, or a positional executable.
+      # @return [Array<Array(String, Symbol, String?)>]
+      def collect_filters
+        # -c/--sh-exec and --pid take precedence over a positional BPF file or executable.
+        option[:ifile] = argv.shift unless option[:command] || option[:pid]
+        warn_ignored_arguments
+
+        return dump_filters(command: nil, pid: option[:pid], source: "pid #{option[:pid]}") if option[:pid]
+
+        command = option[:command] || option[:ifile]
+        if command.nil? # nothing to process
+          CLI.show(parser.help)
+          return []
+        end
+        return read_raw_bpf if raw_bpf_file?
+
+        dump_filters(command:, pid: nil, source: command)
+      end
+
+      # Reads the positional file (or stdin) as a raw BPF blob, logging an error instead of
+      # crashing when it cannot be read.
+      # @return [Array<Array(String, Symbol, String?)>]
+      def read_raw_bpf
+        [[input, option[:arch], source_name(option[:ifile])]]
+      rescue SystemCallError => e
+        Logger.error(e.message)
+        []
+      end
+
+      # Should the input be read directly as a raw BPF blob, rather than run as a command? True when
+      # the command accepts blobs at all, no +-c+ was given, and the positional argument is not an
+      # executable (a plain file or stdin).
+      # @return [Boolean]
+      def raw_bpf_file?
+        accepts_raw_bpf? && !option[:command] && !executable?(option[:ifile])
+      end
+
+      # Does a positional argument that is not an ELF mean "read this filter"? True for the commands
+      # that analyze a filter ({Explain}, {Audit}); {Dump} overrides it to +false+, because its
+      # positional is always something to execute - a shell script is not an ELF but must still be
+      # run, not parsed as BPF.
+      # @return [Boolean]
+      def accepts_raw_bpf?
+        true
+      end
+
+      # Dumps filters from a command or pid and labels each with +source+.
+      # @return [Array<Array(String, Symbol, String?)>]
+      #   The filter tuples, empty when dumping is unsupported or nothing was installed.
+      def dump_filters(command:, pid:, source:)
+        return [] unless dumping_supported?
+
+        dump_seccomp(command:, pid:, limit: option[:limit], timeout: option[:timeout]) do |bpf, arch|
+          [bpf, arch || option[:arch], source]
+        end
+      end
+
+      # Is +file+ an ELF executable to run, rather than a raw BPF blob or stdin to read?
+      # @param [String?] file
+      #   The path to check. +nil+ (no argument) and +-+ (stdin) are not executables.
+      # @return [Boolean]
+      def executable?(file)
+        file && file != '-' && Util.elf?(file)
+      end
+
+      # The label shown in the header for +file+; +<STDIN>+ when reading from stdin.
+      # @param [String] file
+      #   The input path, or +-+ for stdin.
+      # @return [String]
+      def source_name(file)
+        file == '-' ? '<STDIN>' : file
+      end
+    end
+  end
+end