augure 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0439bafc6950f3d38a680b8187ebbba52acc7c8d0a19e12cfff0bad82555b11
+  data.tar.gz: f9b6f194a5652122823106fa65dd5fc19f0630a2095d831da32300c5c7cc350c
+SHA512:
+  metadata.gz: a97621f43eccee16165e6ab913620e8d853b9ec7cdff3c381f2dadda689cecceb269c022b9a631eb31a3e98efb8e4f6e5561bd1232ac475785bab930163c9960
+  data.tar.gz: b428108f2757244c6da8316ef9047fb1944adf257317244bf230a4ab0acfb8c78ed9a655cf92ea218605bc6aeebcd81300da915b5f21a27b7ddfad7dd18ce28e

data/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- The `cve` fact (the CVE/KEV bridge): an agent or the operator proposes the CVE id as a fact (`cve("CVE-2024-1234").`) - the technique packs consume it like any observation. The schema + the atom grammar treat it as any string fact.
+
+- The pack DSL gains an optional `build:` section (the pack teaching the BUILDER its assembly
+  order): armor check 8 validates it (own technique, slot vocabulary), `pack.build` exposes it -
+  lictor's PayloadBuilder consumes it (packs teach, the builder follows, for real this time).
+- ADRs: docs/adr/ records the architectural decisions and renouncements - the arch abstraction
+  before any port (0001), ARM64 deferred behind it (0002), PE/Mach-O out of scope for v0.x (0003).
+- The general gadget hunter: every ret-terminated chain in the executable sections, semantically
+  classified - write4 yields seventeen gadgets the byte patterns never saw (pop_r14_r15_ret, the
+  multi-pop families).
+- The parametrized shellcode: execve of a chosen path, and the orw chain (open/read/write, no
+  execve) for the seccomp answer - the x64 stub reads and prints a real flag file in the suite.
+- The ghost-writing pools: the zeroing, the call-number and the camouflage equivalents picked per
+  seed - ten seeds, ten living stubs, deterministic.
+- The encoders: the keyed self-decoder with the backward-call get-pc (zero-free by construction),
+  the xor and the polymorphic flavours, both live-tested through a 00/41/0a/0d channel; a payload
+  wider than 120 bytes on a 0x00 channel is refused honestly.
+- The dynamic layer: the write-site proof (the watchpoint catches the instruction that plants the
+  overflow), the runtime map (libc, stack), and the crash identification (vuln_function, sink,
+  crash_site).
+- Static parity on the real binaries: a CI job downloads the eight sha256-pinned ROP Emporium x64
+  binaries, profiles binary + shipped libraries, and asserts every statically-derivable corpus
+  claim (96 checked; write-up-only facts are reported as skipped, never silently dropped). The
+  profiler learned the mov [r14], r15 encoding, and the corpus lost two copy-paste defects (a
+  duplicated format1 entry, badchars claiming write4's mov-deref-write gadget).
+- The profiler emits `plt_addr(name, addr)` and `got_addr(name, addr)` for the JMP_SLOT imports
+  (PLT stub from the section layout, GOT entry from the relocation offset): a ROP chain resolves
+  addresses from facts instead of hand-parsed banners. `plt(name)` stays the rule vocabulary.
+- Technique packs: complete techniques as YAML data (rules, KB, MCTS transitions, priors, mandatory
+  provenance), validated by the armor (constrained vocabulary, existing predicates only,
+  stratification, new heads only) and the corpus guard (a pack may not reorder an existing
+  technique or take a documented target's top-1).
+- The network fact vocabulary: service/software_version/remote emitted from nmap scans;
+  `verified("remote")` = the differential confidence level (modeled-from-ELF vs remote-verified).
+- The profiler detects win/flag symbols (the target_function fact).
+- The shipped corpus (lib/augure/ctf_corpus.json) enables the corpus guard at consumer runtime.
+- augure-mcp: the read-only MCP surface (analyze_target, list_rules, explain_technique).
+
+### Changed
+
+- `shellcode` carries the seccomp guard too: the technique as-modeled ends in execve - dead under a
+  filter, the orw pack owns the seccomp case. The frozen `pwnable/orw` entry moves to an EMPTY
+  built-in verdict (the pack layer's technique, deliberately not in the built-in table) with the
+  justification in the corpus; the benchmark counts a reproduced empty verdict as concordance
+  (33/33 holds).
+- `printf` leaves UNSAFE_SYMBOLS: a constant format is not a vuln, and the hint derived
+  `vuln(fmtstr)` for every binary that prints - the lab's menu binaries all became "format string
+  bugs". `sprintf` stays flagged (unbounded by design); the controlled-format knowledge belongs to
+  the operator's suggest flow.
+- seccomp demotes the shell techniques: `ret2libc`, `rop` and `srop` rules carry `[not_fact,
+  seccomp, "true"]` - a filter that kills execve kills system/execve chains, and the decision layer
+  now says so. The not_fact passes when the fact is absent, so the frozen corpus is untouched
+  (33/33); the lab's orw target demonstrated the gap (the demo picked ret2libc on a seccomp'd
+  binary).
+- The shipped `augure` gem now carries the packs, the example fact bases, the docs and the
+  `augure-benchmark` executable (previously checkout-only: consumers could not reproduce the
+  headline concordance claim from an installed gem). `augure-profiler` gets its first real version
+  (0.0.1), a bounded `augure ~> 0.1` dependency and a changelog_uri. Doc drift fixed: 31 input
+  facts, 33 corpus targets, `leaked_address` in the schema table, `#ranking_of` documented.
+- `GadgetHunt.hunt` was O(n^2) in memory traffic: at every offset it copied the remaining section
+  bytes into a fresh EncodedData (~512 GB cumulative for a 1 MB .text). One EncodedData per section
+  now, decoding moves `edata.ptr` instead of copying; the per-decode rescue narrows to
+  DecodeError/ParseError so metasm internal bugs surface instead of masquerading as "not a gadget".
+  Same gadget sets: ROP Emporium parity 8/8, write4 multi-instruction gadgets intact.
+- `Pipeline.analyze` no longer accepts `solver:`: the parameter was accepted and never used, so the
+  API pretended the decision ran an SMT solver while `verify` is the arithmetic feasibility check.
+  The SMT path stays a tested seam (Verifier.payload_fits_smtlib + SmtProcess) wired by consumers
+  who need it; the docstring, reference.md and the new regression spec say so.
+- `Mcts.terminal?` hardcoded `shell`: a pack declaring `terminal: true` (orw provides `flag_read`)
+  could never terminate a plan, so pack-authored terminal semantics - validated by the armor,
+  stored by `merged_model` - were ignored and plans ran on toward a shell the technique never
+  delivers. The model's terminal stages now own the semantics; the built-in model (all terminals
+  provide `shell`) behaves identically, 33/33 concordance.
+- The engine refused to re-derive an existing head: sibling rules sharing a head (the documented
+  way to express OR) lost every reason after the first, so `explain.provenance` contradicted
+  `how-to-write-rules.md` ("the provenance tells which reason fired"). All firings now merge into
+  the head, each attributed to its own rule; verdicts unchanged (33/33 concordance).
+- `plt` facts described every identifier-shaped symbol (`main`, `_start`, `_DYNAMIC`, a local
+  function named `system`...): a local `system` satisfied `app_ret2plt` and the parity subset check
+  could pass for the wrong reason. `plt` now means real dynamic imports only (shndx == UNDEF, FUNC
+  type), regression-tested against a local-system binary; ROP Emporium parity stays 8/8.
+
+### Fixed
+
+- `Shellcode.generate` on Ia32 with a seeded rng crashed (`zero_esi` pool had no x86 key while
+  every x86 stub zeroes `ecx`); the pool is now `zero_ecx`, and the x86 seeds are regression-tested
+  (assembly + decode validity; the live-run proof stays x64 - a 32-bit runner needs gcc multilib).
+- Facts accepted any string atom (`nx("maybe")`, `relro("sorta")`, `canary("ture")`): the fact
+  parsed, the closed-world default was disabled, and every rule of the predicate silently never
+  fired. Closed predicates now validate their value domain (`VALUE_DOMAINS`) at parse and at `add`,
+  loud `MalformedFact` both ways.
+- The pack armor let an invalid `match` pattern (`"("`) and a non-integer or unknown-operator `cmp`
+  (`"26"`, `"gtr"`) through to decision time, where they died as
+  `RegexpError`/`ArgumentError`/`KeyError` - violating the fail-loudly-at-load doctrine. Armor
+  check 7: match patterns precompile and cmp operands/operators type-check at load, all as
+  `PackError`.
+- The fact-atom grammar is enforced at `Facts#add` too (the wall goes both ways): a symbol name
+  from an untrusted binary or a version string from a hostile banner can no longer carry quotes,
+  parens or newlines into a re-parsed facts file - the injected-facts decision manipulation is
+  closed. The profiler's win regex is anchored.
+- The sub-gemspecs (augure-profiler, augure-mcp) declare relative `bindir`/`require_paths` again:
+  absolute values break RubyGems `full_require_paths` (the require path gets joined against the gem
+  dir), so the gems were unrequirable in CI and in the `augure-profile` subprocess. The `files`
+  globs stay anchored to `__dir__` so a gem builds identically from any working directory.
+
+## [0.1.0] - 2026-10-02
+
+### Added
+
+- Project scaffold: gemspec, RSpec, Standard linting, CI skeleton.
+- Core decision layer: Facts (strict parser), Rules-as-data + Engine with
+  provenance, Bandit (seeded Thompson sampling), MCTS planner, KnowledgeBase
+  (TF-IDF + prior calibration), Verifier with SMT-LIB subprocess boundary,
+  Pipeline facade and `augure analyze` CLI.
+- CTF benchmark corpus: 34 targets across ROP Emporium, Protostar, Phoenix
+  and pwnable-style suites; 5 MCTS planning scenarios; byte-identical parity
+  with the frozen Python engine (24/24 classification, 5/5 plans).
+- Extended technique vocabulary, all documented by public suites:
+  fmtstr_leak, ret2dlresolve, ret2csu, stack_pivot, got_overwrite.
+- `augure-benchmark`: per-suite concordance harness with exit-code gate;
+  dedicated CI job.
+- `augure-profiler` gem (metasm isolated, LGPL): ELF in, facts out -
+  checksec, PLT imports, unsafe-symbol hints, semantic gadget
+  classification; `augure-profile` CLI; compiled-binary test suite.
+- Documentation: commercial README (mermaid pipeline), Diataxis suite
+  (tutorial, how-tos, reference, architecture), auditability page with
+  red/blue/purple team sections.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Epp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,217 @@
+# augure
+
+![augure - the augur reads the birds: facts converge, the verdict is a star](docs/art/augure-v1.png)
+
+**The auditable exploitation decision layer.**
+
+> *Augur (n.): a Roman official who read the signs, announced the strategy,
+> and kept the record. Before any legion moved, someone had to decide -
+> and account for the decision.*
+
+---
+
+[![CI](https://github.com/log0u7/augure/actions/workflows/ci.yml/badge.svg)](https://github.com/log0u7/augure/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/augure)](https://rubygems.org/gems/augure)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.4-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Every exploitation framework answers *"how do I run this technique?"*.
+**Augure answers the question nobody automates: *"which technique should run,
+and why - provably?"***
+
+An LLM will confidently recommend `ret2libc` against a target with no libc,
+because it generates text, not proofs. Augure generates proofs, not text:
+
+- **Propose** - Datalog rules over the target's fact base select every
+  applicable technique. Decidable, terminating, readable.
+- **Verify** - arithmetic and SMT-LIB checks confirm the selected technique
+  is *numerically feasible*, not merely logically applicable.
+- **Explain** - every decision ships with its provenance: every rule that
+  fired (siblings included, each attributed), the facts that justified it,
+  the Beta prior and the seeded draw that ranked it.
+  Same input + same seed = same decision. Always.
+
+## Why it exists
+
+When an exploit developer picks a technique - *"this is a ret2libc situation"* -
+that pick is a **heuristic**, and heuristics are local optima: fast, usually
+right, never systematically tested. Augure is the test rig for those local
+optima. Run your intuition against the frozen CTF corpus and watch the
+weight inversions: humans overweight shellcode and `ret2libc`; the data
+underweights them. `ret2plt` - the boring, reliable one - was massively
+underrated.
+
+That is the product. Not autonomy. **Accountability.**
+
+## Quickstart
+
+```sh
+gem install augure
+augure doctor                              # verify the environment
+augure analyze examples/ret2win.facts      # your first decision
+```
+
+(The `examples/` ship in the gem; in a repo checkout the same paths work
+from the repo root. Not published yet? The sibling lictor checkout
+resolves augure by path - its Gemfile says so.)
+
+Profile a real binary into facts, then decide on them:
+
+```sh
+augure-profile app.elf -o target.facts   # gem augure-profiler (metasm)
+augure analyze target.facts
+```
+
+```sh
+$ augure analyze target.facts
+applicable: ret2plt, rop
+selected:   ret2plt
+plan:       ret2plt
+  ret2plt <- app_ret2plt (vuln=sof, nx=true, pie=false, plt=system)
+  rop <- app_rop (vuln=sof, nx=true, enough_gadgets=true)
+```
+
+Or the machine-readable form:
+
+```console
+$ augure analyze target.facts --json
+{
+  "schema":     "augure/decision@1",
+  "applicable": ["ret2plt", "rop"],
+  "ranking":    ["ret2plt", "rop"],
+  "verified":   { "ret2plt": { "status": "sat", "checks": { "payload_fits": "sat" } },
+                  "rop":     { "status": "sat", "checks": { "payload_fits": "sat" } } },
+  "selected":   "ret2plt",
+  "plan":       ["ret2plt"],
+  "explain": {
+    "provenance": {
+      "ret2plt": [{ "rule": "app_ret2plt", "origin": null,
+                    "evidence": [["vuln", "sof"], ["nx", "true"], ["pie", "false"], ["plt", "system"]] }]
+    }
+  }
+}
+```
+
+From Ruby:
+
+```ruby
+require "augure"
+
+result = Augure::Pipeline.analyze(facts: File.read("target.facts"), seed: 42)
+
+result[:selected]          # => "ret2plt"
+result[:explain]           # => { provenance: { "ret2plt" => [{ rule:, origin:, evidence: [...] }] } }
+```
+
+## What is in the box
+
+| Layer | Module | What it does |
+|---|---|---|
+| Facts | [`Augure::Facts`](docs/reference.md#fact-format) | Strict, schema-checked fact parser. Malformed input fails loudly, never silently. |
+| Rules | [`Augure::Rules`](docs/how-to-write-rules.md) | Rules-as-data: the single source of truth for applicability. |
+| Engine | [`Augure::Engine`](docs/reference.md#augureengine) | Forward-chaining evaluation with per-decision provenance. |
+| Verifier | [`Augure::Verifier`](docs/reference.md#augureverifier) | Arithmetic fast path + SMT-LIB emission. |
+| Solvers | [`Augure::SmtProcess`](docs/how-to-swap-solver.md) | Subprocess boundary to z3 / bitwuzla / cvc5. Timeout = `:unknown`, never a crash. |
+| Knowledge | [`Augure::KnowledgeBase`](docs/reference.md#augureknowledgebase) | 22 documented exploitation patterns; TF-IDF retrieval; Beta prior calibration. |
+| Bandit | [`Augure::Bandit`](docs/reference.md#augurebandit) | Thompson sampling over Beta posteriors, seeded and auditable. |
+| Planner | [`Augure::Mcts`](docs/reference.md#auguremcts) | Multi-step planning: a leak is worth what it unlocks. |
+| CLI | [`exe/augure`](docs/tutorial.md) | Facts in, decision out, JSON if you want it. |
+
+**Zero runtime dependencies.** Every external capability (SMT
+solvers, LLM providers) enters through a subprocess or HTTP boundary.
+
+## How the decision flows
+
+```mermaid
+graph LR
+    B["binary<br/>(augure-profiler)"] --> F["Augure::Facts<br/>strict schema<br/>+ value domains"]
+    F --> E["Augure::Engine<br/>Datalog rules-as-data"]
+    P["technique packs<br/>(build: / detection: / mitre:)"] -- "armored + corpus-guarded" --> E
+    E -- provenance --> D
+    E --> V["Augure::Verifier<br/>arithmetic / SMT-LIB"]
+    V --> B1["Augure::Bandit<br/>Beta posteriors"]
+    B1 --> M["Augure::Mcts<br/>multi-step plan (model-owned terminals)"]
+    M --> D["decision + explain<br/>augure/decision@1"]
+    KB["KnowledgeBase<br/>22 documented patterns"] -. priors .-> B1
+    SOLV["z3 / bitwuzla / cvc5<br/>(subprocess)"] -. SMT-LIB text .-> V
+    D --> COV["augure coverage<br/>the corpus read backwards"]
+```
+
+## Honest numbers
+
+Augure's decision engine reproduces the frozen CTF benchmark corpus
+byte-for-byte - **33/33** technique classifications across ROP Emporium,
+Protostar, Phoenix and pwnable-style targets (16 built-in technique
+heads plus the 20 taught technique packs),
+and 5/5 multi-step plans including an externally documented kernel chain.
+CI runs [`augure-benchmark`](docs/reference.md#cli) and fails the build below 100%.
+
+Read that carefully: these are **predictions against frozen ground truth**,
+not field results. The success probabilities in the prior table are
+*authored, not measured*. Augure is an auditable decision layer, and the
+audit begins with this sentence.
+
+| Claim | Evidence |
+|---|---|
+| 33/33 classification parity | `lib/augure/ctf_corpus.json`, `spec/augure/engine_spec.rb` |
+| 5/5 plan parity (incl. PinTheft kernel chain) | `spec/augure/mcts_spec.rb` |
+| Ruby engine == frozen Python engine | corpus conformance specs, CI-enforced |
+| MEASURED vs a typed-decision classifier (Laya, open weights): 5/5 vs 1/5 on the discriminantes, 8.5 ms vs ~3-5 s on CPU | `pappers/laya-bench.py`, the measurement story in the augure-lictor draft |
+
+## Why not just ask an LLM?
+
+| | LLM alone | Augure |
+|---|---|---|
+| recommends `ret2libc` with no libc | confidently | structurally impossible (a rule forbids it) |
+| the 5 discriminantes (the fact text as state, the 16 heads as choices, measured) | a typed-decision model answered **1/5**, confident-and-wrong (0.93-0.98 on its errors) | **5/5**, 8.5 ms warm with the MCTS |
+| explains *why* | plausible prose | rule ID + facts + checks + seeded draw |
+| reproducible | no | same seed, same decision |
+| terminates | usually | provably (Datalog) |
+| audit trail | chat log | machine-checkable provenance |
+
+They compose: an LLM proposes hypotheses, Augure disposes. That is the
+generate-then-verify pattern the planning literature names LLM-Modulo
+(Kambhampati et al., ICML 2024) and that CHECKMATE (Wang et al., 2025)
+measured at +20% penetration success. The shipped **augure-mcp** gem
+exposes exactly that read-only surface (analyze_target, list_rules,
+explain_technique) to agents.
+
+## Acceptable use
+
+Augure is a **decision layer**. It contains no exploit code, executes
+nothing, and touches no target. It encodes technique *metadata* - rules,
+facts, feasibility checks - the same class of knowledge as a public
+write-up. Use it for:
+
+- security research, CTF preparation and training;
+- red-team engagement planning where you are authorized to operate;
+- defensive analysis: the same model read backwards tells you which
+  techniques your estate makes impossible.
+
+Do not use it to attack systems you do not own or are not explicitly
+authorized to test.
+
+## License
+
+MIT. The `augure-profiler` gem depends on metasm, LGPL-2.1, used as an
+external library in the readline style.
+
+## Documentation
+
+The architectural renouncements and deferrals are recorded as ADRs in
+[docs/adr/](docs/adr/): the arch abstraction before any port (0001), ARM64
+deferred behind it (0002), PE/Windows out of scope for v0.x (0003).
+
+| I want to... | Read |
+|---|---|
+| get my first decision in 10 minutes | [the tutorial](docs/tutorial.md) |
+| see what hardening kills (the blue scorecard) | `augure coverage --flip canary:true` |
+| align with ATT&CK (purple) | `augure rules --mitre --packs packs --json` |
+| write my own technique rules | [rule-writing how-to](docs/how-to-write-rules.md) |
+| teach augure a technique (packs) | [the pack format](docs/pack-format.md) |
+| read the published lineage and where this project stands on it | [build-format](docs/build-format.md) |
+| plug a real SMT solver | [solver how-to](docs/how-to-swap-solver.md) |
+| look up the fact format or API | [the reference](docs/reference.md) |
+| understand auditability (red/blue/purple) | [auditability](docs/auditability.md) |
+| understand why rules-as-data | [architecture](docs/explanation-architecture.md) |
+| brief an LLM agent on the pair | [the agent snippet](docs/agent-snippet.md) |

data/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/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

data/home/runner/work/augure/augure/docs/agent-snippet.md

@@ -0,0 +1,31 @@
+# Agent snippet: paste into your project's AGENTS.md
+
+```markdown
+## augure/lictor - the auditable exploitation decision layer
+
+- augure DECIDES (verified techniques + provenance); lictor ORCHESTRATES
+  (authorization + trail). I propose; augure disposes. I never claim a technique
+  augure did not rank, and I quote decisions as predictions with
+  provenance, never as proven results.
+- Loop (all recorded in the trail): `lictor doctor` ->
+  `lictor scan <host>` -> `lictor acquire <target>
+  --from <url>|-bin <path>` -> [optional discovery: `lictor fuzz`,
+  `lictor verify`] -> `lictor suggest <facts> "plt(\"system\")."`
+  (propose observations; the delta comes back) -> `lictor plan
+  <binary-or-facts> [--json]` -> `lictor build <binary>
+  --facts <facts>` (offset measured, payload file) ->
+  `lictor exploit scaffold <technique> <binary> --facts <facts>
+  --repo-dir DIR` (no exploit in the repos? the draft lands, review it)
+  -> `lictor draft <facts> [binary]` (nothing applies? a staged pack)
+  `lictor run <target> --facts <f> --executor ronin`
+  -> `lictor outcome <run-id> --success|--failure --technique <t>` ->
+  `lictor report`. Full skill: augure/skills/augure-operator/SKILL.md.
+- New technique = a PACK (YAML data, never code): copy
+  `augure/packs/ret2csu_v2.yml`, validate with `lictor rule validate`,
+  install only with operator confirmation. The corpus guard refuses
+  packs that move frozen verdicts - read the refusal, fix the data.
+- Authorized use only: the operator decides the scope, the trail
+   records it. No
+  exceptions. The trail is never edited.
+- Payload contract: `--json` emits schema "augure/decision@1".
+```