seccomp-tools 1.6.2 → 1.7.0

data/lib/seccomp-tools/emulator.rb

@@ -3,20 +3,21 @@
 require 'seccomp-tools/const'
 
 module SeccompTools
-  # For emulating seccomp.
+  # Runs a seccomp filter against a hypothetical syscall to find out which action it returns.
   class Emulator
     # Instantiate a {Emulator} object.
     #
     # All parameters except +instructions+ are optional. A warning is shown when uninitialized data is accessed.
     # @param [Array<Instruction::Base>] instructions
-    # @param [Integer] sys_nr
+    #   The filter to be emulated, as returned by +SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)+.
+    # @param [Integer?] sys_nr
     #   Syscall number.
     # @param [Array<Integer>] args
-    #   Syscall arguments
-    # @param [Integer] instruction_pointer
-    #   Program counter address when this syscall invoked.
+    #   Syscall arguments.
+    # @param [Integer?] instruction_pointer
+    #   Program counter address when this syscall is invoked.
     # @param [Symbol?] arch
-    #   System architecture is used when this parameter is not provided.
+    #   Defaults to the system architecture when not provided.
     #
     #   See {SeccompTools::Util.supported_archs} for list of supported architectures.
     def initialize(instructions, sys_nr: nil, args: [], instruction_pointer: nil, arch: nil)
@@ -24,16 +25,27 @@ module SeccompTools
       @sys_nr = sys_nr
       @args = args
       @ip = instruction_pointer
-      @arch = audit(arch || Util.system_arch)
+      arch ||= Util.system_arch
+      @arch = audit(arch)
+      # On a big-endian architecture the high 32-bit word of a 64-bit field comes first.
+      @big_endian = Const::Endian.big?(arch)
     end
 
     # Run emulation!
+    #
+    # Executes the filter until it returns, then reports the final machine state.
+    # @yieldparam [{Symbol, Integer => Integer}] values
+    #   If a block is given, it is invoked before each instruction with the current machine state.
     # @return [{Symbol, Integer => Integer}]
+    #   The final state: +:ret+ is the action the filter returned, +:pc+ the line it returned from,
+    #   +:a+ and +:x+ the registers, and Integer keys the scratch memory slots.
+    # @example
+    #   insts = SeccompTools::Disasm.to_bpf(raw, :amd64).map(&:inst)
+    #   SeccompTools::Emulator.new(insts, sys_nr: 0).run[:ret]
+    #   #=> 2147418112 # SECCOMP_RET_ALLOW
     def run
       @values = { pc: 0, a: 0, x: 0 }
       loop do
-        break if @values[:ret] # break when returned
-
         yield(@values) if block_given?
         inst = @instructions[pc]
         op, *args = inst.symbolize
@@ -46,6 +58,8 @@ module SeccompTools
         when :alu then alu(args[0], args[1]) # alu
         when :misc then misc(args[0]) # misc: txa/tax
         end
+        break if @values[:ret] # break when returned
+
         set(:pc, get(:pc) + 1) if %i[ld st alu misc].include?(op)
       end
       @values
@@ -101,6 +115,9 @@ module SeccompTools
         set(:a, (2**32) - get(:a))
       else
         src = get(:x) if src == :x
+        # Classic BPF aborts the whole program on division by zero.
+        return set(:ret, Const::BPF::ACTION[:KILL_THREAD]) if op == :/ && src.zero?
+
         set(:a, get(:a).__send__(op, src))
       end
     end
@@ -140,20 +157,28 @@ module SeccompTools
     end
 
     def data_of(index)
-      raise IndexError, "Invalid index: #{index}" unless index.nobits?(3) && index.between?(0, 63)
+      data = Const::BPF::SeccompData
+      raise IndexError, "Invalid index: #{index}" unless index.nobits?(3) && index.between?(0, data::SIZE - 1)
 
       index /= 4
       case index
-      when 0 then @sys_nr || undefined('sys_number')
-      when 1 then @arch || undefined('arch')
-      when 2 then (@ip & 0xffffffff) || undefined('instruction_pointer')
-      when 3 then (@ip >> 32) || undefined('instruction_pointer')
+      when 0 then @sys_nr || undefined(data::NAMES[data::SYS_NUMBER])
+      when 1 then @arch || undefined(data::NAMES[data::ARCH])
+      when 2, 3 then word_of(@ip || undefined(data::NAMES[data::INSTRUCTION_POINTER]), index)
       else
         val = @args[(index - 4) / 2] || undefined("args[#{(index - 4) / 2}]")
-        (val >> (index.even? ? 0 : 32)) & 0xffffffff
+        word_of(val, index)
       end
     end
 
+    # The 32-bit word of the 64-bit value +val+ that lives at word-index +index+ of
+    # +seccomp_data+: the high word comes second on little-endian architectures but first on
+    # big-endian ones (s390x).
+    def word_of(val, index)
+      hi = index.odd? ^ @big_endian
+      (val >> (hi ? 32 : 0)) & 0xffffffff
+    end
+
     def undefined(var)
       raise format("Undefined Variable\n\t%04d: %s <- `%s` is undefined", pc, @instructions[pc].decompile, var)
     end

data/lib/seccomp-tools/error.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module SeccompTools
-  # Base error class.
+  # Base class of all errors raised by this library.
+  #
+  # Rescue this class to catch every assembler error at once.
   class Error < StandardError
   end
 
@@ -9,7 +11,7 @@ module SeccompTools
   class UnrecognizedTokenError < Error
   end
 
-  # Raised when a referred label is defined no where on compiling seccomp assembly.
+  # Raised when a referenced label is defined nowhere on compiling seccomp assembly.
   class UndefinedLabelError < Error
   end
 

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/path_facts'
+require 'seccomp-tools/explain/verdict'
+
+module SeccompTools
+  class Explain
+    # What a walk of one filter amounts to: the reachable returns, each one's facts read once, and
+    # the split into the architectures the filter distinguishes.
+    #
+    # Everything that reads a walk needs the same groundwork - {Summary} to render a per-architecture
+    # policy, {Audit} to assess each architecture's reachable syscalls - so it is derived here once
+    # rather than in each of them.
+    class Analysis
+      # @param [Array<Symbolic::Executor::Leaf>] leaves
+      def initialize(leaves)
+        @leaves = leaves
+        @facts = Hash.new { |h, leaf| h[leaf] = PathFacts.new(leaf.path) }
+      end
+
+      # The {PathFacts} of +leaf+, computed once and shared across all consumers.
+      # @param [Symbolic::Executor::Leaf] leaf
+      # @return [PathFacts]
+      def facts(leaf)
+        @facts[leaf]
+      end
+
+      # The distinct architecture values (+AUDIT_ARCH_*+) the filter explicitly branches on.
+      # @return [Array<Integer>]
+      def arch_values
+        @arch_values ||= @leaves.filter_map { |l| facts(l).arch_eq }.uniq
+      end
+
+      # One entry per architecture section: its +AUDIT_ARCH+ value (+nil+ when the filter never
+      # branches on +arch+), the architecture symbol whose syscall names apply (+nil+ when the checked
+      # value is not one seccomp-tools knows), a display title, and the leaves reachable on it.
+      # @param [Symbol] declared_arch
+      #   The architecture assumed when the filter itself does not branch on +arch+.
+      # @return [Array<Array(Integer?, Symbol?, Object, Array<Symbolic::Executor::Leaf>)>]
+      def sections(declared_arch)
+        vals = arch_values
+        return [[nil, declared_arch, declared_arch, @leaves]] if vals.empty?
+
+        vals.map do |v|
+          sym = Const::Audit.arch_symbol(v)
+          [v, sym, sym || format('0x%x (unknown)', v), @leaves.select { |l| facts(l).arch_consistent?(v) }]
+        end
+      end
+
+      # Leaves reachable when +arch+ is none of the explicitly-checked values.
+      # @return [Array<Symbolic::Executor::Leaf>]
+      def other_leaves
+        @leaves.reject { |l| facts(l).arch_eq }
+      end
+
+      # The catch-all action of +leaves+: the verdict of a leaf that matches no syscall, no range and
+      # no arguments (or the first leaf, if none is a pure catch-all), or +nil+ when +leaves+ is empty.
+      # @param [Array<Symbolic::Executor::Leaf>] leaves
+      # @return [String?]
+      def default_label(leaves)
+        catch_all = leaves.find { |l| facts(l).catch_all? }
+        (catch_all || leaves.first)&.then { |l| Verdict.label(l.ret) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/symbolic/constraint'
+
+module SeccompTools
+  class Explain
+    # The seccomp reading of one leaf's path condition: which syscall number it pins or bounds,
+    # which architecture value it pins, and which facts remain for the rule's +when+ clause. The
+    # path is immutable, so every query is derived once, eagerly.
+    class PathFacts
+      SYS = Const::BPF::SeccompData::SYS_NUMBER
+      ARCH = Const::BPF::SeccompData::ARCH
+      # Largest 32-bit value, the upper end of an unconstrained syscall-number range.
+      U32_MAX = 0xffffffff
+
+      # The syscall number the path pins with +==+, or +nil+.
+      # @return [Integer?]
+      attr_reader :sys_eq
+      # The architecture value the path pins with +==+, or +nil+.
+      # @return [Integer?]
+      attr_reader :arch_eq
+      # The +[lo, hi]+ range (inclusive; +hi+ is +nil+ when unbounded) all bound facts restrict the
+      # syscall number to, or +nil+ when there is no lower bound. An upper bound alone does not
+      # make a range rule: it is the complement of one (e.g. the +sys < 0x40000000+ side of an x32
+      # guard) and reads naturally as part of the default bucket.
+      # @return [Array(Integer, Integer?)?]
+      attr_reader :sys_range
+      # Constraints not already conveyed by the syscall-number / architecture presentation.
+      #
+      # Consumed (dropped): +==+, +!=+ and range facts on +sys_number+ - the named/ranged buckets
+      # and the "any other syscall" default wording express them; +==+/+!=+ facts on +arch+ - the
+      # per-architecture sections and the "any other" fall-through express them; and any non-+==+
+      # fact on a word that some +==+ on the same path already pins (it is then redundant - a
+      # contradicting combination would have been pruned as infeasible).
+      #
+      # Everything else is kept so a kernel-valid check is never silently dropped: bit-tests on an
+      # unpinned +sys_number+ (e.g. an odd/even dispatch), bit-tests or ranges on +arch+ (e.g.
+      # testing the +__AUDIT_ARCH_64BIT+ flag instead of pinning one value), and any comparison
+      # against a register rather than a constant.
+      # @return [Array<Symbolic::Constraint>]
+      attr_reader :residual
+
+      # @param [Array<Symbolic::Constraint>] path
+      def initialize(path)
+        @path = path
+        @sys_eq = eq(SYS)
+        @arch_eq = eq(ARCH)
+        @sys_range = compute_sys_range
+        @residual = compute_residual
+      end
+
+      # Is the path consistent with the architecture being +val+? Every constant arch fact is
+      # evaluated against +val+.
+      # @param [Integer] val
+      # @return [Boolean]
+      def arch_consistent?(val)
+        @path.all? do |c|
+          next true unless c.plain_data_fact?(ARCH)
+
+          Symbolic::Constraint.evaluate(val, c.op, c.rhs.val)
+        end
+      end
+
+      # Does the path match no syscall, no range, and no arguments - i.e. describe the filter's
+      # catch-all behavior?
+      # @return [Boolean]
+      def catch_all?
+        sys_eq.nil? && sys_range.nil? && residual.empty?
+      end
+
+      private
+
+      # The value of the single +data[offset] == k+ fact, if any.
+      def eq(offset)
+        @path.find { |c| c.plain_data_eq?(offset) }&.rhs&.val
+      end
+
+      def compute_sys_range
+        lo = nil
+        hi = nil
+        @path.each do |c|
+          next unless c.plain_data_fact?(SYS)
+
+          case c.op
+          when :> then lo = [lo || 0, c.rhs.val + 1].max
+          when :>= then lo = [lo || 0, c.rhs.val].max
+          when :< then hi = [hi || U32_MAX, c.rhs.val - 1].min
+          when :<= then hi = [hi || U32_MAX, c.rhs.val].min
+          end
+        end
+        lo && [lo, hi]
+      end
+
+      def compute_residual
+        pinned = @path.filter_map { |c| c.lhs.offset if c.plain_data_eq? }
+        @path.reject do |c|
+          next false unless c.plain_data_fact?
+
+          redundant = c.op != :== && pinned.include?(c.lhs.offset)
+          case c.lhs.offset
+          when SYS then redundant || !%i[set unset].include?(c.op)
+          when ARCH then redundant || %i[== !=].include?(c.op)
+          else redundant
+          end
+        end.uniq(&:key)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+
+module SeccompTools
+  class Explain
+    # A 64-bit fact reassembled from 32-bit word checks (see {QwordFusion}); +base+ is the field's
+    # byte offset in +seccomp_data+.
+    Qword = Struct.new(:base, :op, :val) do
+      # Mirrors {Symbolic::Constraint#key} (a string) so fused condition lists can still be compared;
+      # the +q+ prefix keeps it distinct from any constraint key, which starts with an operand char.
+      def key
+        "q#{base},#{op},#{val}"
+      end
+
+      # A {Qword} is a whole-field fact, never a single plain-word one, so it matches neither
+      # predicate. Defining them lets the fusion code treat a mixed list uniformly, without an
+      # +is_a?+ guard on every access.
+      def plain_data_fact?(_offset = nil) = false
+      alias_method :plain_data_eq?, :plain_data_fact?
+    end
+
+    # A 64-bit field of +seccomp_data+ (+instruction_pointer+ or an argument) is two 32-bit words,
+    # and filters check them separately. This class fuses such word facts back into 64-bit ones
+    # ({Qword}), both within one path condition ({#fold}) and across the sibling or-branches
+    # libseccomp compiles a 64-bit range comparison into ({#merge_or}).
+    class QwordFusion
+      # Byte offsets of the 64-bit fields whose two 32-bit words this class fuses.
+      BASES = Const::BPF::SeccompData::QWORD_BASES
+      # How the extra facts of two sibling or-branches fuse into one 64-bit comparison: one branch
+      # holds a strict high-word fact +hi <hi_op> H+ (+hi_op+ is +>+, +<+ or +!=+, normalized by
+      # {#strict}) and the other +hi == H && lo <lo_op> L+; keyed by +[hi_op, lo_op]+, they are
+      # exactly +field <fused op> (H << 32 | L)+. This is the shape libseccomp compiles
+      # SCMP_CMP_GT/GE/LT/LE/NE argument comparisons into.
+      OR_MERGE = {
+        %i[> >] => :>, %i[> >=] => :>=, %i[< <] => :<, %i[< <=] => :<=, %i[!= !=] => :!=
+      }.freeze
+
+      # @param [Symbol] arch
+      #   Decides the word order: on a big-endian architecture the high 32-bit word of a 64-bit
+      #   field comes first.
+      def initialize(arch)
+        @hi_first = Const::Endian.big?(arch)
+      end
+
+      # The byte offset of the low 32-bit word of the 64-bit field at +base+.
+      def lo_off(base)
+        @hi_first ? base + 4 : base
+      end
+
+      # The byte offset of the high 32-bit word of the 64-bit field at +base+.
+      def hi_off(base)
+        @hi_first ? base : base + 4
+      end
+
+      # The byte offset of the 64-bit field that the word at +offset+ belongs to.
+      def base_of(offset)
+        offset - (offset % 8)
+      end
+
+      # Fuses the 32-bit word facts of one path condition into whole-field {Qword}s; facts that do
+      # not form a fusable pair pass through unchanged.
+      # @param [Array<Symbolic::Constraint, Qword>] constraints
+      # @return [Array<Symbolic::Constraint, Qword>]
+      # @example Both halves pinned by == (little-endian: args[0] lo word @16, hi @20)
+      #   fold([ data[20] == 0x1, data[16] == 0x2 ])
+      #   #=> [ Qword(base: 16, op: :==, val: 0x100000002) ]
+      # @example A zero high word with a low-word bound
+      #   fold([ data[20] == 0x0, data[16] < 0x1000 ])
+      #   #=> [ Qword(base: 16, op: :<, val: 0x1000) ]
+      def fold(constraints)
+        plan = qword_plan(constraints)
+        constraints.filter_map do |c|
+          action = plan[c]
+          next if action == :drop
+
+          action || c
+        end
+      end
+
+      # Fuses sibling or-branches that together express one 64-bit comparison, repeatedly until
+      # nothing fuses; branches that do not pair up are returned untouched. See {#fuse_pair} for
+      # the shape of a fusable pair.
+      # @param [Array<Array<Symbolic::Constraint, Qword>>] lists
+      #   The condition lists of one rule's or-branches.
+      # @return [Array<Array<Symbolic::Constraint, Qword>>]
+      # @example The two match branches of a 64-bit +args[0] > 0x200000500+ (little-endian: lo @16, hi @20)
+      #   merge_or([ [ data[20] > 2 ],
+      #              [ data[20] == 2, data[16] > 0x500 ] ])
+      #   #=> [ [ Qword(base: 16, op: :>, val: 0x200000500) ] ]
+      def merge_or(lists)
+        lists = lists.dup # own a mutable copy; the caller's array is left untouched
+        loop { break unless merge_one_pair!(lists) }
+        lists
+      end
+
+      private
+
+      # Maps each constraint to what {#fold} should do with it: a {Qword} to replace it with, or
+      # +:drop+ to remove it. A constraint absent from the plan is kept as-is.
+      def qword_plan(constraints)
+        eqs = constraints.select(&:plain_data_eq?).group_by { |c| c.lhs.offset }.transform_values(&:first)
+        plan = {}
+        BASES.each do |base|
+          hi = eqs[hi_off(base)]
+          next unless hi
+
+          if (lo = eqs[lo_off(base)])
+            plan[lo] = Qword.new(base, :==, (hi.rhs.val << 32) | lo.rhs.val)
+          elsif hi.rhs.val.zero? && (lo = lo_bound(constraints, base))
+            plan[lo] = Qword.new(base, lo.op, lo.rhs.val)
+          else
+            next
+          end
+          plan[hi] = :drop
+        end
+        plan
+      end
+
+      # The +lo < L+ / +lo <= L+ fact on the low word of the field at +base+, if any.
+      def lo_bound(constraints, base)
+        constraints.find { |c| c.plain_data_fact?(lo_off(base)) && %i[< <=].include?(c.op) }
+      end
+
+      # Fuses the first fusable pair of +lists+ in place - dropping the two branches and putting the
+      # fused one at the earlier slot - and returns it, or +nil+ when no pair fused.
+      def merge_one_pair!(lists)
+        lists.each_with_index do |a, i|
+          lists.each_with_index do |b, j|
+            next if i == j
+
+            fused = fuse_pair(a, b)
+            next unless fused
+
+            lo, hi = [i, j].minmax
+            lists[lo] = fused
+            lists.delete_at(hi)
+            return fused
+          end
+        end
+        nil
+      end
+
+      # Fuses two sibling or-branches into one 64-bit fact. It applies when +a+'s only extra fact
+      # (vs +b+) is a strict high-word fact +hi <op> H+, and +b+'s two extras are +hi == H+ plus a
+      # bound on the matching low word: that pair in +b+ is then replaced by the fused {Qword} (see
+      # {OR_MERGE}).
+      # @param [Array<Symbolic::Constraint, Qword>] a
+      #   One or-branch's condition list.
+      # @param [Array<Symbolic::Constraint, Qword>] b
+      #   The sibling branch's condition list.
+      # @return [Array<Symbolic::Constraint, Qword>, nil]
+      #   +b+ with its +hi == H+ / +lo <op> L+ pair collapsed into one {Qword}, or +nil+ when the
+      #   two lists do not have the fusable shape.
+      # @example Fusing the two match paths of a 64-bit +args[0] > 0x200000500+ (little-endian: lo word @16, hi @20)
+      #   a = [ data[20] >  2 ]                    # hi > H
+      #   b = [ data[20] == 2, data[16] > 0x500 ]  # hi == H && lo > L
+      #   fuse_pair(a, b) #=> [ Qword(base: 16, op: :>, val: 0x200000500) ]
+      def fuse_pair(a, b)
+        only_a = minus(a, b)
+        return unless only_a.size == 1
+
+        hi = only_a.first
+        base = hi_field_base(hi)
+        return unless base
+
+        hi_op, hi_val = strict(hi.op, hi.rhs.val)
+        only_b = minus(b, a)
+        eq = only_b.find { |c| c.plain_data_eq?(hi.lhs.offset) && c.rhs.val == hi_val }
+        lo = only_b.find { |c| c.plain_data_fact?(lo_off(base)) }
+        return unless only_b.size == 2 && eq && lo && (op = OR_MERGE[[hi_op, lo.op]])
+
+        b.map { |c| c.equal?(eq) ? Qword.new(base, op, (hi_val << 32) | lo.rhs.val) : c }.reject { |c| c.equal?(lo) }
+      end
+
+      # The field base when +hi+ is a constant comparison on the high word of a 64-bit field;
+      # +nil+ otherwise.
+      def hi_field_base(hi)
+        return unless hi.plain_data_fact?
+
+        base = base_of(hi.lhs.offset)
+        base if BASES.include?(base) && hi.lhs.offset == hi_off(base)
+      end
+
+      # +>= v+ and +> v-1+ are the same test; normalize the high-word comparison to the strict form
+      # so {OR_MERGE} needs only one spelling. At the 32-bit boundary +val+ can step out of range
+      # (+>= 0+ to +> -1+, +<= 0xffffffff+ to +< 0x100000000+), but that is safe: the result is only
+      # matched against a data-word +==+ constant, which is masked to +0..0xffffffff+ and so can
+      # never equal it, and those boundary comparisons are always-true anyway (nothing to fuse).
+      def strict(op, val)
+        case op
+        when :>= then [:>, val - 1]
+        when :<= then [:<, val + 1]
+        else [op, val]
+        end
+      end
+
+      # The constraints in +a+ whose fact does not also appear in +b+.
+      def minus(a, b)
+        a.reject { |c| b.any? { |d| d.key == c.key } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/qword'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  class Explain
+    # Renders path-condition facts ({Symbolic::Constraint}s and {Qword}s) as C-like conditions,
+    # naming the +seccomp_data+ fields and parenthesizing exactly where the expression would
+    # otherwise be misread.
+    class Renderer
+      # C-like operator precedence (higher binds tighter), used to parenthesize a rendered condition
+      # exactly where it would otherwise be misread - notably that +==+ binds tighter than the
+      # bitwise operators, so +a & b == c+ must be shown as +(a & b) == c+.
+      PREC = {
+        :* => 12, :/ => 12, :+ => 11, :- => 11, :<< => 10, :>> => 10,
+        :< => 9, :<= => 9, :> => 9, :>= => 9, :== => 8, :!= => 8,
+        :& => 7, :^ => 6, :| => 5
+      }.freeze
+      # Unary negation binds tighter than any binary operator.
+      UNARY_PREC = 13
+      # The comparison operators. When one is the parent, operands are parenthesized by precedence
+      # alone (so +a & b == c+ becomes +(a & b) == c+ but +a >> b == c+ stays put), never by the
+      # extra readability rule in {#clarity_wrap?}.
+      COMPARISON = %i[== != < <= > >=].freeze
+      # The +seccomp_data+ field layout the rendered names come from.
+      DATA = Const::BPF::SeccompData
+
+      # @param [QwordFusion] fusion
+      #   Supplies the endian-correct word offsets of the 64-bit fields, for naming their halves.
+      def initialize(fusion)
+        @fusion = fusion
+      end
+
+      # Renders a conjunction of facts, e.g. +"fd == 0x1 && (flags & 0xf) < 0x5"+.
+      # @param [Array<Symbolic::Constraint, Qword>] constraints
+      # @param [Symbol?] sys
+      #   The syscall the facts belong to, if pinned - names the arguments.
+      # @return [String]
+      def conjunction(constraints, sys)
+        constraints.map do |c|
+          if c.is_a?(Qword)
+            "#{data_name(@fusion.lo_off(c.base), sys)} #{c.op} 0x#{c.val.to_s(16)}"
+          else
+            constraint(c, sys)
+          end
+        end.join(' && ')
+      end
+
+      private
+
+      def constraint(c, sys)
+        return "(#{binop(:&, c.lhs, c.rhs, sys)}) != 0" if c.op == :set
+        return "(#{binop(:&, c.lhs, c.rhs, sys)}) == 0" if c.op == :unset
+
+        prec = PREC[c.op]
+        "#{operand(c.lhs, c.op, prec, sys)} #{c.op} #{operand(c.rhs, c.op, prec, sys)}"
+      end
+
+      # Renders an expression without any outer parentheses; each caller wraps it via {#operand}.
+      def expr(e, sys)
+        return '<opaque>' if e.opaque?
+        return "0x#{e.val.to_s(16)}" if e.imm?
+        return data_name(e.offset, sys) if e.plain_data?
+        return "-#{operand(e.lhs, :neg, UNARY_PREC, sys)}" if e.kind == :unop
+
+        binop(e.op, e.lhs, e.rhs, sys)
+      end
+
+      # Renders +lhs op rhs+. Operators are left-associative, so the left operand shares +op+'s
+      # precedence while the right needs one higher (an equal-precedence right subtree is wrapped).
+      def binop(op, lhs, rhs, sys)
+        prec = PREC[op]
+        left = operand(lhs, op, prec, sys)
+        right = rhs.imm? && %i[<< >>].include?(op) ? rhs.val.to_s : operand(rhs, op, prec + 1, sys)
+        "#{left} #{op} #{right}"
+      end
+
+      # Renders +child+ as an operand of +parent_op+, parenthesizing it when precedence requires it
+      # (+child+ binds looser than +min_prec+) or when {#clarity_wrap?} judges the grouping too easy
+      # to misread.
+      def operand(child, parent_op, min_prec, sys)
+        s = expr(child, sys)
+        return s unless child.kind == :binop
+
+        PREC[child.op] < min_prec || clarity_wrap?(parent_op, child.op) ? "(#{s})" : s
+      end
+
+      # Should a +child_op+ nested under +parent_op+ be parenthesized purely for readability (beyond
+      # what precedence requires)? Yes when they sit at *different* precedence levels - mixing
+      # families like +a & (b + c)+ or +(a + b) << c+ is easy to misjudge. The exceptions, where the
+      # grouping is universally understood, are: any comparison parent (+a & b == c+ is already made
+      # unambiguous by wrapping the looser +&+), a same-level pair (+a + b - c+, +a ^ b ^ c+), and
+      # multiplication/division directly inside addition/subtraction (+a + b * c+).
+      def clarity_wrap?(parent_op, child_op)
+        return false if COMPARISON.include?(parent_op)
+        return false if PREC[parent_op] == PREC[child_op]
+        return false if PREC[child_op] == PREC[:*] && PREC[parent_op] == PREC[:+]
+
+        true
+      end
+
+      def data_name(offset, sys)
+        case offset
+        when DATA::SYS_NUMBER, DATA::ARCH then DATA::NAMES[offset] # the scalar fields
+        else qword_word_name(offset, sys) # endian-split fields (instruction_pointer, args)
+        end
+      end
+
+      # Names one 32-bit word of a 64-bit field, appending +>> 32+ for the high word - which is the
+      # second word on little-endian architectures but the first on big-endian ones.
+      def qword_word_name(offset, sys)
+        base = @fusion.base_of(offset)
+        return "data[#{offset}]" unless DATA::QWORD_BASES.include?(base)
+
+        name = if base == DATA::INSTRUCTION_POINTER
+                 DATA::NAMES[base]
+               else
+                 idx = (base - DATA::ARGS) / 8
+                 names = sys && Const::SYS_ARG[sys]
+                 Util.colorize((names && names[idx]) || "args[#{idx}]", t: :args)
+               end
+        offset == @fusion.hi_off(base) ? "#{name} >> 32" : name
+      end
+    end
+  end
+end