augure

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.

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.

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.

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:

augure-profile app.elf -o target.facts   # gem augure-profiler (metasm)
augure analyze target.facts

$ 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:

$ 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:

require "augure"

result = Augure::Pipeline.analyze(facts: File.read("target.facts"), seed: 42)

result[:selected]          # => "ret2plt"
result[:explain]           # => { provenance: { "ret2plt" => [{ rule:, origin:, evidence: [...] }] } }

Zero runtime dependencies. Every external capability (SMT solvers, LLM providers) enters through a subprocess or HTTP boundary.

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"]

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 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.

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.

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.

MIT. The augure-profiler gem depends on metasm, LGPL-2.1, used as an external library in the readline style.

The architectural renouncements and deferrals are recorded as ADRs in docs/adr/: the arch abstraction before any port (0001), ARM64 deferred behind it (0002), PE/Windows out of scope for v0.x (0003).