augure 0.1.0

data/home/runner/work/augure/augure/docs/reference.md

@@ -0,0 +1,293 @@
+# Reference: fact format, rules table, API
+
+Version: augure 0.1.x.
+
+## Fact format
+
+One fact per line: `predicate("string-atom").` or `predicate("atom", 42).`
+Blank lines and `// comments` ignored. Rules (`:-`) rejected. Unknown
+predicate, wrong arity or wrong argument type raises an explicit error with
+the line number. So does:
+
+- a **value outside a closed domain** (18 predicates are validated: the
+  booleans take `"true"`/`"false"` only, `relro` takes `none`/`partial`/`full`,
+  `verified` takes `"remote"` - a typo'd atom parses under a string-only
+  schema, disables the closed-world default and silently kills every rule
+  of the predicate; the validation makes it loud instead);
+- an **atom carrying quotes, backslashes, parens or newlines** (the
+  grammar keeps the fact stream a stream).
+
+Free-form predicates (`vuln`, `vuln_hint`, `allocator`, `gadget`,
+`win_symbol`, `plt`...) take any atom.
+
+### A complete example
+
+This is the shape of a `target.facts` file (see the
+[tutorial](tutorial.md) for the full walkthrough):
+
+```
+// the target
+nx("true").
+pie("false").
+canary("false").
+relro("partial").
+
+// what it imports
+plt("system").
+plt("puts").
+
+// what gadgets exist inside it
+gadget("pop_rdi_ret", 4198400).
+gadget("ret_align", 4198404).
+
+// what the profiler noticed
+vuln_hint("unsafe_func:gets").
+```
+
+### Schema
+
+| Predicate | Arity | Arg types | Meaning |
+|---|---|---|---|
+| `nx` | 1 | string | data execution prevention (`"true"`/`"false"`) |
+| `win_symbol` | 2 | string, integer | the winning function's name and address (emitted by the profiler) |
+| `crash_site` | 1 | string | the crash's identification: `ret` when the control is confirmed by the planted pattern |
+| `leaked_address` | 2 | string, integer | an address the service's own banner leaked (name + value, emitted by lictor's harvest) |
+| `plt_addr` | 2 | string, integer | a JMP_SLOT import's PLT stub address (name + value, emitted by the profiler from the section layout) |
+| `got_addr` | 2 | string, integer | a JMP_SLOT import's GOT entry address (the relocation offset) |
+| `vuln_function` | 1 | string | the vulnerable function the static frame read named |
+| `sink` | 1 | string | the unsafe sink (strcpy, gets, ...) the static read identified |
+| `pie` | 1 | string | position-independent executable |
+| `canary` | 1 | string | stack canary present |
+| `relro` | 1 | string | `"none"`, `"partial"`, `"full"` |
+| `plt` | 1 | string | imported function name |
+| `gadget` | 2 | string, integer | gadget semantic type + address |
+| `vuln_hint` | 1 | string | profiler hint, e.g. `"unsafe_func:gets"` |
+| `vuln` | 1 | string | explicit vuln class: `sof`, `fmtstr`, `heap` |
+| `target_function` | 1 | string | win-style function present |
+| `libc_present` | 1 | string | libc known/version pinned |
+| `allocator` | 1 | string | `tcache`, `ptmalloc2`, `dlmalloc` |
+| `glibc_minor` | 1 | integer | glibc minor version |
+| `return_addr_filtered` | 1 | string | return addresses constrained (stack6-style) |
+| `got_overwrite_target` | 1 | string | GOT overwrite viable |
+| `function_pointer_on_heap` | 1 | string | heap function pointer |
+| `seccomp` | 1 | string | seccomp filter context |
+| `shellcode_input` | 1 | string | input reachable and executable |
+| `sigreturn_frame` | 1 | string | sigreturn frame constructible |
+| `fmtstr_read` | 1 | string | format string has a read primitive |
+| `reloc_writable` | 1 | string | relocations writable (ret2dlresolve) |
+| `dt_lazy` | 1 | string | lazy binding in effect |
+| `limited_stack` | 1 | string | stack space constrains the chain |
+| `service` | 1 | string | remote service name (nmap: `ssh`, `http`...) |
+| `software_version` | 1 | string | remote product + version (from the scan) |
+| `remote` | 1 | string | the facts describe a remote service, not a local ELF |
+| `verified` | 1 | string | `"remote"` = validated by a differential probe: the remote faults like the local model |
+
+Defaults (closed world): absent `nx` = `"true"`, absent `pie` = `"true"`,
+absent `canary` = `"false"`.
+
+## Rules table (applicability)
+
+| Rule ID | Head | Fires when |
+|---|---|---|
+| `app_shellcode` | `shellcode` | sof, NX off, no canary, return not filtered, NOT seccomp |
+| `app_ret2func` | `ret2func` | sof, PIE off, target function present |
+| `app_ret2plt` | `ret2plt` | sof, NX on, PIE off, `system` imported |
+| `app_ret2libc_plt` | `ret2libc` | sof, `__libc_start_main` imported, NOT seccomp |
+| `app_ret2libc_libc` | `ret2libc` | sof, libc present, NOT seccomp |
+| `app_rop` | `rop` | sof, NX on, gadget supply (pop or mov-store), NOT seccomp |
+| `app_srop` | `srop` | sof, sigreturn frame, syscall gadget, NOT seccomp |
+| `app_ret2plt_leak` | `ret2plt_leak` | sof, NX on, PIE on, `puts`, reg control |
+| `app_fmtstr_write` | `fmtstr_write` | format-string vuln (NX-independent) |
+| `app_fmtstr_leak_read` | `fmtstr_leak` | fmtstr + read primitive |
+| `app_fmtstr_leak_pie` | `fmtstr_leak` | fmtstr + PIE on |
+| `app_fmtstr_leak_canary` | `fmtstr_leak` | fmtstr + canary on |
+| `app_ret2dlresolve` | `ret2dlresolve` | sof, NX on, PIE off, lazy binding, writable reloc |
+| `app_ret2csu` | `ret2csu` | sof, NX on, csu gadget family |
+| `app_stack_pivot` | `stack_pivot` | sof, NX on, limited stack, pivot gadget |
+| `app_got_overwrite_sof` | `got_overwrite` | sof, NX on, GOT target, not full RELRO |
+| `app_got_overwrite_fmtstr` | `got_overwrite` | fmtstr, GOT target, not full RELRO |
+| `app_heap_tcache_alloc` | `heap_tcache` | heap, allocator tcache |
+| `app_heap_tcache_glibc` | `heap_tcache` | heap, glibc 2.26..2.33 |
+| `app_heap_fastbin_glibc` | `heap_fastbin` | heap, glibc < 2.26 |
+| `app_heap_fastbin_alloc` | `heap_fastbin` | heap, allocator ptmalloc2 |
+| `app_heap_overwrite_dlmalloc` | `heap_overwrite` | heap, dlmalloc |
+| `app_heap_overwrite_fp` | `heap_overwrite` | heap, function pointer on heap |
+
+("NOT seccomp" = the rule carries `[not_fact, seccomp, "true"]`: the
+technique ends in execve, dead under any filter that kills execve; the
+condition passes when the fact is absent.)
+
+Derived relations: `vuln` (from hints), `has_reg_control`,
+`has_write_primitive`, `has_syscall_gadget`, `has_csu_gadget`,
+`has_pivot_gadget`, `enough_gadgets`.
+
+## CLI
+
+```
+augure analyze <facts-file | -> [--json] [--seed N] [--packs DIR]
+augure coverage [--flip NAME:VALUE ...] [--facts FILE] [--json]
+augure rules [--mitre] [--packs DIR] [--json]
+augure explain <technique>
+augure doctor
+```
+
+| Flag | Effect |
+|---|---|
+| `--json`, `-j` | machine-readable decision (analyze) / the coverage scorecard (coverage) / the Navigator layer (rules --mitre) |
+| `--seed N`, `-s N` | deterministic bandit/MCTS draws |
+| `--packs DIR` | merge technique packs (analyze, explain, rules --mitre's source) |
+| `--flip NAME:VALUE` | coverage: a hardening override (`nx:true`, `canary:true`, `relro:full`; `NAME:nil` removes) |
+| `--facts FILE` | coverage: one entry instead of the whole corpus |
+| (stdin) | `-` reads facts from stdin |
+
+Exit codes: `0` decision emitted, non-zero on malformed facts (message on
+stderr names the line). `coverage` always exits 0 (an analysis, not a gate).
+
+## Ruby API
+
+### `Augure::Facts`
+
+- `.parse(text) -> Facts` - strict parse, raises `MalformedFact` /
+  `UnknownPredicate` with line numbers.
+- `.from_file(path) -> Facts`
+- `.new` + `#add(name, *args)` - the builder API (the profiler's
+  contract; the same domain + grammar validation as `parse`).
+- `#rel(name) -> Array<[arg, ...]> | nil` - tuples by relation.
+- `#each`, `#size`, `#[]` - iteration, count, direct lookup.
+- `#merge(other) -> Facts` - combined copy.
+- `#to_s -> String` - deterministic emission; round-trips.
+
+### `Augure::Engine`
+
+- `.new(facts, rules: Rules.all)`
+- `#run -> Result`
+- `Result#applicable -> [String]` - rule-table order.
+- `Result#derived(rel) -> [tuple]`
+- `Result#provenance(technique) -> [{rule:, origin:, evidence:}]` - every sibling firing, each attributed
+
+### `Augure::Bandit`
+
+- `.new(priors: {"tech" => [alpha, beta]}, rng: Random.new)`
+- `#arm(tech) -> Arm` (auto-arms unknown with (1, 1))
+- `#select(verified) -> String | nil` - Thompson sample argmax.
+- `#feedback(tech, success)` - updates posterior, logs history.
+- `#ranking_of(techniques) -> [[tech, mean], ...]` - prior-mean pairs,
+  deterministic (the method the corpus freezes; the pipeline maps
+  `&:first` over it).
+- `#rankings -> [[tech, mean], ...]` - ALL arms sorted by prior mean
+  (deterministic, not a draw).
+- `#mean(tech) -> Float` - the prior mean (alpha / (alpha + beta)).
+- `#select(verified)` - the Thompson sampler (the draw).
+
+### `Augure::Mcts`
+
+- `.plan(allowed, iterations: 2000, seed:) -> [first_move, path]`
+  (`model:` overrides the transition graph; technique packs merge into
+  it via `merged_model(packs)`)
+- `.available(caps, allowed)`, `.transition(caps, tech)`,
+  `.terminal?(caps, model:)` - terminal = any capability provided by a
+  `terminal: true` stage of the model (packs own their semantics; the
+  built-in model's terminals all provide `shell`).
+- `.stage(tech)` - one stage's `[requires, provides, terminal, success]`.
+- `STAGE_MODEL` - the technique transition graph.
+
+### `Augure::Pack` / `PackLoader`
+
+- `Pack.load_file(path)` - validates a technique pack (YAML) through
+  the **10 armor checks** (see [pack-format.md](pack-format.md)): shape,
+  stratification, new heads, provenance, kb/mcts/priors shapes, match
+  regexes + cmp types (7), the optional `build:` (8), `detection:` (9),
+  `mitre:` (10).
+- `PackLoader.load_dir(dir) -> [Pack]`, `.priors_with(packs, base)`,
+  `.mcts_model(packs)`.
+- `.corpus_guard(packs)` - refuses any pack that reorders an existing
+  technique or takes a documented target's top-1; honors a documented
+  `pack_verdict` entry (the pack answer must ARRIVE) and tolerates
+  empty frozen verdicts.
+- The gem SHIPS all 20 packs (`packs/` in the gem); `packs/ret2csu_v2.yml`
+  is the canonical authoring example.
+
+### `Augure::Verifier`
+
+- `.payload_fits(buffer_size:, payload_min:) -> :sat | :unsat`
+- `.bad_bytes?(payload:, bad_bytes:) -> bool`
+- `.rop_chain_feasible?(...) -> bool`
+- `.payload_fits_smtlib(buffer_size, payload_min) -> String`
+
+### `Augure::SmtProcess`
+
+- `.solve(smt_text, solver:, timeout: 10) -> :sat | :unsat | :unknown`
+
+### `Augure::Pipeline`
+
+- `.analyze(facts:, seed: nil, priors: nil, buffer_size: 256,
+  packs: nil, plan: true) -> {applicable:, verified:, ranking:, selected:,
+  plan:, explain:}` - `packs:` merges technique packs (rules, priors,
+  MCTS transitions); `plan: false` skips the MCTS search (the corpus
+  guard uses it).
+
+### Machine payload contract
+
+`augure analyze --json` emits the decision hash stamped with a stable
+schema tag:
+
+```json
+{ "schema": "augure/decision@1", "applicable": [...], ... }
+```
+
+Consumers (CI, agents, the MCP server) pin `augure/decision@1`; a
+breaking change bumps the tag and is documented in the CHANGELOG.
+
+### Taught technique packs
+
+The shipped packs extend the rule table as data (`packs/`, loaded with
+`augure analyze --packs DIR` or taught to lictor with
+`lictor rule install`): `house_force`, `house_orange`, `house_botcake`,
+`unsorted_bin_attack`, `fastbin_hook`, `ret2dlresolve_x86`,
+`got_partial_overwrite`, `brop` (the first rule that consumes
+`verified("remote")` - an observation anchors it), `ret2partial_overwrite`,
+`one_gadget`, `banner_leak`, `got_partial_overwrite_deref`,
+`house_of_apple2`, `jop`, `large_bin_attack`, `orw`, `ret2vdso`,
+`setcontext_srop`, `uaf_tcache` - plus the canonical `ret2csu_v2`
+example: **20 packs** ship. Each carries its rules, knowledge-base
+entries, MCTS transition and Beta priors, the author and source as
+provenance, and (optionally) `build:` (the assembly order),
+`detection:` (the defender side) and `mitre:` (the ATT&CK mapping).
+Pack priors fill the gaps of the prior table; a consumer-provided or
+outcome-adapted entry always wins.
+
+### `Augure::KnowledgeBase`
+
+- `.corpus -> [entry]` (22 documented patterns)
+- `.corpus_with(extra) -> [entry]` (seed corpus + technique-pack knowledge)
+- `.priors -> {"tech" => [alpha, beta]}` (N=10 pseudo-counts)
+- `.transitions -> {"tech" => [unlock, ...]}`
+- `#query(text, technique: nil, n_results: 3) -> [{doc:, score:}]`
+
+## MCTS stage model
+
+| Technique | Requires | Provides | Terminal | Base success |
+|---|---|---|---|---|
+| `fmtstr_leak` | - | libc_base | no | 0.75 |
+| `fmtstr_canary` | - | canary | no | 0.70 |
+| `ret2plt_leak` | - | libc_base | no | 0.68 |
+| `ret2libc` | libc_base | shell | yes | 0.85 |
+| `rop` | libc_base | shell | yes | 0.75 |
+| `rop_nocontext` | - | shell | yes | 0.25 |
+| `ret2plt` | - | shell | yes | 0.75 |
+| `shellcode` | - | shell | yes | 0.90 |
+| `stack_pivot` | - | pivot | no | 0.60 |
+| `ret2plt_leak_big` | pivot | libc_base | no | 0.68 |
+| `ret2libc_big` | pivot+libc_base | shell | yes | 0.85 |
+| `ret2csu` | - | libc_base | no | 0.70 |
+| `dlresolve` | - | shell | yes | 0.55 |
+| `got_overwrite` | - | shell | yes | 0.65 |
+| `io_uring_register` | - | iouring | no | 0.90 |
+| `rds_pin_steal` | iouring | pin_underflow | no | 0.70 |
+| `page_free` | pin_underflow | freed_page | no | 0.75 |
+| `pagecache_reclaim` | freed_page | pagecache_ctrl | no | 0.65 |
+| `io_uring_write` | pagecache_ctrl+iouring | suid_overwrite | no | 0.70 |
+| `suid_exec` | suid_overwrite | shell | yes | 0.90 |
+
+The last six are the PinTheft chain (V12 Security), an externally documented
+ordering - augure only tests whether the planner reproduces it.

data/home/runner/work/augure/augure/docs/tutorial.md

@@ -0,0 +1,108 @@
+# Get your first auditable decision in 10 minutes
+
+*Tutorial. By the end you will have run Augure on a real fact file, read its
+proof trail, and made it disagree with you on purpose.*
+
+Prerequisites: Ruby 3.4+.
+
+## 1. Install
+
+```sh
+gem install augure
+augure --help
+```
+
+You should see the usage banner. **Check:** `Usage: augure analyze`.
+
+## 2. Write a fact file
+
+> **Where do facts come from?** From the profiler, not your keyboard:
+> `augure-profile app.elf -o target.facts` generates exactly this file from
+> a binary (checksec, imports, unsafe symbols, gadgets) via metasm - gem
+> `augure-profiler`. Hand-writing facts is still useful to learn the
+> format the profiler speaks.
+
+Facts are one target's properties, one per line. Create `target.facts`:
+
+```
+// the target
+nx("true").
+pie("false").
+canary("false").
+relro("partial").
+
+// what it imports
+plt("system").
+plt("puts").
+
+// what gadgets exist inside it
+gadget("pop_rdi_ret", 4198400).
+gadget("ret_align", 4198404).
+
+// what the profiler noticed
+vuln_hint("unsafe_func:gets").
+```
+
+**Check:** the file has no trailing `:-` and every line ends with `.`.
+
+## 3. Decide
+
+```sh
+augure analyze target.facts
+```
+
+You should see:
+
+```
+applicable: ret2plt, rop
+selected:   ret2plt
+plan:       ret2plt
+# (selected is a seeded Thompson draw: same facts + same --seed = same
+#  selection, always. Unseeded, the draw explores the ranking.)
+  ret2plt <- app_ret2plt (vuln=sof, nx=true, pie=false, plt=system)
+  rop     <- app_rop (vuln=sof, nx=true, enough_gadgets=true)
+```
+
+Augure picked `ret2plt` - the technique human operators routinely skip in
+favor of a ROP chain. The rules, not the reflex, made the call.
+
+## 4. Read the proof
+
+```sh
+augure analyze target.facts --json | head -30
+```
+
+Find the `explain.provenance` block (the JSON is long: `grep -A 20 provenance`
+after the pipe) - the rule ID, the evidence pairs, and the origin that
+fired it. That block is the whole product: hand it to a colleague, they can
+verify the decision without rerunning anything.
+
+## 5. Reproduce it
+
+```sh
+augure analyze target.facts --json --seed 42 > run1.json
+augure analyze target.facts --json --seed 42 > run2.json
+diff run1.json run2.json && echo "identical"
+```
+
+Same input, same seed, same decision. **Check:** the diff is empty.
+
+## 6. Make it disagree with you
+
+Remove the `plt("system")` line and run again:
+
+```sh
+grep -v 'plt("system")' target.facts > no-system.facts
+augure analyze no-system.facts
+```
+
+`ret2plt` vanished - and the proof trail explains why: the rule
+`app_ret2plt` requires the fact you just removed. This is the loop the
+whole tool is built on: change the facts, watch the decision move, know
+exactly which rule moved it.
+
+## Next steps
+
+- [Write your own technique rules](how-to-write-rules.md)
+- [The full reference](reference.md) - fact schema and API
+- [What the proof trail buys each team](auditability.md)

data/home/runner/work/augure/augure/examples/ret2win.facts

@@ -0,0 +1,11 @@
+nx("true").
+pie("false").
+canary("false").
+relro("partial").
+plt("puts").
+plt("memset").
+plt("read").
+plt("printf").
+gadget("ret_align", 4198400).
+vuln_hint("unsafe_func:gets").
+target_function("true").

data/home/runner/work/augure/augure/examples/split.facts

@@ -0,0 +1,12 @@
+nx("true").
+pie("false").
+canary("false").
+relro("partial").
+plt("system").
+plt("puts").
+plt("memset").
+plt("read").
+plt("printf").
+gadget("pop_rdi_ret", 4198400).
+gadget("ret_align", 4198400).
+vuln_hint("unsafe_func:gets").

data/home/runner/work/augure/augure/exe/augure

@@ -0,0 +1,181 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../lib/augure"
+
+VERSION_LINE = "augure #{Augure::VERSION}"
+
+options = {json: false, seed: nil}
+parser = OptionParser.new do |opts|
+  opts.banner = <<~USAGE
+
+    #{VERSION_LINE} - the auditable exploitation decision layer
+
+    Usage:
+      augure analyze <facts-file | -> [options]   decide on facts
+      augure coverage [options]                   the corpus read backwards (defender side)
+      augure doctor                               verify the environment
+      augure rules                                print the rules-as-data table
+      augure explain <technique>                  rules + knowledge for one technique
+      augure --version                            print the version
+
+    analyze options:
+  USAGE
+  opts.on("-j", "--json", "Emit the decision as JSON (schema: augure/decision@1)") { options[:json] = true }
+  opts.on("-s", "--seed N", Integer, "Seed for deterministic bandit/MCTS") { |n| options[:seed] = n }
+  opts.on("--packs DIR", "Load technique packs (armor + corpus guard) for analyze/explain") { |v| options[:packs] = v }
+  opts.on("--flip NAME:VALUE", "Coverage: a hardening flip (nx:true, canary:true, relro:full; NAME:nil removes)") do |v|
+    name, value = v.split(":", 2)
+    (options[:flips] ||= {})[name] = ((value == "nil") ? nil : value)
+  end
+  opts.on("--facts FILE", "Coverage: one facts entry instead of the corpus") { |v| options[:facts_entry] = v }
+  opts.on("--mitre", "rules: export the ATT&CK navigator layer (from the packs' mitre: fields)") { options[:mitre] = true }
+  opts.on("--version", "Print the version") do
+    puts VERSION_LINE
+    exit 0
+  end
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit 0
+  end
+end
+parser.parse!
+
+command = ARGV.shift
+
+case command
+when "--version", "-v"
+  puts VERSION_LINE
+when "doctor"
+  checks = []
+  checks << ["ruby >= 3.4", (RUBY_VERSION >= "3.4") ? nil : "upgrade ruby (mise install ruby@3.4)"]
+  checks << [VERSION_LINE, nil]
+
+  # The corpus self-verifies: parse a shipped example, decide, compare.
+  begin
+    example = File.join(__dir__, "../examples/ret2win.facts")
+    result = Augure::Pipeline.analyze(facts: File.read(example))
+    checks << if result[:ranking].first == "ret2func"
+      ["corpus self-test (selected: ret2func)", nil]
+    else
+      ["corpus self-test", "corpus example decided differently - report a bug"]
+    end
+  rescue => e
+    checks << ["corpus self-test", e.message]
+  end
+
+  solvers = %w[z3 bitwuzla cvc5].select do |s|
+    system("sh", "-c", "command -v '#{s}' >/dev/null 2>&1")
+  end
+  checks << ["SMT solvers",
+    solvers.empty? ? "optional - none found; the arithmetic path works without (apt install z3 for the SMT path)" : "optional, found: #{solvers.join(", ")}"]
+
+  failed = false
+  checks.each do |name, problem|
+    if problem&.start_with?("optional")
+      puts "  opt   #{name} - #{problem}"
+    elsif problem
+      failed = true
+      puts "  FAIL  #{name} - fix: #{problem}"
+    else
+      puts "  ok    #{name}"
+    end
+  end
+  if failed
+    n = checks.count { |_, p| p && !p.start_with?("optional") }
+    abort("augure: doctor found #{n} issue(s) - fixes above")
+  end
+when "rules"
+  if options[:mitre]
+    mitre_by_pack = {}
+    packs_dir = options[:packs] || "packs"
+    Dir.glob(File.expand_path(File.join(packs_dir, "*.yml"))).each do |path|
+      pack = Augure::Pack.load_file(path)
+      (mitre_by_pack[pack.technique] = pack.mitre) if pack.mitre
+    rescue
+      nil
+    end
+    if options[:json]
+      puts JSON.pretty_generate("schema" => "augure/mitre-navigator@1", "layers" => [{
+        "name" => "augure techniques", "versions" => {"attack" => "14", "navigator" => "4.9"},
+        "techniques" => mitre_by_pack.map { |tech, codes| codes.map { |c| {"techniqueID" => c, "score" => 1, "comment" => tech} } }.flatten
+      }])
+      exit 0
+    end
+    mitre_by_pack.each { |tech, codes| puts "#{tech}\t#{codes.join(", ")}" }
+    exit 0
+  end
+  Augure::Rules.all.each do |rule|
+    puts rule.id
+    puts "  head: #{rule.head.join("=")}"
+    puts "  why:  #{rule.source}"
+  end
+when "explain"
+  technique = ARGV.shift or abort(parser.to_s)
+  packs = options[:packs] && Augure::PackLoader.load_dir(options[:packs]).tap { |ps| Augure::PackLoader.corpus_guard(ps) }
+  rules = Augure::Rules.all + packs.to_a.flat_map(&:rules)
+  rules = rules.select { |r| r.head == [Augure::Rules::APPLICABLE, technique] }
+  entries = Augure::KnowledgeBase.corpus_with(packs.to_a.flat_map(&:kb))
+    .select { |e| e["technique"] == technique }
+  if rules.empty? && entries.empty?
+    known = Augure::Rules.applicable_rules.map { |r| r.head[1] }.uniq.sort
+    abort("augure: unknown technique '#{technique}' - known: #{known.join(", ")}")
+  end
+  puts "technique: #{technique}"
+  rules.each do |rule|
+    puts "  rule: #{rule.id} - #{rule.source}"
+  end
+  entries.each do |e|
+    puts "  kb:   #{e["id"]} (success_rate #{e["success_rate"]})"
+    puts "        #{e["description"]}"
+  end
+when "coverage"
+  entries = if options[:facts_entry]
+    [{"suite" => "facts", "name" => File.basename(options[:facts_entry]),
+      "facts" => File.read(options[:facts_entry])}]
+  else
+    corpus = JSON.parse(File.read(File.expand_path("../lib/augure/ctf_corpus.json", __dir__)))
+    corpus["suites"].values.flatten
+  end
+  unless options[:flips]
+    abort("augure: coverage needs at least one --flip NAME:VALUE (nx:true, canary:true, relro:full)")
+  end
+  report = Augure::Coverage.report(entries, flips: options[:flips])
+  if options[:json]
+    puts JSON.pretty_generate("schema" => "augure/coverage@1", **report)
+    exit 0
+  end
+  entries.size
+  report[:entries].count { |e| e[:lost].empty? && e[:gained].empty? }
+  puts "the corpus read backwards: #{entries.size} targets, flips #{options[:flips].inspect}"
+  puts "targets that change their applicable set: #{report[:entries].count { |e| e[:lost] || e[:gained] } - report[:entries].count { |e| e[:lost].empty? && e[:gained].empty? }}"
+  report[:died].each { |tech, n| puts "  died:    #{tech}  (#{n} target(s))" }
+  report[:gained].each { |tech, n| puts "  gained:  #{tech}  (#{n} target(s))" }
+  puts "untouched targets: #{report[:survived_count]}"
+  puts "the remaining applicable techniques are the attacker's next moves - harden accordingly."
+when "analyze"
+  path = ARGV.shift or abort(parser.to_s)
+  input = (path == "-") ? $stdin.read : File.read(path)
+  begin
+    packs = options[:packs] && Augure::PackLoader.load_dir(options[:packs]).tap { |ps| Augure::PackLoader.corpus_guard(ps) }
+    result = Augure::Pipeline.analyze(facts: input, seed: options[:seed], packs: packs)
+    if options[:json]
+      puts JSON.pretty_generate({schema: "augure/decision@1"}.merge(result))
+    else
+      puts "applicable: #{result[:applicable].join(", ")}"
+      puts "selected:   #{result[:selected]}"
+      puts "plan:       #{result[:plan].join(" -> ")}"
+      result[:explain][:provenance].each do |tech, provs|
+        provs.each do |p|
+          puts "  #{tech} <- #{p[:rule]} (#{p[:evidence].map { |e| e.join("=") }.join(", ")})"
+        end
+      end
+    end
+  rescue Augure::MalformedFact, Augure::UnknownPredicate => e
+    abort("augure: #{e.message}")
+  end
+else
+  abort(parser.to_s)
+end

data/home/runner/work/augure/augure/exe/augure-benchmark

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../lib/augure"
+
+# Concordance benchmark against the frozen CTF corpus, in the spirit of the
+# Python prototype's benchmark harness: predictions vs documented truth,
+# per suite, with an explicit exit code gate.
+
+threshold = 1.00
+OptionParser.new do |opts|
+  opts.banner = "Usage: augure-benchmark <corpus.json> [--min-top1 N]"
+  opts.on("--min-top1 N", Float, "Fail below this top-1 concordance (default 1.00)") { |v| threshold = v }
+  opts.on("--version", "Print the version") do
+    puts "augure #{Augure::VERSION} (benchmark)"
+    exit 0
+  end
+end.parse!(ARGV)
+
+path = ARGV.shift or abort("Usage: augure-benchmark <corpus.json> [--min-top1 N]")
+corpus = JSON.parse(File.read(path))
+meta_priors = corpus.dig("meta", "priors")
+
+puts "  augure-benchmark: prediction vs documented ground truth"
+puts
+
+correct_top1 = 0
+correct_top3 = 0
+n = 0
+
+corpus["suites"].each do |suite, entries|
+  suite_ok1 = 0
+  suite_ok3 = 0
+  entries.each do |entry|
+    result = Augure::Pipeline.analyze(facts: entry["facts"], priors: meta_priors)
+    top3 = result[:ranking].first(3)
+    # An empty frozen verdict is a verdict: concordance = the engine
+    # reproduces it exactly (the pack layer owns the technique; the
+    # built-in table intentionally says nothing).
+    if entry["applicable"].empty?
+      ok = result[:applicable].empty?
+      suite_ok1 += 1 if ok
+      suite_ok3 += 1 if ok
+      next
+    end
+    suite_ok1 += 1 if result[:ranking].first == entry["truth"]
+    suite_ok3 += 1 if top3.include?(entry["truth"])
+  end
+  count = entries.size
+  n += count
+  correct_top1 += suite_ok1
+  correct_top3 += suite_ok3
+  puts format("  %-12s %d/%d top-1   %d/%d top-3",
+    suite, suite_ok1, count, suite_ok3, count)
+end
+
+puts
+pct = correct_top1.to_f / n
+puts format("  Top-1 concordance: %d/%d (%.0f%%)", correct_top1, n, pct * 100)
+puts format("  Top-3 concordance: %d/%d (%.0f%%)", correct_top3, n, (correct_top3.to_f / n) * 100)
+
+if pct < threshold
+  puts format("  BELOW THRESHOLD (%.0f%% < %.0f%%)", pct * 100, threshold * 100)
+  exit 1
+end