augure 0.1.0

data/home/runner/work/augure/augure/lib/augure/engine.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Augure
+  # Forward-chaining evaluator over a rule table. Interprets the Rules data;
+  # keeps, per derived head, the rule id and the evidence tuples that fired
+  # it. Naive fixpoint: the rule set is tiny, clarity beats semi-naive here.
+  class Engine
+    Result = Struct.new(:derived_rels, :provenance_by_head) do
+      def derived(rel)
+        derived_rels.fetch(rel, [])
+      end
+
+      def applicable
+        provenance_by_head.filter_map do |head, provs|
+          head[1] if head[0] == Rules::APPLICABLE && !provs.empty?
+        end
+      end
+
+      def provenance(technique)
+        provenance_by_head.fetch([Rules::APPLICABLE, technique], [])
+      end
+    end
+
+    OP = {lt: :<, le: :<=, gt: :>, ge: :>=, eq: :==}.freeze
+
+    def initialize(facts, rules: nil)
+      @facts = facts
+      @rules = rules || Rules.all
+    end
+
+    def run
+      rels = seeded_relations
+
+      loop do
+        fired = false
+        @rules.each do |rule|
+          head_key = [rule.head[0], rule.head[1..]]
+          evidence = satisfy(rule.conditions, rels)
+          next if evidence.empty?
+
+          # sibling rules sharing a head ALL contribute: the provenance
+          # carries every reason that fired, each attributed to its own
+          # rule (the docs promise "which reason fired" - all of them).
+          known = rels[head_key] || []
+          fresh = evidence.reject { |combo| known.any? { |(c, _)| c == combo } }
+          next if fresh.empty?
+
+          rels[head_key] = known + fresh.map { |combo| [combo, rule] }
+          fired = true
+        end
+        break unless fired
+      end
+
+      build_result(rels)
+    end
+
+    private
+
+    # key: [rel_name, tuple]; value: [[combo, rule], ...] - every firing
+    # (dedup by combo) with its own rule attribution. Input facts carry
+    # an empty evidence; defaults are seeded as inputs.
+    def seeded_relations
+      rels = {}
+      @facts.each { |(name, tuple)| rels[[name, tuple]] = [] }
+      Rules::DEFAULTS.each do |name, default|
+        rels[[name, [default]]] ||= [] if @facts.rel(name).nil?
+      end
+      rels
+    end
+
+    def tuples_for(rels, rel)
+      rels.filter_map { |(r, t), _| t if r == rel }
+    end
+
+    # Returns combos of evidence items ([rel, atom, ...] pairs) when
+    # satisfiable, [] else. A negated condition contributes an empty item.
+    def satisfy(conditions, rels)
+      combos = [[]]
+      conditions.each do |cond|
+        hits = match_condition(cond, rels)
+        return [] if hits.empty?
+
+        combos = combos.flat_map { |c| hits.map { |h| c + [h] } }
+      end
+      combos
+    end
+
+    def match_condition(cond, rels)
+      case cond[0]
+      when :fact
+        tuples_for(rels, cond[1])
+          .select { |t| t == [cond[2]] }
+          .map { |t| [cond[1], t[0]] }
+      when :not_fact
+        present = tuples_for(rels, cond[1]).any? { |t| t == [cond[2]] }
+        present ? [] : [[]]
+      when :match
+        pattern = /#{cond[3]}/
+        tuples_for(rels, cond[1])
+          .select { |t| t[cond[2]].is_a?(String) && t[cond[2]] =~ pattern }
+          .map { |t| [cond[1], *t] }
+      when :cmp
+        tuples_for(rels, cond[1])
+          .select { |t| t[0].is_a?(Integer) && t[0].public_send(OP.fetch(cond[2].to_sym), cond[3]) }
+          .map { |t| [cond[1], *t] }
+      else
+        raise EngineError, "unknown condition #{cond[0].inspect}"
+      end
+    end
+
+    def build_result(rels)
+      derived = {}
+      provs = {}
+      rels.each do |(r, t), firings|
+        # Pure input facts (empty evidence) never surface as derived outputs.
+        next if firings.empty?
+
+        (derived[r] ||= []) << t
+        key = [r, t[0]]
+        entries = provs[key] ||= []
+        firings.each do |(combo, rule)|
+          entries << {rule: rule.id, origin: rule.origin, evidence: combo.reject(&:empty?)}
+        end
+      end
+      Result.new(derived, provs)
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/facts.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Augure
+  # Strict, schema-checked parser for Augure fact files.
+  #
+  # A fact is one line: predicate("string").  or  predicate("atom", 42).
+  # The schema is the single source of truth for which predicates exist and
+  # their arity. Anything else is rejected with an explicit error: silent
+  # acceptance of malformed input is what broke the Python prototype.
+  class Facts
+    # name => arity. Order is the emission order of #to_s.
+    SCHEMA = {
+      "nx" => 1, "pie" => 1, "canary" => 1, "relro" => 1,
+      "plt" => 1, "gadget" => 2, "vuln_hint" => 1, "vuln" => 1,
+      "target_function" => 1, "libc_present" => 1, "allocator" => 1,
+      "glibc_minor" => 1, "return_addr_filtered" => 1,
+      "got_overwrite_target" => 1, "function_pointer_on_heap" => 1,
+      "seccomp" => 1, "shellcode_input" => 1, "sigreturn_frame" => 1,
+      "fmtstr_read" => 1, "reloc_writable" => 1, "dt_lazy" => 1,
+      "limited_stack" => 1, "service" => 1, "software_version" => 1,
+      "remote" => 1, "verified" => 1, "win_symbol" => 2,
+      "crash_site" => 1, "vuln_function" => 1, "sink" => 1, "leaked_address" => 2,
+      "plt_addr" => 2, "got_addr" => 2, "cve" => 1
+    }.freeze
+
+    STRING_TYPES = {
+      "gadget" => %w[string integer],
+      "win_symbol" => %w[string integer],
+      "crash_site" => %w[string],
+      "vuln_function" => %w[string],
+      "sink" => %w[string],
+      "leaked_address" => %w[string integer],
+      "plt_addr" => %w[string integer],
+      "got_addr" => %w[string integer],
+      "glibc_minor" => %w[integer],
+      "cve" => %w[string]
+    }.freeze
+
+    # Closed value domains: a typo'd atom ("ture", "maybe") would parse,
+    # disable the closed-world default, and every rule of the predicate
+    # would silently never fire. The loud-failure philosophy stops at
+    # the grammar AND the vocabulary.
+    VALUE_DOMAINS = {
+      "nx" => %w[true false], "pie" => %w[true false], "canary" => %w[true false],
+      "relro" => %w[none partial full], "target_function" => %w[true false],
+      "libc_present" => %w[true false], "function_pointer_on_heap" => %w[true false],
+      "got_overwrite_target" => %w[true false], "seccomp" => %w[true false],
+      "shellcode_input" => %w[true false], "sigreturn_frame" => %w[true false],
+      "fmtstr_read" => %w[true false], "reloc_writable" => %w[true false],
+      "dt_lazy" => %w[true false], "limited_stack" => %w[true false],
+      "remote" => %w[true false], "verified" => %w[remote],
+      "return_addr_filtered" => %w[true false]
+    }.freeze
+
+    include Enumerable
+
+    def self.parse(text)
+      new.parse(text)
+    end
+
+    def self.from_file(path)
+      parse(File.read(path))
+    end
+
+    def initialize
+      @rels = {}
+    end
+
+    def parse(text)
+      text.each_line.with_index(1) do |line, lineno|
+        line = line.rstrip
+        next if line.empty? || line.start_with?("//")
+
+        consume(line, lineno)
+      end
+      self
+    end
+
+    def rel(name)
+      @rels[name]&.dup
+    end
+    alias_method :[], :rel
+
+    def each
+      SCHEMA.each_key do |name|
+        @rels.fetch(name, []).each { |tuple| yield([name, tuple]) }
+      end
+    end
+
+    def size
+      @rels.values.sum(&:size)
+    end
+
+    def merge(other)
+      merged = self.class.new
+      rels = merged.instance_variable_get(:@rels)
+      other_r = other.instance_variable_get(:@rels)
+      SCHEMA.each_key do |name|
+        combined = Array(@rels[name]) + Array(other_r[name])
+        rels[name] = combined unless combined.empty?
+      end
+      merged
+    end
+
+    # Builder API for programmatic construction (the profiler's contract):
+    # identical validation as parsing - same schema, same loud failures.
+    def add(name, *args)
+      raise UnknownPredicate, "unknown predicate #{name.inspect}" unless SCHEMA.key?(name)
+
+      arity = SCHEMA[name]
+      raise MalformedFact, "#{name} expects arity #{arity}, got #{args.size}" unless args.size == arity
+
+      check_types(name, args, 0)
+      domain = VALUE_DOMAINS[name]
+      if domain && args.size == 1 && args.first.is_a?(String) && !domain.include?(args.first)
+        raise MalformedFact, "#{name}: value #{args.first.inspect} is outside the value domain #{domain.inspect}"
+      end
+
+      # the atom grammar is the load-bearing wall: a symbol name from an
+      # untrusted binary (win_symbol) or a version string from a hostile
+      # banner (software_version) must not carry quotes, backslashes,
+      # parens or newlines into a re-parsed facts file
+      args.each do |arg|
+        next unless arg.is_a?(String) && arg.match?(/["\\()\n\r]/)
+
+        raise MalformedFact, "#{name}: fact atoms may not contain quotes, backslashes, parens or newlines"
+      end
+      (@rels[name] ||= []) << args
+      self
+    end
+
+    def to_s
+      SCHEMA.filter_map do |name, _arity|
+        @rels.fetch(name, []).map { |tuple| emit_fact(name, tuple) }
+      end.join
+    end
+
+    private
+
+    def consume(line, lineno)
+      raise MalformedFact, "line #{lineno}: rules are not facts, only facts belong here" if line.include?(":-")
+
+      match = line.match(/\A([a-z][a-z0-9_]*)\((.*)\)\.\z/)
+      raise MalformedFact, "line #{lineno}: malformed fact #{line.inspect}" unless match
+
+      name = match[1]
+      raw_args = match[2]
+      raise UnknownPredicate, "line #{lineno}: unknown predicate #{name.inspect}" unless SCHEMA.key?(name)
+
+      args = parse_args(raw_args, name, lineno)
+      begin
+        add(name, *args)
+      rescue UnknownPredicate, MalformedFact => e
+        raise e.class, "line #{lineno}: #{e.message}"
+      end
+    end
+
+    def parse_args(raw, name, lineno)
+      return [] if raw.strip.empty?
+
+      raw.split(",", -1).map.with_index do |arg, i|
+        arg = arg.strip
+        if arg.match?(/\A-?\d+\z/)
+          arg.to_i
+        elsif arg.match?(/\A"[^"\\()]*"\z/)
+          arg[1..-2]
+        else
+          raise MalformedFact,
+            "line #{lineno}: #{name} arg #{i + 1} is not a quoted string atom or integer"
+        end
+      end
+    end
+
+    def check_types(name, args, lineno)
+      types = STRING_TYPES[name] || (["string"] * SCHEMA[name])
+
+      args.each_with_index do |arg, i|
+        expected = types[i]
+        actual = arg.is_a?(Integer) ? "integer" : "string"
+        next if actual == expected
+
+        raise MalformedFact, "line #{lineno}: #{name} arg #{i + 1} must be a #{expected} atom, got #{actual}"
+      end
+    end
+
+    def emit_fact(name, tuple)
+      types = STRING_TYPES[name]
+      args = tuple.each_with_index.map do |arg, i|
+        (types && types[i] == "integer") ? arg.to_s : %("#{arg}")
+      end
+      "#{name}(#{args.join(", ")}).\n"
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/kb_corpus.json

@@ -0,0 +1,345 @@
+[
+  {
+    "id": "ret2plt_nopie_001",
+    "technique": "ret2plt",
+    "target_class": "nx_no_pie",
+    "source": "ropemporium_ret2win",
+    "description": "ret2plt on no-PIE binary with system@plt. Requires pop rdi gadget binsh string NX on PIE off. Common mistake forgetting ret alignment x86_64 ABI movaps.",
+    "chain": [
+      "pop_rdi_ret",
+      "binsh_addr",
+      "ret_align",
+      "system_plt"
+    ],
+    "unlocks": [],
+    "success_rate": 0.85
+  },
+  {
+    "id": "ret2plt_partial_relro_001",
+    "technique": "ret2plt",
+    "target_class": "nx_no_pie",
+    "source": "protostar_stack6",
+    "description": "ret2plt with partial RELRO. GOT writable but not needed. Technique does not require GOT overwrite. system plt direct.",
+    "chain": [
+      "pop_rdi_ret",
+      "binsh_addr",
+      "system_plt"
+    ],
+    "unlocks": [],
+    "success_rate": 0.82
+  },
+  {
+    "id": "ret2libc_leak_001",
+    "technique": "ret2libc",
+    "target_class": "nx_pie",
+    "source": "phoenix_stack5",
+    "description": "ret2libc via puts leak defeat ASLR. Chain leak libc via puts plt calc system offset pop rdi. Requires pop rdi puts PLT known libc version.",
+    "chain": [
+      "pop_rdi_ret",
+      "got_puts",
+      "puts_plt",
+      "ret_align",
+      "pop_rdi_ret",
+      "binsh_offset",
+      "system_libc"
+    ],
+    "unlocks": [],
+    "success_rate": 0.65
+  },
+  {
+    "id": "fmtstr_arbitrary_write_001",
+    "technique": "fmtstr_write",
+    "target_class": "fmtstr",
+    "source": "protostar_format4",
+    "description": "Format string arbitrary write via %n overwrite GOT. Calibration find offset with %p chain first. FORTIFY_SOURCE breaks %n in glibc 2.17 and above.",
+    "chain": [
+      "leak_stack_canary",
+      "leak_pie_base",
+      "got_overwrite"
+    ],
+    "unlocks": [],
+    "success_rate": 0.55
+  },
+  {
+    "id": "fmtstr_stack_leak_001",
+    "technique": "fmtstr_write",
+    "target_class": "fmtstr",
+    "source": "ctf_generic",
+    "description": "Format string stack leak defeat canary PIE base address. Useful as first stage before ret2libc or ROP chain.",
+    "chain": [
+      "fmtstr_leak_canary",
+      "fmtstr_leak_pie"
+    ],
+    "unlocks": [
+      "ret2libc",
+      "rop"
+    ],
+    "success_rate": 0.72
+  },
+  {
+    "id": "rop_execve_001",
+    "technique": "rop",
+    "target_class": "nx_pie_full_prot",
+    "source": "ropemporium_write4",
+    "description": "ROP chain execve binsh NULL NULL syscall. Requires pop rdi rsi rdx gadgets write primitive binsh string syscall gadget ROPgadget ropper discovery.",
+    "chain": [
+      "write_binsh",
+      "pop_rdi",
+      "binsh_addr",
+      "pop_rsi",
+      "null",
+      "pop_rdx",
+      "null",
+      "syscall"
+    ],
+    "unlocks": [],
+    "success_rate": 0.45
+  },
+  {
+    "id": "fastbin_dup_001",
+    "technique": "heap_fastbin",
+    "target_class": "heap_ptmalloc2",
+    "source": "how2heap_fastbin_dup",
+    "description": "Fastbin dup double-free arbitrary write ptmalloc2. Only works glibc before 2.32 no safe linking. Requires controlled heap double-free primitive.",
+    "chain": [
+      "double_free",
+      "fastbin_overwrite",
+      "arbitrary_write"
+    ],
+    "unlocks": [],
+    "success_rate": 0.4
+  },
+  {
+    "id": "srop_001",
+    "technique": "srop",
+    "target_class": "nx_minimal_gadgets",
+    "source": "ctf_generic",
+    "description": "SROP sigreturn ROP minimal gadgets. Requires syscall gadget sigreturn frame control. Single gadget controls all registers unlike ROP chain.",
+    "chain": [
+      "sigreturn_frame",
+      "syscall"
+    ],
+    "unlocks": [],
+    "success_rate": 0.5
+  },
+  {
+    "id": "chain_fmtstr_ret2libc_001",
+    "technique": "fmtstr_write",
+    "target_class": "nx_pie",
+    "source": "ctf_generic",
+    "description": "Two stage fmtstr leak canary libc base then ret2libc. Classic chain PIE NX canary targets.",
+    "chain": [
+      "fmtstr_leak_canary",
+      "fmtstr_leak_libc",
+      "ret2libc"
+    ],
+    "unlocks": [
+      "ret2libc"
+    ],
+    "success_rate": 0.6
+  },
+  {
+    "id": "chain_puts_leak_rop_001",
+    "technique": "ret2libc",
+    "target_class": "nx_pie",
+    "source": "phoenix_stack7",
+    "description": "puts leak then ROP chain. Stage 1 leak libc base puts plt. Stage 2 construct ROP known libc offsets.",
+    "chain": [
+      "ret2plt_puts_leak",
+      "calc_libc_base",
+      "full_rop"
+    ],
+    "unlocks": [
+      "rop",
+      "ret2libc"
+    ],
+    "success_rate": 0.58
+  },
+  {
+    "id": "unlink_dlmalloc_001",
+    "technique": "heap_overwrite",
+    "target_class": "heap_dlmalloc",
+    "source": "pwnable.kr/unlink",
+    "description": "Unlink macro corruption old dlmalloc arbitrary write. FD BK pointer manipulation overwrite return address shell. Requires heap and stack leak to defeat ASLR.",
+    "chain": [
+      "heap_leak",
+      "stack_leak",
+      "unlink_corrupt",
+      "overwrite_ret"
+    ],
+    "unlocks": [],
+    "success_rate": 0.78
+  },
+  {
+    "id": "tcache_tear_001",
+    "technique": "heap_tcache",
+    "target_class": "heap_tcache",
+    "source": "pwnable.tw/tcache_tear",
+    "description": "Tcache tear double-free poisoning modern glibc. Overwrite free_hook with one_gadget. Unsorted bin attack for libc leak first.",
+    "chain": [
+      "double_free",
+      "tcache_poison",
+      "leak_libc",
+      "overwrite_free_hook",
+      "one_gadget"
+    ],
+    "unlocks": [],
+    "success_rate": 0.62
+  },
+  {
+    "id": "tcache_realloc_fmtstr_001",
+    "technique": "heap_tcache",
+    "target_class": "heap_tcache",
+    "source": "pwnable.tw/realloc",
+    "description": "Tcache dup overwrite atoll GOT with printf. Turns input into format string then leak libc. Overwrite atoll with system for shell.",
+    "chain": [
+      "tcache_dup",
+      "got_overwrite_printf",
+      "fmtstr_leak",
+      "got_overwrite_system"
+    ],
+    "unlocks": [
+      "fmtstr_write"
+    ],
+    "success_rate": 0.55
+  },
+  {
+    "id": "srop_smallest_001",
+    "technique": "srop",
+    "target_class": "minimal_static_nx",
+    "source": "360ctf/smallest",
+    "description": "SROP x86_64 canonical 17 byte binary read rsp ret. read retval sets rax 15 rt_sigreturn send 15 bytes. fake sigframe execve rax 59 rdi binsh syscall gadget.",
+    "chain": [
+      "read_sets_rax_15",
+      "syscall_sigreturn",
+      "fake_frame_execve"
+    ],
+    "unlocks": [],
+    "success_rate": 0.55
+  },
+  {
+    "id": "srop_sickrop_001",
+    "technique": "srop",
+    "target_class": "minimal_static_nx",
+    "source": "hackthebox/sick_rop",
+    "description": "SROP x86_64 mprotect variant static binary read write. rax 15 rt_sigreturn via read write byte count. fake sigframe mprotect rax 10 region rwx then shellcode.",
+    "chain": [
+      "set_rax_15",
+      "syscall_sigreturn",
+      "fake_frame_mprotect",
+      "region_rwx",
+      "shellcode"
+    ],
+    "unlocks": [],
+    "success_rate": 0.55
+  },
+  {
+    "id": "orw_seccomp_001",
+    "technique": "shellcode",
+    "target_class": "seccomp_nx_off",
+    "source": "pwnable.tw/orw",
+    "description": "Shellcode under seccomp open read write only. No execve allowed so shellcode reads flag file directly. Binary reads shellcode into executable buffer.",
+    "chain": [
+      "inject_shellcode",
+      "open_flag",
+      "read_flag",
+      "write_stdout"
+    ],
+    "unlocks": [],
+    "success_rate": 0.55
+  },
+  {
+    "id": "rop_calc_int80_001",
+    "technique": "rop",
+    "target_class": "nx_canary_static",
+    "source": "pwnable.tw/calc",
+    "description": "ROP chain static binary NX canary int 0x80 execve. Arbitrary relative write builds chain on stack. pop edx pop eax int80 gadgets execve binsh.",
+    "chain": [
+      "arbitrary_write",
+      "build_rop",
+      "int80_execve"
+    ],
+    "unlocks": [],
+    "success_rate": 0.5
+  },
+  {
+    "id": "fmtstr_leak_stack_001",
+    "technique": "fmtstr_leak",
+    "target_class": "nx_pie",
+    "source": "protostar_format1",
+    "description": "format string leak of stack data via %x %s. Reads defeat PIE by leaking code pointers and defeat canaries by leaking the stack cookie. Common mistake forgetting the read primitive needs no write at all.",
+    "chain": [
+      "printf"
+    ],
+    "unlocks": [
+      "ret2libc",
+      "rop"
+    ],
+    "success_rate": 0.72
+  },
+  {
+    "id": "ret2dlresolve_ropemporium_001",
+    "technique": "dlresolve",
+    "target_class": "nx_no_pie",
+    "source": "ropemporium_ret2dlresolve",
+    "description": "deferred symbol resolution abuse with lazy binding. Fake DT_SYMTAB entry resolves system without any libc leak. Requires writable relocation and lazy binding partial RELRO. Sparse gadget binary.",
+    "chain": [
+      "fake_reloc",
+      "dl_fixup",
+      "system"
+    ],
+    "unlocks": [
+      "shell"
+    ],
+    "success_rate": 0.55
+  },
+  {
+    "id": "ret2csu_sparse_001",
+    "technique": "ret2csu",
+    "target_class": "nx_no_pie",
+    "source": "ropemporium_ret2csu",
+    "description": "__libc_csu_init universal gadget populates rdx rsi rdi in gadget-sparse binaries. The popper and mov gadgets enable controlled multi-argument calls.",
+    "chain": [
+      "csu_popper",
+      "csu_mov",
+      "target_fn"
+    ],
+    "unlocks": [
+      "libc_base"
+    ],
+    "success_rate": 0.75
+  },
+  {
+    "id": "stack_pivot_bss_001",
+    "technique": "stack_pivot",
+    "target_class": "nx_no_pie",
+    "source": "ropemporium_pivot",
+    "description": "stack pivot via xchg rsp rax onto a larger buffer in bss. Required when the full chain does not fit the available stack space. Two-stage chain discipline.",
+    "chain": [
+      "pop_rax_ret",
+      "xchg_rsp_rax",
+      "bss_chain"
+    ],
+    "unlocks": [
+      "ret2libc",
+      "rop"
+    ],
+    "success_rate": 0.7
+  },
+  {
+    "id": "got_overwrite_fmtstr_001",
+    "technique": "got_overwrite",
+    "target_class": "nx_pie",
+    "source": "phoenix_format4",
+    "description": "overwrite a GOT entry to redirect a called function. Partial RELRO keeps the GOT writable. Redirect printf or exit to the target. Classic documented format4 path.",
+    "chain": [
+      "fmtstr_n_write",
+      "got_entry",
+      "redirect"
+    ],
+    "unlocks": [
+      "shell"
+    ],
+    "success_rate": 0.65
+  }
+]