lictor 0.4.0

data/bin/lictor

@@ -0,0 +1,609 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Bootstrap the bundler context from the checkout: the CLI runs from any
+# working directory (when not already inside `bundle exec`).
+unless defined?(Bundler)
+  ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+  require "bundler/setup"
+end
+
+require "optparse"
+require "tmpdir"
+require "fileutils"
+require "json"
+require_relative "../lib/lictor"
+
+# Config first (lictor.yml in CWD), flags override it.
+options = Lictor::Config.load
+parser = OptionParser.new do |opts|
+  opts.banner = <<~USAGE
+
+    Usage: lictor <command> [options]
+
+    Commands:
+      scan <host>                 run nmap against a target (trailed)
+      acquire <target>            fetch the binary, profile it into target.facts
+      fuzz <binary>               fuzz + triage a local binary (discovery layer)
+      verify <host:port>          probe the remote with the crash input
+      harvest <host:port>         parse the banner's hex leaks into facts
+      suggest <facts> "..."       simulate a fact merge, print the delta (-o writes it)
+      plan <binary-or-facts>      profile if ELF, decide, print the recipe
+      build <binary>              measure the offset, emit the payload
+      run <target>                the closed loop: decide, execute, outcome
+      outcome <run-id>            record the result of a run
+      exploit scaffold <t> <bin>  draft a ronin exploit from measured constants
+      draft <facts>               auto-draft a technique pack into staging/
+      rule validate|install|list  teach augure a technique (data-only packs)
+      runs / report               the trail, rendered (--defender: the blue view)
+      target add|list             named targets: a dir + the registry (ADR)
+      doctor / init               verify the environment, scaffold the setup
+
+    Setup: lictor.yml in the working directory
+      (trail: runs.jsonl / nmap: / seed: / profile_cmd:). Flags override
+      the config. You are the operator: what this tool does, you did.
+      The trail is the record.
+  USAGE
+  opts.on("-s", "--seed N", Integer, "Seed for reproducible decisions") { |v| options[:seed] = v }
+  opts.on("-t", "--trail PATH", "JSONL trail (default: lictor-trail.jsonl)") { |v| options[:trail] = v }
+  opts.on("--nmap PATH", "Path to the nmap binary (default: nmap in PATH)") { |v| options[:nmap] = v }
+  opts.on("--profile-cmd PATH", "Path to augure-profile (default: augure-profile in PATH)") { |v| options[:profile_cmd] = v }
+  opts.on("--success", "Record a successful outcome (outcome only)") { options[:success] = true }
+  opts.on("--failure", "Record a failed outcome (outcome only)") { options[:success] = false }
+  opts.on("--technique NAME", "The technique the outcome applies to") { |v| options[:technique] = v }
+  opts.on("--packs DIR", "Technique packs directory (default: packs/)") { |v| options[:packs] = v }
+  opts.on("--max-inputs N", Integer, "Fuzz budget: mutated inputs to try (default 50)") { |v| options[:max_inputs] = v }
+  opts.on("--mutator NAME", "ruby (default) or radamsa if installed") { |v| options[:mutator] = v }
+  opts.on("--executor NAME", "manual (default) or ronin") { |v| options[:executor] = v }
+  opts.on("--technique NAME", "Override the technique the build implements (default: augure's pick)") { |v| options[:technique] = v }
+  opts.on("--payload FILE", "Send a pre-built payload (from `lictor build`) with run") { |v| options[:payload] = v }
+  opts.on("--shellcode-path PATH", "The flag path embedded in the shellcode stubs (build)") { |v| options[:shellcode_path] = v }
+  opts.on("--flag-regex RE", "Success oracle: the flag pattern in the runner's output (the exit code lies)") { |v| options[:flag_regex] = v }
+  opts.on("--resume RUN-ID", "Continue an interrupted run (the manifest carries the id)") { |v| options[:resume] = v }
+  opts.on("--payload-file FILE", "Custom shellcode/payload bytes for build") { |v| options[:payload_file] = v }
+  opts.on("--out FILE", "Output path for build (default payload.bin)") { |v| options[:out] = v }
+  opts.on("--repo-dir DIR", "Exploit scaffold destination directory (default: .)") { |v| options[:repo_dir] = v }
+  opts.on("--author NAME", "The scaffolded exploit's author line") { |v| options[:author] = v }
+  opts.on("--max-attempts N", Integer, "Run budget: attempts before giving up (default 3)") { |v| options[:max_attempts] = v }
+  opts.on("--facts PATH", "Facts file for run/plan (the profiler output)") { |v| options[:facts] = v }
+  opts.on("--target NAME", "Scope the state into targets/NAME (facts, payloads, trail)") { |v| options[:target] = v }
+  opts.on("--from URL", "Acquire the binary from an http(s) URL") { |v| options[:from] = v }
+  opts.on("--bin PATH", "Local binary: the acquire source, or the mirror for run auto-scaffold") { |v| options[:bin] = v }
+  opts.on("--input PATH", "Crash input for verify (the fuzzer's discovery)") { |v| options[:input] = v }
+  opts.on("--triage-backend NAME", "gdb (default), rizin or lldb") { |v| options[:triage_backend] = v }
+  opts.on("-o", "--output PATH", "Report output path, or the merged facts for suggest") { |v| options[:output] = v }
+  opts.on("-j", "--json", "Machine payload instead of human output") { options[:json] = true }
+  opts.on("--defender", "report: the blue-side view (the timeline + the packs' detection hints)") { options[:defender] = true }
+  opts.on("-h", "--help", "Show this help") { puts opts; exit 0 }
+end
+parser.parse!
+
+HELP = {
+  "recon" => "recon <nmap.xml>\n    Print service candidates from an nmap XML scan (passive).",
+  "scan" => "scan <host>\n    Run nmap against a target (trailed).",
+  "plan" => "plan <binary-or-facts>\n    Profile if ELF (augure-profile), decide, print the handoff recipe.",
+  "outcome" => "outcome <run-id> --success|--failure --technique NAME\n    Record the result; the next plan adapts the priors.",
+  "runs" => "runs\n    List the trailed runs.",
+  "report" => "report [--json] [--defender] [-o PATH]\n    The operator's report, or (--defender) the blue-side view.",
+  "rule" => "rule validate|install|list <pack.yml>\n    Teach augure a technique: data-only pack, validated + corpus-guarded.\n    install is interactive and trailed.",
+  "init" => "init\n    Scaffold lictor.yml and an example facts file.",
+  "doctor" => "doctor\n    Verify the environment; print the exact fix per check.",
+  "target" => "target add <name> <host:port> [--from URL | --bin PATH] | target list\n    A named target owns a dir: facts, payloads, its own trail. --target scopes the commands.",
+  "acquire" => "acquire <target> [--from URL | --bin PATH]\n    Fetch (or copy) the binary, check it is an ELF, profile it into target.facts.",
+  "verify" => "verify <host:port> [--input PATH]\n    Probe the remote with the crash input; a fault anchors verified(\"remote\").",
+  "fuzz" => "fuzz <binary> [--max-inputs N] [--mutator ruby|radamsa] [--triage-backend gdb]\n    Discover crashes, triage the best one, trail both.",
+  "harvest" => "harvest <host:port> [--facts PATH]\n    Parse the service banner's hex leaks into leaked_address facts.",
+  "suggest" => "suggest <facts-file> \"fact(\"atom\").\n...\" [-o PATH]\n    Simulate the fact merge, print the decision delta; -o writes the merged base.",
+  "run" => "run <target> --facts PATH [--executor manual|ronin] [--payload FILE]\n    The closed loop: decide, execute (or hand off), outcome, re-decide.",
+  "build" => "build <binary> [--facts PATH] [-o payload.bin]\n    Measure the offset, resolve the addresses from the facts, emit the payload.",
+  "exploit" => "exploit scaffold <technique> <binary>\n    Draft a ronin exploit from the measured constants into your repo.",
+  "draft" => "draft <facts> [--bin PATH]\n    Auto-draft a technique pack from the facts into staging/."
+}.freeze
+
+if ARGV[0] == "help"
+  verb = ARGV[1]
+  abort("lictor: no such command '#{verb}' (see lictor --help)") unless HELP[verb]
+  puts HELP[verb]
+  exit 0
+end
+
+options[:technique] = nil unless options.key?(:technique)
+options[:success] = nil unless options.key?(:success)
+command = ARGV.shift or abort(parser.to_s)
+
+when_state = if options[:target]
+  entry = Lictor::Targets.resolve(options[:target])
+  entry[:dir]
+else
+  "."
+end
+options[:trail] ||= File.join(when_state, "trail.jsonl")
+if options[:target]
+  options[:facts] ||= File.join(when_state, "target.facts")
+  options[:out] ||= File.join(when_state, "payload.bin")
+end
+trail = Lictor::Trail.new(options[:trail])
+
+def scaffold_files
+  {
+    "lictor.yml" => <<~YML,
+      # lictor setup - flags override these values
+      trail: lictor-trail.jsonl
+    YML
+  }
+end
+
+case command
+when "init"
+  scaffold_files.each do |name, content|
+    path = File.join(Dir.pwd, name)
+    if File.exist?(path)
+      abort("lictor: #{name} already exists - keep your setup, run `lictor doctor`")
+    end
+  end
+  scaffold_files.each do |name, content|
+    dir = File.dirname(File.join(Dir.pwd, name))
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(Dir.pwd, name), content)
+  end
+  # The one example that proves the pipeline: straight from the corpus.
+  # Same resolution as the Gemfile: dev sibling or CI in-tree checkout.
+  FileUtils.mkdir_p("examples")
+  corpus_candidates = [
+    File.expand_path("../../augure/lib/augure/ctf_corpus.json", __dir__),
+    File.expand_path("../augure/lib/augure/ctf_corpus.json", __dir__)
+  ]
+  augure_corpus = corpus_candidates.find { |p| File.file?(p) }
+  if augure_corpus
+    entry = JSON.parse(File.read(augure_corpus))["suites"]["ropemporium"].find { |e| e["name"] == "ret2win" }
+    File.write("examples/ret2win.facts", entry["facts"]) if entry
+  end
+  scaffolded = ["lictor.yml"]
+  scaffolded << "examples/ret2win.facts" if File.file?("examples/ret2win.facts")
+  puts "scaffolded: #{scaffolded.join(", ")}"
+  puts
+  puts "next:"
+  puts "  1. lictor doctor                     # verify the environment"
+  puts "  2. lictor plan examples/ret2win.facts   # your first decision"
+when "target"
+  sub = ARGV.shift or abort(parser.to_s)
+  case sub
+  when "add"
+    name = ARGV.shift or abort(parser.to_s)
+    host = ARGV.shift or abort(parser.to_s)
+    info = Lictor::Targets.add(name, host, from: options[:from], bin: options[:bin])
+    puts "target:     #{name} (#{info[:registry]["host"]})"
+    puts "dir:        #{info[:dir]}/ (facts, payloads, trail - scoped)"
+    puts "registry:   #{Lictor::Targets::REGISTRY}"
+    puts "next:       lictor acquire #{name} --target #{name} --from <url>"
+  when "list"
+    Lictor::Targets.load.each { |name, entry| puts "#{name}\t#{entry["host"]}" }
+  else
+    abort("lictor: target add|list")
+  end
+when "doctor"
+  checks = []
+  checks << ["ruby >= 3.4", RUBY_VERSION >= "3.4" ? nil : "upgrade ruby (mise install ruby@3.4)"]
+  nmap = options[:nmap] || "nmap"
+  nmap_found = system(nmap, "--version", out: File::NULL, err: File::NULL)
+  checks << ["nmap binary", nmap_found ? nil : "install nmap (apt install nmap) or set nmap: in lictor.yml"]
+  profiler = options[:profile_cmd] || Lictor::Profiler::DEFAULT_CMD
+  # Same candidate resolution as init's corpus: dev sibling or CI in-tree.
+  profiler_candidates = [
+    File.expand_path("../../augure/profiler/exe/augure-profile", __dir__),
+    File.expand_path("../augure/profiler/exe/augure-profile", __dir__)
+  ]
+  # Availability only: missing gems at runtime are ProfilerError's job.
+  profiler_found = [profiler, *profiler_candidates].find do |c|
+    system("sh", "-c", "command -v '#{c}' >/dev/null 2>&1")
+  end
+  checks << ["augure-profile",
+             profiler_found ? nil : "gem install augure-profiler (or set profile_cmd: in lictor.yml)"]
+  config_path = "lictor.yml"
+  checks << ["lictor.yml", File.file?(config_path) ? nil : "run `lictor init`"]
+  # optional tooling: warned, never failed - plan/report run without them
+  @optional = []
+  gdb_found = system("sh", "-c", "command -v gdb >/dev/null 2>&1")
+  @optional << ["gdb binary", gdb_found ? nil : "install gdb (apt install gdb) - the offset measurement, fuzz and triage need it"]
+  ronin_found = system("sh", "-c", "gem list -i ronin-exploits >/dev/null 2>&1")
+  @optional << ["ronin-exploits (run executor)", ronin_found ? nil : "gem install ronin-exploits - only the ronin executor needs it"]
+  docker_found = system("sh", "-c", "command -v docker >/dev/null 2>&1")
+  @optional << ["docker (the lab)", docker_found ? nil : "install docker to run the lab bench - optional outside the lab"]
+
+  trail_path = options[:trail] || Lictor::Config.load[:trail] || "lictor-trail.jsonl"
+  writable = begin
+    File.open(trail_path, "a") { |f| f.write("") }
+    true
+  rescue StandardError
+    false
+  end
+  checks << ["trail writable: #{trail_path}", writable ? nil : "check directory permissions"]
+
+  failed = false
+  checks.each do |name, problem|
+    if problem
+      failed = true
+      puts "  FAIL  #{name} - fix: #{problem}"
+    else
+      puts "  ok    #{name}"
+    end
+  end
+  @optional.each do |name, problem|
+    if problem
+      puts "  warn  #{name} - note: #{problem}"
+    else
+      puts "  ok    #{name}"
+    end
+  end
+  if failed
+    n = checks.count { |_, p| p }
+    abort("lictor: doctor found #{n} issue(s) - fixes above (fresh setup? run lictor init)")
+  end
+when "recon"
+  xml = ARGV.shift or abort(parser.to_s)
+  puts Lictor::Recon.service_candidates(xml)
+when "rule"
+  sub = ARGV.shift or abort(parser.to_s)
+  packs_dir = options[:packs] || Lictor::Config.load[:packs] || "packs"
+  case sub
+  when "list"
+    Dir.glob(File.join(packs_dir, "*.{yml,yaml}")).sort.each do |p|
+      pack = Augure::PackLoader.load_file(p)
+      puts "#{pack.technique}  by #{pack.author}  (#{p})"
+    end
+  when "validate", "install"
+    path = ARGV.shift or abort("lictor: rule #{sub} <pack.yml>")
+    begin
+      pack = Augure::PackLoader.load_file(path)
+      Augure::PackLoader.corpus_guard([pack])
+    rescue Augure::PackError => e
+      abort("lictor: pack refused - #{e.message}")
+    end
+    puts "pack:       #{pack.technique}"
+    puts "author:     #{pack.author}"
+    puts "source:     #{pack.source}"
+    puts "corpus:     all 34 documented verdicts intact"
+    if sub == "validate"
+      puts "verdict:    valid (dry-run; `lictor rule install #{path}` to teach augure)"
+    else
+      # Interactive confirmation: friction with information. Type the
+      # technique name - a flag can be typed by reflex, this cannot.
+      print "type the technique name to confirm: "
+      confirm = $stdin.gets.to_s.strip
+      abort("lictor: confirmation mismatch - nothing installed") unless confirm == pack.technique
+      FileUtils.mkdir_p(packs_dir)
+      installed = File.join(packs_dir, File.basename(path))
+      FileUtils.cp(path, installed)
+      trail.record(run: SecureRandom.uuid, type: "rule_install", technique: pack.technique,
+                   author: pack.author, source: pack.source, pack_file: installed)
+      puts "installed:  #{installed} (trailed)"
+      puts "next plan run will consider #{pack.technique}"
+    end
+  else
+    abort("lictor: rule validate|install|list")
+  end
+when "verify"
+  # The differential: the fuzzer's crash input goes to the REMOTE
+  # service. If the remote faults like the local model, the model is
+  # remote-verified (the facts carry the confidence level).
+  target = ARGV.shift or abort(parser.to_s)
+  abort("lictor: verify needs --input <crash-input-file> (lictor fuzz discovers it)") unless options[:input]
+  # Remote crash detection: deliver the input, then read until the
+  # connection dies. A crashed child dies IN vuln_copy: the normal path
+  # prints "hello" first, the crash path does not. A reset = death too.
+  # The socket work is the Tube's (ADR lictor 0001).
+  host, port = target.split(":", 2)
+  begin
+    tube = Lictor::Tube.tcp(host, port, timeout: 5)
+    tube.gets("\n") # the greeting, if any
+    tube.write(File.binread(options[:input]))
+    reply = tube.read_bytes(limit: 4096)
+    reset_seen = tube.reset?
+    tube.close
+  rescue Lictor::TubeError => e
+    reset_seen = false
+    reply = ""
+    puts "  (the connection itself failed: #{e.message})"
+  end
+  crashed = (reset_seen || reply.empty?) && !reply.include?("hello")
+  trail.record(run: SecureRandom.uuid, type: "verify", target: target,
+               input: options[:input], remote_crashed: crashed)
+  if crashed
+    puts "remote-verified: the remote service faulted on the same input -"
+    puts "  the local model (offsets, gadgets) is representative. The facts"
+    puts "  gained verified(\"remote\")."
+    facts_path = options[:facts] || "target.facts"
+    File.open(facts_path, "a") { |f| f.puts 'verified("remote").' }
+  else
+    puts "not verified: the remote survived - the local model may not apply"
+    puts "  (version drift? a different build?). Do not trust the offsets."
+  end
+when "fuzz"
+  # Fuzzing is an ACTION on a local binary: TRAILED, and its discoveries
+  # feed the plan.
+  binary = ARGV.shift or abort(parser.to_s)
+  begin
+    require "augure-profiler"
+    binary = File.expand_path(binary)
+  rescue LoadError
+    abort("lictor: fuzzing needs the augure-profiler gem (gem install augure-profiler)")
+  end
+  crashes = AugureProfiler::Fuzzer.run(binary, inputs: options[:max_inputs] || 50,
+                                       mutator: (options[:mutator] || :ruby).to_sym)
+  trail.record(run: SecureRandom.uuid, type: "fuzz", binary: binary,
+               inputs: options[:max_inputs] || 50, crashes: crashes.size)
+  if crashes.empty?
+    puts "fuzzed:   #{binary} - no crash (nothing to triage)"
+  else
+    puts "fuzzed:   #{binary} - #{crashes.size} crash(es)"
+    # The LONGEST crash input is the most robust across environments
+    # (it smashes past any offset): the shortest may be a marginal,
+    # layout-dependent crash - exactly what `verify` is there to catch.
+    robust = crashes.max_by { |c| c[:input].bytesize }
+    crash_file = File.join(Dir.pwd, "crash-input.bin")
+    File.binwrite(crash_file, robust[:input])
+    puts "saved:    #{crash_file} (the longest crash input - robust for verify)"
+    triage = AugureProfiler::Triage.run(binary, robust[:input])
+    trail.record(run: SecureRandom.uuid, type: "triage", binary: binary,
+                 signal: triage[:signal], control: triage[:control].to_s)
+    puts "triage:   #{triage[:signal]} control=#{triage[:control]}"
+    facts_text = AugureProfiler::Triage.facts(triage)
+    puts facts_text
+    puts "next:     lictor plan <binary>  (facts above are decidable)"
+  end
+when "run"
+  # The closed loop, opt-in: decide -> execute -> outcome -> re-decide.
+  target = ARGV.shift or abort(parser.to_s)
+  abort("lictor: run needs --facts <facts-file> (scan/profile first)") unless options[:facts]
+  executor_kind = (options[:executor] || :manual).to_sym
+
+    result = Lictor::Run.run(target: target, facts: File.read(options[:facts]), trail: trail,
+                             executor: Lictor::Executor.resolve(executor_kind),
+                             max_attempts: options[:max_attempts] || 3,
+                             packs: Lictor::TechniquePacks.load(options[:packs] || Lictor::Config.load[:packs] || "packs"),
+                             payload: options[:payload],
+                             seed: options[:seed],
+                             binary: options[:bin],
+                             repo_dir: options[:repo_dir],
+                             flag_regex: options[:flag_regex],
+                             manifest_path: File.join(when_state, "run.json"),
+                             resume: options[:resume],
+                             technique: options[:technique])
+  puts "run:     #{result[:run_id]}  (interrupted? resume: lictor run ... --resume #{result[:run_id]})"
+  puts "status:  #{result[:status]}"
+  result[:steps].each do |s|
+    executed = s[:executed] ? "executed" : "handoff"
+    ok = s[:success] ? "success" : (s[:success].nil? ? "-" : "failed")
+    puts "  #{s[:technique]} [#{executed}/#{ok}]"
+  end
+  # The flag in the output is the proof the loop actually closed - the
+  # exit code lies, the flag does not.
+  flag = result[:steps].filter_map { |s| s[:flag] }.first
+  puts "flag:    #{flag}" if flag
+when "acquire"
+  # The nmap -> binary bridge: local copy or http download, ELF-checked,
+  # profiled, trailed.
+  target = ARGV.shift or abort(parser.to_s)
+  # the registry carries the source: --from/--bin override, the
+  # target's recorded `from`/`bin` is the fallback (the engagement
+  # flow: one `target add` and the acquire needs no flags)
+  source = options[:from] || (options[:bin] && "local:#{options[:bin]}")
+  source ||= begin
+    entry = Lictor::Targets.resolve(target)
+    (entry[:from] || (entry[:bin] && "local:#{entry[:bin]}"))
+  rescue ArgumentError
+    nil
+  end
+  source or abort("lictor: acquire needs --from <url> or --bin <path> (or a target add --from/--bin)")
+  result = Lictor::Acquisition.acquire(target, source: source, trail: trail,
+                                       out_dir: when_state,
+                                       profiler_cmd: options[:profile_cmd])
+  puts "acquired:   #{result[:binary_path]}"
+  puts "facts:      #{result[:facts_path]} (#{result[:facts].lines.size} facts)"
+  puts "next:       lictor plan target.facts"
+when "scan"
+  # A scan is an ACTION, trailed.
+  target = ARGV.shift or abort(parser.to_s)
+  out_xml = File.join(Dir.mktmpdir("lictor_scan"), "scan.xml")
+  begin
+    targets = Lictor::Scanner.run(target, out: out_xml, nmap_cmd: options[:nmap] || "nmap")
+  rescue Lictor::ScanError => e
+    abort("lictor: #{e.message}")
+  end
+  trail.record(run: SecureRandom.uuid, type: "scan", target: target,
+               nmap_args: [options[:nmap] || "nmap", *Lictor::Scanner::NMAP_ARGS])
+  puts "scanned: #{target}"
+  targets.each do |t|
+    puts "#{t[:host]}:#{t[:port]}  #{t[:service]}#{t[:product] ? " (#{t[:product]} #{t[:version]})" : ''}"
+  end
+when "suggest"
+  facts_path = ARGV.shift or abort(parser.to_s)
+  suggested = ARGV.shift or abort("lictor: suggest <facts-file> \"fact(\\\"atom\\\").\\n...\" - the suggestion text")
+  begin
+    result = Lictor::Suggestion.apply(base_facts: File.read(facts_path), suggested: suggested,
+      trail: trail, target: facts_path, seed: options[:seed],
+      packs: Lictor::TechniquePacks.load(options[:packs] || Lictor::Config.load[:packs] || "packs"))
+  rescue Augure::MalformedFact, Augure::UnknownPredicate => e
+    abort("lictor: #{e.message}")
+  end
+  puts "added:      #{result[:added].inspect}"
+  puts "applicable: #{result[:applicable_before].join(', ')}  ->  #{result[:applicable_after].join(', ')}"
+  puts "selected:   #{result[:selected_before].inspect}  ->  #{result[:selected_after].inspect}"
+  if options[:output]
+    File.write(options[:output], result[:facts].to_s)
+    puts "written:    #{options[:output]} (the merged base - the enrichment is not a dry run)"
+  end
+when "harvest"
+  target = ARGV.shift or abort(parser.to_s)
+  begin
+    result = Lictor::Harvest.harvest(target, trail: trail,
+      timeout: options[:timeout] || 5, read_bytes: 512)
+    puts "leaked:     #{result[:addresses].map { |k, v| "#{k}=#{format('0x%x', v)}" }.join(', ')}"
+    if options[:facts]
+      File.open(options[:facts], "a") { |f| f.write(result[:facts]) }
+      puts "appended:   #{options[:facts]} (leaked_address facts, observed-live)"
+    else
+      puts "facts:      merge them with lictor suggest or pass --facts PATH to append"
+    end
+  rescue Lictor::Harvest::HarvestError => e
+    abort("lictor: #{e.message}")
+  end
+when "exploit"
+  sub = ARGV.shift
+  abort("lictor: exploit <scaffold> ... - only scaffold is implemented") unless sub == "scaffold"
+  technique = ARGV.shift or abort(parser.to_s)
+  abort("lictor: the technique must match [a-z0-9_]+ (it becomes a filename and lands in generated code)") unless technique =~ /\A[a-z0-9_]+\z/
+  binary = ARGV.shift or abort(parser.to_s)
+  begin
+    facts_path = options[:facts] ||
+                 abort("lictor: exploit scaffold needs --facts <facts-file>")
+    result = Lictor::PayloadBuilder.build(binary: binary, facts: File.read(facts_path),
+      technique: technique, out: options[:out] || "payload.bin",
+      payload_file: options[:payload_file])
+    repo_dir = File.expand_path(options[:repo_dir] || ".")
+    FileUtils.mkdir_p(repo_dir)
+    dest = Lictor::ExploitScaffold.scaffold(technique: technique, constants: result,
+      repo_dir: repo_dir, author: options[:author] || "lictor scaffold")
+    trail.record(run: SecureRandom.uuid, type: "scaffold", technique: technique,
+      offset: result[:offset], offset_source: result[:offset_source],
+      ret: result[:ret_source], file: dest)
+    puts "scaffolded: #{dest}"
+    puts "review it, commit it, then ronin-exploits finds it by name"
+  rescue Lictor::PayloadBuilder::BuildError, Lictor::ExploitScaffold::ScaffoldError => e
+    abort("lictor: #{e.message}")
+  end
+when "draft"
+  facts_path = ARGV.shift or abort(parser.to_s)
+  binary = ARGV.shift
+  begin
+    require "augure-profiler" # lazy: metasm loads on the draft path only
+    measurements = {}
+    if binary && File.file?(binary)
+      static = AugureProfiler::StaticOffset.offset(binary) rescue nil
+      measurements[:sink] = static&.dig(:sink)
+      measurements[:offset] = static&.dig(:offset)
+      measurements[:offset_source] = static&.dig(:offset) ? "static-frame" : nil
+    end
+    measurements[:run_id] = options[:run_id] || "manual"
+    staging = options[:repo_dir] || "staging"
+    result = Lictor::PackDraft.draft(facts: File.read(facts_path),
+      measurements: measurements, staging_dir: File.expand_path(staging))
+    abort("lictor: the built-in techniques already cover these facts - no draft needed") if result.nil?
+    trail.record(run: SecureRandom.uuid, type: "pack_draft", technique: result[:technique],
+      status: result[:status], file: result[:path])
+    puts "draft:    #{result[:path]} (#{result[:technique]})"
+    puts "armor:    #{result[:status]}"
+    puts "staging:  review it, then lictor rule install once it is yours"
+  rescue Lictor::PackDraft::DraftError => e
+    abort("lictor: #{e.message}")
+  end
+when "build"
+  input = ARGV.shift or abort(parser.to_s)
+  facts_path = options[:facts]
+  unless facts_path
+    abort("lictor: build needs --facts <facts-file> (scan/profile first)") unless File.file?("target.facts")
+    facts_path = "target.facts"
+  end
+  begin
+    packs = Lictor::TechniquePacks.load(options[:packs] || Lictor::Config.load[:packs] || "packs")
+    decision = Lictor::Handoff.plan(facts: File.read(facts_path), seed: options[:seed],
+      priors: Lictor::Priors.from_trail(trail), packs: packs)
+    technique = options[:technique] || decision[:selected] or
+      abort("lictor: build needs a selected technique - plan decided nothing")
+    result = Lictor::PayloadBuilder.build(binary: input, facts: File.read(facts_path),
+                             shellcode_path: options[:shellcode_path],
+      technique: technique, out: options[:out] || "payload.bin",
+      payload_file: options[:payload_file],
+      packs: packs)
+    trail.record(run: SecureRandom.uuid, type: "build", technique: technique,
+      offset: result[:offset], ret: result[:ret_source], arch: result[:arch].to_s,
+      size: result[:size], out: result[:path])
+    puts "technique:  #{technique}"
+    puts "offset:     #{result[:offset]}  (measured: cyclic pattern under the debugger)"
+    puts "ret:        #{result[:ret_source]}"
+    puts "payload:    #{result[:path]} (#{result[:size]} bytes, arch #{result[:arch]})"
+  rescue Lictor::PayloadBuilder::BuildError => e
+    abort("lictor: #{e.message}")
+  rescue Augure::MalformedFact, Augure::UnknownPredicate => e
+    abort("lictor: #{e.message}")
+  end
+when "plan"
+  # --target: the facts default to the target's dir (the ARGV input
+  # stays for the direct path)
+  input = ARGV.shift || options[:facts] or abort(parser.to_s)
+  mode = "handoff (prints a recipe; executes nothing)"
+
+  begin
+    if Lictor::Profiler.elf?(input)
+      facts = Lictor::Profiler.run(input, cmd: options[:profile_cmd] || Lictor::Profiler::DEFAULT_CMD)
+      trail.record(run: SecureRandom.uuid, type: "profile", binary: input)
+    else
+      facts = File.read(input)
+    end
+    priors = Lictor::Priors.from_trail(trail)
+    packs = Lictor::TechniquePacks.load(options[:packs] || Lictor::Config.load[:packs] || "packs")
+    plan = Lictor::Handoff.plan(facts: facts, seed: options[:seed], priors: priors, packs: packs)
+  rescue Lictor::ProfilerError => e
+    abort("lictor: #{e.message}")
+  rescue Augure::MalformedFact, Augure::UnknownPredicate => e
+    abort("lictor: #{e.message}")
+  end
+  trail.record(run: SecureRandom.uuid, type: "plan", mode: mode, facts_file: input,
+               profiled: Lictor::Profiler.elf?(input) ? input : nil,
+               selected: plan[:selected], applicable: plan[:applicable],
+               explain: plan[:explain],
+               priors_adapted: Lictor::Priors.adapted?(trail))
+
+  if options[:json]
+    puts JSON.generate(plan)
+  else
+    puts "mode:      #{mode}"
+    puts "applicable: #{plan[:applicable].join(', ')}"
+    puts "ranking:    #{plan[:ranking].join(' > ')}"
+    puts "selected:   #{plan[:selected]}"
+    if plan[:recipe]
+      puts "recipe:     #{plan[:recipe][:console]}"
+    end
+    plan[:explain][:provenance].each do |tech, provs|
+      provs.each do |p|
+        puts "  #{tech} <- #{p[:rule]} (#{p[:evidence].map { |e| e.join('=') }.join(', ')})"
+      end
+    end
+  end
+when "outcome"
+  run_id = ARGV.shift or abort(parser.to_s)
+  if options[:success].nil? || options[:technique].nil?
+    abort("lictor: outcome needs --success or --failure, and --technique NAME")
+  end
+  trail.record(run: run_id, type: "outcome", technique: options[:technique],
+               success: options[:success])
+  puts "recorded: #{run_id} #{options[:technique]} #{options[:success] ? 'success' : 'failure'}"
+  puts "next plan run adapts the priors (the closed loop)"
+when "runs"
+  runs = trail.runs
+  abort("lictor: empty trail") if runs.empty?
+  runs.each do |r|
+    puts "#{r[:run]}  #{r[:mode]}  selected=#{r[:selected]}  " \
+         "outcomes=#{r[:outcomes].map { |o| "#{o[:technique]}:#{o[:success] ? 'ok' : 'ko'}" }.join(',')}"
+  end
+when "report"
+  if options[:defender]
+    packs = Lictor::TechniquePacks.load(options[:packs] || Lictor::Config.load[:packs] || "packs")
+    content = Lictor::Report.defender(trail, packs: packs)
+    if options[:output]
+      File.write(options[:output], content)
+      puts "wrote #{options[:output]}"
+    else
+      puts content
+    end
+  elsif options[:json]
+    puts JSON.generate(runs: trail.runs)
+  elsif options[:output]
+    Lictor::Report.to_file(options[:output], trail)
+    puts "wrote #{options[:output]}"
+  else
+    puts Lictor::Report.from_trail(trail)
+  end
+else
+  abort(parser.to_s)
+end

data/lib/config/build_layouts.yml

@@ -0,0 +1,67 @@
+# The build layouts: how a decided technique becomes bytes. Data, not
+# code - a pack can add or override a layout for its own techniques
+# (pack `build:` sections follow the same slot vocabulary and pass the
+# same armor).
+#
+# Slots:
+#   [padding, measured_offset]        - the measured offset, as filler
+#   [qword, win]                      - the win_symbol address, 8 bytes
+#   [qword, gadget:TYPE]              - the address of that gadget type
+#   [dword, ...]                      - the same, 4 bytes (x86)
+#   [shellcode, sh|bash]              - the assembled stub
+#   [shellcode, file]                 - the operator-provided payload file
+#   [chain, REF, REF, ...]            - a ROP chain: one arch-width word
+#                                       per REF, resolved in order
+#
+# chain references:
+#   gadget:TYPE      - the address of that gadget type (facts)
+#   plt_addr:NAME    - the PLT stub address (profiler facts)
+#   got_addr:NAME    - the GOT entry address (profiler facts)
+#   win              - the win_symbol address
+#   leak:NAME        - a leaked_address(name) fact (harvest/banner)
+#   const:N          - the literal N (a syscall number, an offset)
+#
+# resolved at build time from the facts + the measurement; anything the
+# facts cannot supply is a loud BuildError, never a guessed byte.
+
+ret2func:
+  arch: any
+  layout:
+    - [padding, measured_offset]
+    - [qword, win]
+
+ret2win:
+  arch: any
+  layout:
+    - [padding, measured_offset]
+    - [qword, win]
+
+shellcode:
+  arch: any
+  layout:
+    - [padding, measured_offset, sled]
+    - [qword, leak:buf]
+    - [shellcode, sh]
+
+banner_leak:
+  arch: any
+  layout:
+    - [padding, measured_offset]
+    - [qword, leak:win]
+ret2plt:
+  arch: any
+  layout:
+    - [padding, measured_offset]
+    - [chain, "gadget:pop_rdi_ret", "got_addr:puts", "plt_addr:puts"]
+
+ret2libc:
+  arch: any
+  layout:
+    - [padding, measured_offset]
+    - [chain, "gadget:ret_align", "gadget:pop_rdi_ret", "leak:binsh", "leak:system"]
+orw:
+  arch: any
+  layout:
+    - [padding, measured_offset, sled]
+    - [qword, leak:input]
+    - [shellcode, orw, flag.txt]