lictor 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e9c7b5e421a9542337e32d066b0cbe509b497f7d79184e6db586056758cef7f
+  data.tar.gz: 6ee268badd063fbb9339a399ab63051155a3fde7956edb0b49840376b0b03eb2
+SHA512:
+  metadata.gz: dc09b6af16b52923a4ec5daee3d0b348ff0223b7a49262d037c439bc0ab04ea01de6006a3cd5fb6530217571638ffecfa78e4ef0f21cee2c5a5a54b85a324012
+  data.tar.gz: 7f881208f341632cf934bb79bda0531e30d35a83caf5e4cb83b687d29282a4ef6dff3fdbf6c1cf499cbc26f51cd79f23825b69825dfdb066b3720a5b030a3962

data/CHANGELOG.md

@@ -0,0 +1,240 @@
+# 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]
+
+## [0.4.0] - 2026-10-29
+
+- The lab grows to eight targets: the ROP Emporium pair (callme,
+  ret2csu) joins as binary-only services - the challenge binaries and
+  their companion libraries vendored under `lab/targets/` with the
+  provenance noted, served through wrapper scripts (the loader needs
+  `LD_LIBRARY_PATH`, the lib opens the encrypted flag relative to the
+  cwd). The demo walks them like the rest: acquire, suggest (the
+  unbounded copy is a read), the pack-taught layout builds the payload
+  (measured offset), the discovered exploit lands the flag. The build
+  fetches the companion library beside the measured binary so the
+  debugger's cyclic run resolves it.
+- The ret2plt loop is deterministic: the service's copy is bounded by
+  the read length (`memcpy`, not `strcpy`), so the read channel carries
+  NUL bytes and the textbook chain rides whole - the banner's leaks aim
+  pop rdi (entry+4), the service's own command string and system, the
+  chain enters system at the ABI alignment (measured under gdb,
+  30/30 connections land the flag). The demo's oracle is now the
+  target's own flag (success means THIS target's flag, a wrong flag
+  fails), and the ret2plt source knowledge (`vuln("sof")`) enters
+  through suggest like fmtstr's.
+
+- The ret2plt loop is deterministic: the service's copy is bounded by
+  the read length (`memcpy`, not `strcpy`), so the read channel carries
+  NUL bytes and the textbook chain rides whole - the banner's leaks aim
+  pop rdi (entry+4), the service's own command string and system, the
+  chain enters system at the ABI alignment (measured under gdb,
+  30/30 connections land the flag). The demo's oracle is now the
+  target's own flag (success means THIS target's flag, a wrong flag
+  fails), and the ret2plt source knowledge (`vuln("sof")`) enters
+  through suggest like fmtstr's.
+- README banner recompressed: `lictor-v1.png` 1.9M -> 969K (256-color palette
+  with dithering; repo weight only, no content change). `lictor-v0.png` and
+  `demo.gif` are untouched.
+- The demo tape is self-sufficient and leak-free: the setup line (workdir
+  creation, `lictor.yml`, PATH, starship stripping) is typed under `Hide`/`Show`
+  so nothing of the host ever shows in `docs/art/demo.gif`, the workdir
+  `/tmp/lictor-demo` is created by the tape itself (a skipped manual step used
+  to leave the whole render in the caller's CWD, which broke the final trail
+  tail), and the repo root is referenced as `$PWD` captured before the `cd` -
+  no laptop path on screen.
+- The demo's closed loop lands the flag on screen: the tape's `--flag-regex`
+  carried doubled backslashes (vhs sends the typed string verbatim, bash
+  single quotes preserved them, the oracle regex matched a literal backslash
+  and never fired - three executed/failed attempts in every render). The
+  regex is now backslash-free (`FLAG[{][^}]*}`). And `lictor run` surfaces
+  the flag the executor reports: the successful attempt prints
+  `flag: FLAG{...}` after the steps - the proof the loop closed, since the
+  exit code lies both ways.
+
+- The engagement flow without flags: `lictor acquire <name>` resolves the source from the target's registry entry (the `--from`/`--bin` recorded at `target add`) - one `target add` and the acquire needs no flags; the explicit flags still override.
+
+- The ROP chaineur: the build layout gains the `chain` slot - one arch-width word per
+  reference, resolved in order against the facts (`gadget:TYPE`, `plt_addr:NAME`,
+  `got_addr:NAME`, `win`, `leak:NAME`, `const:N`), loud BuildError on any missing piece.
+  `ret2plt` (the puts@got leak chain) and `ret2libc` (post-leak: ret-align + pop_rdi +
+  binsh + system) ship as built-in layouts; a pack's `build:` teaches chains for its own
+  techniques.
+- `Lictor::Tube`: the ONE TCP implementation behind the banner readers (ADR 0001) -
+  connect, read_until (EOF/reset/deadline/limit), write, reset tracking. `harvest` and
+  `verify` consume it; `verify` honours `--facts` (it used to append to a hardcoded
+  `target.facts` in the CWD, ignoring the flag).
+- The success oracle reads the FLAG, not the exit code: `run --flag-regex RE` makes the
+  flag pattern in the runner's output the success semantics (a polite exploit exits 0 on
+  failure, a caught-cleanup exploit exits non-zero after landing the flag - the exit code
+  lies both ways). Without the regex the exit code stays the oracle, the honest weaker
+  fallback.
+- The two-steps state: the run's leak capture - the service's own output hex addresses
+  become `leaked_address` facts for the NEXT attempt (trailed as `leak` events), so a
+  leak technique followed by a rebuild technique resolves its `leak:NAME` refs from the
+  observed values. The boundary stays documented: a leak and its strike inside ONE
+  connection is the operator's exploit craft (the scaffold pattern), not the loop's.
+- The run manifest + resume (ADR 0003): one stable run id per logical run - every trail
+  event carries it, the CLI prints it with the resume hint; the state (facts with the
+  merged leaks, the attempt history) lands on disk per attempt (`run.json` in the target
+  dir); `lictor run --resume <id>` continues THAT run - an interruption is a pause, not
+  an orphan.
+- Named targets (ADR 0003): `lictor target add <name> <host:port> [--from URL | --bin
+  PATH]` scaffolds `targets/<name>/` (facts, payloads, its own trail) and registers it
+  in `targets.yml`; `--target NAME` scopes acquire/plan/build/run/fuzz/verify/harvest
+  state into the dir - the CWD-global `target.facts` clobbering is dead, two targets
+  coexist.
+- Per-target priors: the isolation comes from the scoped trail (the `--target` trail
+  file IS the scope) - a failure on target A shifts A's decisions, B stays at the
+  defaults; proven by the isolation spec.
+- `lictor report --defender`: the blue-side view of the SAME trail - the raw action
+  timeline (the scans, the banners read, the payloads sent, the techniques attempted
+  with their verdicts) plus, per attempted technique, the pack's `detection:` hints.
+- The hardening matrix in the lab: the same sources compiled canary+PIE+full-RELRO+
+  FORTIFY, served on the 889x ports; `lab/purple.sh` replays the purple loop - `augure
+  coverage` flips against the corpus, `lictor report --defender` reads an attack trail.
+- The lab gains the missing targets: `uaf_heap` (9995, tcache UAF with the fn pointer
+  on the heap - the 8 heap packs finally have a bench) and `orw` (9994, seccomp filter:
+  execve dies). The builder is seccomp-aware: a `sh` stub under `seccomp("true")` is a
+  booby trap, so the slot switches to the orw chain (open/read/write, clean exit) with
+  the flag path embedded. The `orw` technique ships as a built-in layout.
+- ADRs: docs/adr/ records the architectural decisions - the Tube as the transport seam
+  (0001), verify as the arithmetic check with SMT a seam not a promise (0002),
+  engagement state as a directory per target, no database (0003).
+
+### Changed
+
+- The speed pass (zero verdicts moved): the profiler's gadget scan precompiles its patterns and scans with String#index - profiling a 1MB binary drops 6.07 s to 58 ms (augure side, 45x); StaticOffset runs the cheap e8 scan first (the whole-text disassembly is the last resort - the >600 s hang on a 1 MB text dies); the MCTS depth-bounds the degenerate tree; the corpus guard memoizes; the CLI lazy-loads metasm (the fuzz/draft/scaffold paths load it on use); the build loads its packs once. The augure before/after table lives in augure/tools/bench.rb, the lictor one in tools/bench.sh.
+
+- The report carries the WHOLE trail: `Trail#runs` maps acquire, build (offset, ret
+  source, size), scaffold, harvest, verify, suggest, leak and fuzz - the auditable
+  deliverable no longer omits most of the audit. `report --json` renders the same
+  completeness.
+- The lab is six targets (+3 hardened mirrors); the demo walks suggest-then-decide for
+  the source knowledge (heap class, seccomp filter, controlled format) and
+  harvest-then-build for the orw chain.
+- The capabilities table documents the new surfaces: the chain-slot build, the suggest
+  `-o` write-back, `harvest --facts`, the `run --flag-regex` oracle and the leak capture.
+
+- The run's static enrichment died silently when the lazy metasm require moved (a NameError swallowed by the block's bare `rescue`): the enrichment now trails a `measure` event (the sink, the offset, the source - the report renders it) and the rescue catches only the KNOWN failure modes (the metasm decode family, the file errors) - a programming error crashes loudly instead of vanishing. The regression spec asserts the event's presence: its absence is the red flag.
+
+- `suggest` and `harvest` never persisted their results: the merged fact base was
+  printed then dropped (the docs even claimed the tool "merges into the base"), and the
+  harvest's leaked addresses existed only on stdout - the agent-enrichment loop was a
+  dry-run simulator. `suggest -o PATH` writes the merged base, `harvest --facts PATH`
+  appends the leaked_address facts; regression-tested with a fake banner server.
+- The safe default poisoned the learning: a handoff attempt (manual executor, nothing
+  executed) was recorded as `success: false`, and `Priors.from_trail` counted it - every
+  handoff-only run systematically downgraded the decided technique for all future
+  decisions. The outcome is trailed only when something actually ran; a handoff run
+  stops after one recipe (nothing changes between attempts) with status `handoff`; a
+  fresh auto-scaffold still continues the loop.
+- `lictor build` never consulted pack `build:` sections: `layout_for` read packs but
+  `build()` passed none, and `augure::Pack` had no `build` accessor at all (the pack DSL
+  wrote a section nothing could read). Armor check 8 on the augure side validates the
+  optional `build:` (own technique, slot vocabulary); the builder accepts `packs:` and
+  the CLI passes the loaded packs. A pack teaching a NEW technique now materializes its
+  own layout.
+- The `dword` slot packed with the arch width (8 bytes on x64): a partial-overwrite
+  layout emitted the wrong payload. `dword` is 4 bytes whatever the arch; `qword` is the
+  pointer width.
+- One auto-scaffold per technique per run: the loop continued on a fresh scaffold (the
+  next attempt discovers it) but re-scaffolded the SAME technique on every further
+  attempt, hitting the scaffold's already-exists refusal.
+- The executor timeout kills a black-holed runner instead of hanging forever.
+
+## [0.3.0] - 2026-10-04
+
+### Changed
+
+- **v0.3.0: the operator is the authorization.** The gates and the consent tokens are
+  GONE - no allowlist file, no tokens, no typed confirmations (the review caught `run`
+  minting its own consent with the target as its own confirmation). The README carries
+  the authorized-use disclaimer; the trail is the record. `lictor init` scaffolds the
+  trail only; the doctor checks the environment only (gdb/ronin/docker as warns with
+  exact fixes).
+- v0.3.0 in the gem: the operator-is-the-authorization model (consent and the allowlist
+  are gone, the trail is the record), the gemspecs say so, the gem ships the build
+  layouts and the scaffold template (`gem build` no longer produces a dead artifact),
+  `Unauthorized` is deleted.
+- The demo and every doc reflect the current commands: the harvest act replaces the
+  consent act, the chain is scan → acquire → suggest → harvest → plan → build → run →
+  outcome → report.
+
+### Removed
+
+- The consent system and the allowlist (the operator is the authorization; the trail is
+  the record). The gate-era `-a`/targets.yml spec residue went with them.
+- The dead empty `begin` in the plan command and the MCP's six `Unauthorized` rescues
+  (the class is gone).
+
+### Fixed
+
+- The trail of offensive operations was world-readable: `record` now creates the JSONL
+  0600 (existing files keep the operator's perms). The profiler and acquire subprocesses
+  hang forever on a wedged binary: both carry a 300 s timeout raising a loud error.
+- `lictor acquire` surfaces the profiler's stderr in the failure message (the profiling
+  subprocess used to die silently and the error said nothing).
+- The gemspecs build identically from any working directory: `files` globs anchor to
+  `__dir__` and lictor-mcp reads its version from `lib/lictor-mcp/version.rb`.
+- `lictor run` failure is truthful now: the lab exploit raises when the flag does not
+  come, so ronin's exit code can no longer lie about the success (the `--flag-regex`
+  oracle supersedes even this).
+
+## [0.2.0] - 2026-10-03
+
+- `lictor plan <binary>`: ELF magic detection profiles the binary
+  through the augure-profile subprocess (trailed), then decides. A
+  `.facts` file passes through unchanged. One command from binary to
+  decision.
+- `lictor scan`: nmap as a gated, trailed action against an allowlisted
+  host (subprocess; --nmap override for testing). Scans appear in
+  `runs` and in the engagement report.
+- Network facts: service/software_version/remote emitted from nmap
+  scans; remote technique packs match them like binary facts.
+- Fuzzing and triage (augure-profiler): RubyMutator built-in + radamsa
+  optional; GdbBackend (real run covered), RizinBackend, LldbBackend;
+  `lictor fuzz` gated and trailed.
+- Executor interface: ManualExecutor (default, handoff) + RoninExecutor
+  (discovery from the operator's repos; fabricated names refused).
+- `lictor run`: the closed loop - decide, execute, outcome, re-decide -
+  with budgets and interactive confirmation.
+- Consent tokens: `lictor authorize <target>` - human-typed, TTL'd,
+  trail-recorded.
+- lictor-mcp (4th gem): scan/plan/execute/validate_pack tools with
+  server-side gates and token validation.
+- `lictor rule validate|install|list`: teach augure techniques as data
+  (packs), full armor + corpus guard.
+
+### Removed
+
+- `--i-am-authorized` and `--target` flags: security theater. A flag
+  can be typed by reflex, by a script, or by anyone with shell access -
+  it proves nothing and taxes the legitimate user. Authorization is the
+  allowlist artifact (explicit host[:port] entries, colon-delimited
+  prefix match so .1 cannot pass for .10) plus the trail. A future
+  execute command will confirm interactively (show the recipe, type the
+  target), never through a flag.
+
+## [0.1.0] - 2026-10-02
+
+- Project scaffold: authorization gates design, handoff-default README,
+  CI (gitleaks), MIT license, AGENTS.md.
+- Gates: explicit allowlist (wildcards rejected), per-run consent flag,
+  allowlist-checked `--target`.
+- Recon: nmap XML to target inventory via ruby-nmap; `lictor recon`
+  prints allowlist candidates (candidates, never authorization).
+- Handoff default: augure decision printed as a ronin-exploits recipe
+  with mixin hints (Binary / FormatString); exploit names deferred to
+  the operator's ronin repos.
+- The closed loop: `lictor outcome` records results, outcomes feed the
+  augure bandit priors (`Lictor::Priors.from_trail`), the next decision
+  adapts - end to end trailed.
+- JSONL trail with run aggregation (`lictor runs`).
+- Engagement report: auditable markdown (decision, rule provenance,
+  outcome) with the claims-discipline line; `lictor report -o`.

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,285 @@
+# lictor
+
+![lictor - the fasces of fiber, the trail behind, the open door ahead](docs/art/lictor-v1.png)
+
+**The orchestrator that carries out augure's judgments: nmap, fuzzing,
+profiling, execution - every action recorded, handoff by default.**
+
+> *Lictor (n.): the magistrate's attendant who carried the fasces and
+> executed judgments. He did not judge. He executed what was judged.*
+
+[![CI](https://github.com/log0u7/lictor/actions/workflows/ci.yml/badge.svg)](https://github.com/log0u7/lictor/actions/workflows/ci.yml)
+[![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)
+
+**v0.3.0** - pairs with [augure](https://github.com/log0u7/augure), the
+auditable exploitation decision layer. augure decides; lictor executes;
+the trail records everything.
+
+> **Authorized use only.** This tool is for legally authorized security
+> assessments and CTF labs. You are the operator: what it does, you
+> did. Know the law where you stand.
+
+## Why lictor
+
+Most automation in offensive tooling is a black box: it fires and you
+find out why afterwards - or never. lictor inverts that:
+
+- every technique choice comes from a **verified rule with its
+  evidence** (augure's explain payload: rule ID, facts, seeded draw);
+- every action is **trailed** - one JSONL line, attributable, replayable;
+- the dangerous edge - execution - is opt-in: the default executor is
+  the handoff, which prints the recipe and runs nothing.
+- the mirror is the analysis target: the scan identifies, the local
+  reproduction gets profiled and built against, `verify` proves the
+  remote faults like the local model.
+
+Equally strict when an LLM agent drives it through MCP. The brakes are
+not a mode - they are the design.
+
+## The 60-second demo
+
+![lictor demo: scan, decide with provenance, run, and the auditable trail](docs/art/demo.gif)
+
+Replay it yourself against the lab:
+
+```sh
+sh lab/demo.sh
+```
+
+The full chain is: **scan → acquire/mirror → (fuzz → triage) →
+verify → suggest → harvest → plan → build → run → outcome → report**,
+every step recorded in the trail (one stable run id, the manifest
+written per attempt), the decision explained rule-by-rule.
+`harvest` reads the service banner's hex leaks into `leaked_address`
+facts; `suggest` is the agent's own step
+`suggest` is the agent's own step: propose observations as facts, get
+the decision delta back
+(see [docs/how-to-llm-suggestions.md](docs/how-to-llm-suggestions.md));
+`build` is the payload step: the offset is measured, the bytes are
+assembled (below). When discovery finds NO exploit for the decided
+technique, the run scaffolds it and the next attempt uses it; when NO
+technique applies to the crash, `lictor draft` writes a staged pack
+from the observations - the loop feeds augure back.
+
+## Named targets: the engagement model
+
+State is scoped per target (ADR 0003), not clobbered in the CWD:
+
+```sh
+lictor target add web01 10.0.0.5:9999 --from http://10.0.0.5:8000/binary
+lictor --target web01 acquire web01     # or: acquire web01 --target web01
+lictor --target web01 plan              # reads targets/web01/target.facts
+lictor --target web01 run web01 --facts targets/web01/target.facts \
+  --executor ronin --flag-regex "FLAG\{[^}]+\}"
+lictor run ... --resume <run-id>        # the manifest is written per attempt:
+                                        # an interruption is a pause, not an orphan
+```
+
+`targets/<name>/` holds the facts, the payloads and the trail; the
+registry is `targets.yml`. Priors are per-target by construction (the
+scoped trail IS the scope): a failure on A does not shift B's
+decisions.
+
+The same loop exports as a BENCH: `sh lab/bench.sh` renders the
+engagement's trail as `lictor/bench@1` - the tasks/actions/feedback
+telemetry the LLM benchmarks read (NYU CTF Bench, InterCode). The
+agent proposes, augure disposes, lictor executes, and the whole run
+is the measurement.
+
+## From decision to payload: the offset is measured, not guessed
+
+`lictor build` carries the original tool's inheritance - with every
+number auditable instead of assumed:
+
+- the **offset is measured**: the frame read statically (ret2win x64 =
+  40, the canonical number) or the cyclic pattern crashed under the
+  debugger - never a magic constant;
+- the **return address comes from the facts**: the winning symbol's
+  address, the gadget facts, or the addresses the service's own banner
+  leaked (`lictor harvest`);
+- the **shellcode is assembly source** (execve, bash -p, the orw chain
+  for seccomp targets) assembled on demand by metasm - no hex blobs;
+- the result is a payload file the trail records and `lictor run
+  --payload` sends as-is. When the flag does not come, the exploit says
+  so and the run says failed.
+
+```sh
+lictor build ret2func --facts target.facts -o payload.bin
+# technique:  ret2func
+# offset:     16  (measured)
+# ret:        win_symbol:win@4198870
+# payload:    payload.bin (24 bytes, arch x64)
+lictor run 127.0.0.1:9999 --facts target.facts \
+  --executor ronin --payload payload.bin
+```
+
+The slot vocabulary, the metasm usage step by step, and the published
+lineage (metasm SSTIC 2007 -> the SSTIC 2008 deprotection paper ->
+esec-lab 2010 -> miasm 2012 -> the 2015 ghost-writing technique) live
+in [augure/docs/build-format.md](../augure/docs/build-format.md).
+
+## Capabilities
+
+| Command | What it does |
+|---|---|
+| `target add / list` | Named targets: a dir per target (facts, payloads, its own trail) + the `targets.yml` registry; `--target` scopes every command. |
+| `init` / `doctor` | Scaffold the engagement setup; verify the environment (exact fix per check; gdb/ronin/docker as warns). |
+| `recon <nmap.xml>` | Print the service candidates from an nmap XML (passive, never scans). |
+| `runs` | List the trailed runs. |
+| `scan <host>` | nmap against a target; the scan is recorded. |
+| `acquire <target>` | The lab convenience: copy or download the binary when the target serves it. The real flow is the MIRROR (below). |
+| `fuzz <binary>` | Fuzz + triage a local binary: the fact **discovery** layer. Length sweep + mutations; gdb/rizin/lldb backends. |
+| `verify <target>` | The differential: the crash input faults the remote like the local model → the facts become `remote-verified`. |
+| `harvest <target>` | The banner's hex leaks become `leaked_address` facts - `--facts PATH` appends them. |
+| `plan <binary-or-facts>` | Profile if ELF, decide (augure), print the recipe. |
+| `build <binary>` | Assemble the payload for the selected technique: measured offset (cyclic pattern under the debugger), fact-sourced return address, metasm-assembled shellcode. Layouts cover the ROP chains (`chain` slots resolve `gadget:`/`plt_addr:`/`got_addr:`/`leak:`/`const:` refs from the facts, loud `BuildError` on any missing piece); under seccomp the `sh` stub switches to the orw chain. |
+| `suggest <facts>` | The agent proposes observations as facts; augure re-decides and the delta comes back - `-o PATH` writes the merged base, so the enrichment is not a dry run. |
+| `draft <facts>` | No technique applies? The observed facts + the measured constants draft a PACK in the staging dir, armor-validated, for the operator to review and install. |
+| `exploit scaffold <technique>` | Draft the ronin exploit for a decided technique: the measured constants embedded, the payload loader wired - review, commit, run. |
+| `run <target>` | The closed loop: decide, execute, outcome, re-decide - with an attempt budget, `--flag-regex` as the success oracle (the flag in the output, not the exit code), the leak capture (the output's hex addresses become facts for the next attempt) and the run manifest (`--resume <id>` continues an interrupted run). |
+| `outcome <run-id>` | Record the result; the next decision adapts the priors. |
+| `report` | The auditable engagement report (markdown, provenance included) - `--defender` renders the blue-side view: the action timeline + the packs' `detection:` hints. |
+| `rule validate/install/list` | Teach augure a new technique - as data, through the armor. |
+
+## The operator is the authorization
+
+No gates, no tokens. You decide what to target; the trail records what
+was done:
+
+1. **Handoff is the default.** `plan` prints the recipe and executes
+   nothing; `run` with the ronin executor is opt-in and budgeted.
+2. **The trail is append-only.** Decision → rule provenance → action →
+   outcome. An engagement you cannot replay is an engagement you cannot
+   defend.
+3. **The mirror is the analysis target.** The scan identifies
+   (service + version); when the remote cannot be profiled, you stand
+   up the SAME service locally - your package, your install - and
+   lictor scans+profiles the mirror, builds on its facts, and `verify`
+   proves the remote faults like the local model before anything runs
+   for real.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph scope ["SCOPE - the engagement (ADR 0003)"]
+        T["lictor target add<br/>targets.yml registry"] --> TD["targets/NAME/<br/>facts, payloads, trail"]
+    end
+
+    TD --> F
+
+    subgraph decide ["DECIDE - the augure SDK"]
+        ELF["acquired binary<br/>(the MIRROR)"] --> PRF["augure-profiler<br/>metasm: checksec, gadgets, addresses"]
+        PRF --> F["facts + value domains"]
+        HST["harvest: the banner's leaks"] --> F
+        SUG["suggest: the operator's knowledge"] --> F
+        F --> A["augure Engine<br/>Datalog rules-as-data"]
+        P["technique packs<br/>(build:/detection:/mitre:)"] --> A
+        KB["KnowledgeBase<br/>22 patterns"] -. priors .-> A
+        A --> V["Verifier + Bandit + MCTS"]
+        V --> D["decision + provenance<br/>augure/decision@1"]
+    end
+
+    subgraph act ["ACT"]
+        D -- "handoff (default)" --> H["recipe printed"]
+        D -- "opt-in, budgeted" --> RN["ronin-exploits (subprocess)"]
+        RN --> O["outcome + leak capture"]
+        H --> O
+        O -- "the flag in the output<br/>(--flag-regex oracle)" --> ST["status"]
+        O --> MF["run.json manifest<br/>--resume continues"]
+    end
+
+    MF --> TR["trail (0600)<br/>one id per run, 14 event types"]
+    TR --> RP["report<br/>(--defender: the blue view)"]
+    O -. "outcomes become priors<br/>(per target)" .-> A
+```
+
+## The Ruby-native arsenal
+
+| Need | Gem | Why |
+|---|---|---|
+| nmap XML parsing | [ruby-nmap 1.0.3](https://rubygems.org/gems/ruby-nmap) (postmodern, 703k dl) | the maintained standard; parses XML without running nmap |
+| exploitation runtime | [ronin-exploits 1.1.1](https://rubygems.org/gems/ronin-exploits) + [ronin 2.1.1](https://rubygems.org/gems/ronin) | exploits as Ruby classes, mixins = the technique vocabulary; no daemon, `gem install` |
+| binary analysis | `augure-profiler` (metasm) | pure Ruby, no subprocess, augure's sibling gem |
+| fuzzing | built-in `RubyMutator` (zero-dep) + radamsa optional | the discovery layer for binaries with no write-up |
+| persistence | stdlib JSONL | sequel when queries are actually needed |
+
+**Why not Metasploit?** It IS Ruby - but a monolithic Rapid7 app you
+must install and drive through a daemon. Lictor's path is gems: ronin
+installs as a gem and runs as a subprocess, nothing to daemonize. A
+ready-made msf module is fine for the operator's hands - it is just
+not on lictor's critical path.
+
+## The MCP surface: when an LLM agent drives
+
+[lictor-mcp](mcp_server/README.md) exposes seven tools over stdio - `scan_target`,
+`plan_technique`, `execute_technique`, `suggest_facts`, `build_payload`,
+`scaffold_exploit`, `validate_pack` -
+and validates
+**server-side**: the armor, the corpus guard, the trail.
+The agent proposes; augure disposes; lictor executes - and the checks
+run server-side, so the agent cannot weaken them. Agents teach augure new techniques through the same armor:
+see [augure's pack format](https://github.com/log0u7/augure/blob/main/docs/pack-format.md)
+and the [augure-operator skill](https://github.com/log0u7/augure/tree/main/skills/augure-operator).
+
+## Honest numbers
+
+Read every claim below as a **prediction with provenance**, not a field
+result - the lab is the measurement bench, not the world:
+
+| Claim | Evidence |
+|---|---|
+| ret2func: the built payload lands the real flag, no brute-force | the lab, e2e: build (offset 16 measured) → run → `FLAG{augure_decides_lictor_executes}` |
+| the offset measurement generalizes | static frame read (ret2win x64 = 40, the canonical number) + the cyclic pattern under the debugger, cross-validated on the same binaries |
+| a missing exploit drafts itself | the run's auto-scaffold: discovery empty + binary in hand -> the exploit file lands in the repo, the next attempt uses it |
+| an unknown crash becomes a pack | `lictor draft`: the observed facts + the measured constants -> an armor-validated pack in the staging dir |
+| corpus: 33/33 technique classifications | `augure-benchmark`, CI-enforced at 100% |
+| the eight-target lab, seven deterministic end-to-end | the lab: ret2func/ret2plt/shellcode/fmtstr/orw land the flag via `run` (orw reads its own flag, not the shared one); ret2plt's chain rides the read channel - the copy is bounded by the read length so NUL-bearing addresses cross, rdi aims the service's own command string, 30/30 connections - and the oracle is the target's own flag; the ROP Emporium pair (callme, ret2csu) joins through packs: callme's pop_rsi_r15 pattern and the csu popper aimed at the epilogue (not the symbol entry), an import emits no win_symbol; uaf_heap decides and hands off loyally |
+| the hardening matrix predicts its own death | `lab/purple.sh`: the hardened mirrors (canary+PIE+RELRO+FORTIFY) + `augure coverage` flips - the decision's applicable set shrinks as documented |
+| MEASURED against a typed-decision classifier (Laya, open weights, the fact text as state, the 16 heads as choices): augure **5/5** at 8.5 ms (warm, MCTS included); the classifier 1/5, confident-and-wrong (0.93-0.98 confidence on its errors) - the global-prior bias, reproduced by a 2026 model | `pappers/laya-bench.py`, measured on CPU (i7 8-core, torch) |
+
+A run that fails says failed: `--flag-regex` makes the flag in the
+output the success oracle (the exit code lies both ways), and the
+manual executor hands off instead of pretending.
+
+## Acceptable use
+
+Lictor exists for **authorized security work** (you are responsible for the legality where you stand): engagements with a
+signed scope, labs you own, CTF environments. The authorization model
+is load-bearing; bypassing it is the one contribution that will be
+rejected on sight. Lictor writes no exploit code - it orchestrates the
+operator's chosen tooling; the knowledge lives in the repos, not here.
+
+## Install
+
+Lictor is distributed as a source checkout for a reason: an orchestrator
+around pentest tooling has no business being one `gem install` away
+from anyone. Bundle it from this repo:
+
+```ruby
+# Gemfile
+gem "augure", path: "../augure"    # resolved by path - NOT on rubygems yet
+# lictor + lictor-mcp: bundle from your own checkout, private
+# (augure's tag release can publish it; until then the sibling
+#  checkout is the source of truth - the Gemfile in this repo says so)
+```
+
+## Documentation
+
+The architectural decisions are recorded as ADRs in
+[docs/adr/](docs/adr/): the Tube as the transport seam (0001), verify as
+the arithmetic check with SMT a seam not a promise (0002), engagement
+state as a directory per target, no database (0003).
+
+| I want to... | Read |
+|---|---|
+| run the demo end to end | [the lab](lab/README.md) |
+| understand the operator model | [the operator section](#the-operator-is-the-authorization) |
+| see what augure decides and why | [augure's README](https://github.com/log0u7/augure) |
+| write the auditability story | [augure's auditability page](https://github.com/log0u7/augure/blob/main/docs/auditability.md) |
+| teach augure a technique | [the pack format](https://github.com/log0u7/augure/blob/main/docs/pack-format.md) |
+
+## License
+
+MIT, same as augure.