rcekit 2.45.3__tar.gz → 3.0.0__tar.gz

{rcekit-2.45.3 → rcekit-3.0.0}/CHANGELOG.md

@@ -10,6 +10,107 @@ formats, or the template schema.
 
 ### Added
 
+- **A coverage ledger, so a measured result and a reproduced one stop looking
+  alike.** The README's CVE table had four rows and two columns that mattered,
+  and no way to say what stood behind any of them. It gained seven columns and
+  five more rows, and the two on the right are the point: `Bench case` says
+  whether `tests/bench/` reproduces the row under Docker with its negative
+  control, and `Recording` says whether a file in `confirmation-gifs/` shows it.
+
+  Five rows are new, measured against vulhub builds during this work: OpenTSDB
+  2.4.1 (CVE-2023-25826) reaching `confirmed` through `oob` and `needs-review`
+  through `time`; HugeGraph 1.2.0 reaching `confirmed` through both `eval` and
+  `reflected`; and a Spring Boot application on fastjson 1.2.83 reaching
+  `deserialization-sink`. All five landed saying `not yet` under `Bench case`,
+  which was the honest state at the time and the reason that column exists; each
+  has a case now. The 4 rows that predate this work had last been executed as a
+  set at 2.36.0, and none of them regressed. The ledger carries the figures for
+  the whole set, because a running total written here rots on the next change
+  rather than the next release.
+
+  `Advisory` is empty on three of them, deliberately. HugeGraph 1.3.0 answers
+  the arithmetic exactly as 1.2.0 does -- its Gremlin API evaluates Groovy
+  unauthenticated by design -- and fastjson resolving an `Inet4Address` is
+  documented autoType behaviour. Those rows prove a *method* against real
+  software, which is worth recording; calling them CVE reproductions would be
+  the overclaim the table exists to avoid. Both facts were measured rather than
+  assumed: the patched HugeGraph image was pulled and run.
+
+  Three tests hold the ledger to the repository: a row claiming a bench case
+  must have one, a row claiming a recording must have one, and the capability
+  rows must stay distinguishable from the CVE rows. Each was checked by making
+  the false claim and watching it fail. The tier check now reads *every* row
+  rather than only those naming an advisory, and its parser is keyed on column
+  headings rather than position -- the old one was hard-coded to four columns
+  and found nothing at all once the table grew.
+
+- **A bench case for `write`, the last tier-1 method without one.**
+  `tomcat-cve-2017-12615` -- `PUT /rcekit-probe.jsp/` with the content in the
+  body, which is the shape the method's own docstring names. Its control runs
+  `reflected` against the same point and must stay `negative`: the target is
+  exploitable and `write` confirms on it, but a PUT answers 204 with an empty
+  body, so nothing in the vulnerable response is computed. Measured at 959
+  probes, every one answered 204.
+
+  It is the first case here that may not share a target between its halves --
+  both write a file into the web root -- which turned up a harness bug: under
+  `--keep-up` the teardown *between* the halves was skipped too, and compose
+  handed the control the container the vulnerable half had just written to. That
+  teardown is mandatory now wherever the halves would land on the same
+  container, which is decided from what *starts* a target -- its `vulhub_path`
+  and `compose` -- and not from what stops it. A control overriding only
+  `compose_down`, to keep its volumes say, still meets the container the
+  vulnerable half brought up. A control that brings up its own target has
+  nothing to contaminate, so `--keep-up` leaves the vulnerable one running
+  there, which is the environment worth looking at after a failure. The
+  teardown after the last half stays the flag's to skip either way.
+
+  The case is also what caught the two `write` defects fixed in 2.45.6 and
+  2.45.7, neither of which a fixture could have found.
+
+### Fixed
+
+- **The comparison table named seven of the nine registered methods.** `lookup`
+  and `boolean` had no row in "How RCEKit compares", although `lookup` is the
+  Log4Shell row the CVE table directly above it already carries, and `boolean`
+  shipped two releases ago. The table's claim is coverage -- "every class, one
+  run" -- so a method missing from it is that claim understating itself.
+
+  The drift was structural, not an oversight anyone could have caught by
+  reading. `docs/reference.md`, the `--methods` help, the CVE rows and the demo
+  headings are each pinned to `DETECTION_METHODS` by a test. The comparison
+  table was pinned by nothing, so it was the one place a new method could fail
+  to appear without anything going red.
+
+  Two tests now hold it, in both directions: every registered method has a row,
+  and the table names no method the CLI would reject -- because a one-way check
+  rots. A method *removed* from the registry would otherwise leave its row
+  behind, advertising a `--methods` value that no longer exists, while the
+  completeness test went on passing.
+
+  Each row now names its method in backticks, which is what makes the check
+  possible and also answers the question the table used to leave hanging: a
+  reader who wants the row they just read has the flag in front of them. Rows
+  that are not methods name none on purpose -- second-order execution, the
+  query-language bridges and the per-dialect Windows probes are things the
+  methods run *through*, not entries in `--methods`.
+
+  Both checks read the capability table alone, and identify a method label
+  structurally: the last backtick in the leading cell, after an em-dash. The
+  first attempt did neither, and both shortcuts cost it the guarantee it stated.
+  Reading every table in the section meant a deleted capability row kept passing
+  on a mention elsewhere -- the engagement-controls table names `file` and
+  `write` under "Cleanup commands" -- which was confirmed by deleting the `file`
+  row and watching the check stay green. And filtering labels on lowercase
+  letters exempted exactly the spellings a typo or a rename produces:
+  `boolean2`, `second-order`, `reflected_v2` all walked past the phantom check,
+  while `cmd.exe` is the legitimate backtick in that column that the filter had
+  been reaching for. Structure separates them; a character class does not.
+
+  No version bump -- this is documentation and tests only.
+
+### Added
+
 - **A tier correction has to reach the prose, not only the class.** Four tests
   now read the tier from `DETECTION_METHODS[name].tier` and hold the sentences
   an operator actually sees against it.
@@ -189,7 +290,342 @@ formats, or the template schema.
 
   No version bump -- this is documentation and tests only.
 
-## [Unreleased]
+## [3.0.0] — 2026-09-30
+
+### Changed
+
+- **BREAKING: `confirmed` is now `executed`, and three settled measurements
+  stopped reporting as `needs-review`.** Every verdict is now named for what the
+  *target* did, never for how sure RCEKit is.
+
+  Two problems, one vocabulary. `confirmed` was the only verdict that described
+  RCEKit's own confidence while every sibling described the target's behaviour,
+  and next to it a `lookup-sink` -- proven on a callback carrying a token only
+  that probe held -- read as something unconfirmed. And `needs-review` had four
+  users, of which three had measured their answer:
+
+  | Verdict | Was | What it says |
+  |---|---|---|
+  | `executed` | `confirmed` | the target executed the input |
+  | `timing-sink` | `needs-review` | the target honoured a delay RCEKit injected |
+  | `file-write` | `needs-review` | the target stored a file at a path RCEKit chose and serves it back uninterpreted |
+  | `evaluation-sink` | `needs-review` | an evaluator consumed the input and partitioned on it; which evaluator is not shown |
+  | `needs-review` | `needs-review` | unchanged, and now with one user: `deser`'s parser fingerprint, the one signal that really is a candidate |
+
+  `write`'s middle verdict is the clearest case: its evidence line opened with
+  the words "ARBITRARY FILE WRITE confirmed" under a status that said
+  `needs-review`. The tool's own prose contradicted the tool's own status,
+  because the status was naming a confidence the measurement did not have a
+  reason to lack -- the file was on the target and RCEKit had read it back.
+
+  Nothing was promoted. `executed` still rests on exactly the three channels it
+  did before, and none of the five weaker tiers has a path into it. `time` in
+  particular stays out: a delay honoured is not necessarily a *shell* honouring
+  it, since a sandbox that implements `sleep` answers the regression the same
+  way. What changed is the direction of the reporting error -- three proven
+  findings were being under-reported.
+
+- **`overall_detection_verdict` ranks `needs-review` last instead of second.**
+  Its position was argued from "a suspected RCE outranks a proven non-RCE in
+  triage", which held while `time`, `boolean` and `write`'s uninterpreted file
+  all reported there. The one verdict left under it is a suspected
+  *deserialization*, so ranking it above `deserialization-sink` put the guess
+  above the proof of the same thing. The full order is now `executed`,
+  `timing-sink`, `file-write`, `evaluation-sink`, `deserialization-sink`,
+  `lookup-sink`, `needs-review`.
+
+  That order is stated once, in `NON_EXECUTION_SECTIONS`, and both the
+  collapsed verdict and the text report read it from there. They used to state
+  it separately -- one as a tuple, the other as the order of print statements
+  in `main()` -- and they disagreed: `deserialization-sink` and `lookup-sink`
+  were hand-written blocks above the table holding the rest, so a run
+  reporting both `timing-sink` and `deserialization-sink` collapsed to the
+  first and led the report with the second. A statement order is not data and
+  cannot be checked against anything.
+
+  Folding those two in unifies their heading with the others: `NOT proof of
+  RCE` becomes `NOT proof of execution`, which is what the other four already
+  said. Their rows keep the compact form they had -- truncated payload, no
+  `environment` -- because they carry base64 object streams and JNDI URIs.
+
+- The classic `--verify-url` path renamed its `confirmed` verdict too, and its
+  section headings with it. It has no sinks and no `needs-review`, so nothing
+  there was mis-tiered; a tool printing `[verify] CONFIRMED` beside `[detect]
+  EXECUTED` would just be two vocabularies. That path has no machine-readable
+  output, so this is text only.
+
+### Benchmark
+
+**`runner.py --all`: 9/9, in 55m50s**, against the same vulhub builds. Every
+case's expected verdict changed in this release, and a rename applied to a
+stored result proves nothing about what the tool now reports, so all 9 ran:
+
+| Case | Method | Vulnerable half | Negative control |
+|---|---|---|---|
+| `fastjson-1.2.83` | `deser` | `deserialization-sink` | `negative` |
+| `hugegraph-gremlin-eval` | `eval` | `executed` | `negative` |
+| `hugegraph-gremlin-shell` | `reflected` | `executed` | `negative` |
+| `log4shell-cve-2021-44228` | `lookup` | `lookup-sink` | `negative` |
+| `opentsdb-cve-2023-25826` | `oob` | `executed` | `timing-sink` |
+| `struts2-s2-001` | `eval` | `executed` | `negative` |
+| `tomcat-cve-2017-12615` | `write` | `executed` | `negative` |
+| `webmin-cve-2019-15107-file` | `file` | `executed` | `negative` |
+| `webmin-cve-2019-15107` | `reflected` | `executed` | `timing-sink` |
+
+The two `timing-sink` controls carry the weight. On a Webmin 1.910 and an
+OpenTSDB 2.4.1 that are genuinely vulnerable, `time` reaches its own proven
+tier and still does not reach `executed` -- the retier holding against real
+software and not against a fixture.
+
+Two tiers this release introduced are **not** in that table: `file-write` and
+`evaluation-sink`. The Tomcat `write` case reaches `executed`, and `boolean`
+has no case at all. Both are covered by unit tests only.
+
+### Migration
+
+`--detect-json` changes values, not keys. `verdict`, the keys of `counts`, each
+probe's `verdict`, and `observe_status` take the new names per the table above.
+A consumer keyed on `"confirmed"` must read `"executed"`; one keyed on
+`"needs-review"` should decide which of the four it actually meant. No CLI flag,
+no JSON key, no template-schema field and no exit code changed.
+
+No backward-compatible alias is shipped. Two accepted spellings for one field is
+a second source of truth, and the point of this release is that there is one.
+
+### Fixed
+
+- **A method's question was derived from its tier, which does not determine
+  it.** `detection_question` decided whether a method asks *did the target
+  execute my input* by looking up its tier in a set of two names. A tier says
+  how strong an answer a method can reach; `time` asks the execution question
+  and cannot reach the strongest answer to it, while `lookup` reaches a
+  definitive answer to a different question.
+
+  Left alone, renaming `time`'s tier in this release would have moved it out of
+  the execution group and out of the dedup that skips it on a candidate
+  `reflected` has already proven -- so the most expensive method in the tool
+  would have run to put a second name on a finding. `question` is now declared
+  on the class, `EXECUTION_TIERS` is gone, and the partition is unchanged.
+
+  The test covering this recomputed the derivation rule it was checking, so it
+  agreed with the rule whatever the rule became. Three tests replace it: the
+  partition written out, the one case where question and tier disagree, and the
+  `time`-leaves-the-group regression by name.
+
+## [2.45.7] — 2026-09-26
+
+### Fixed
+
+- **The `write` product overflowed a 32-bit int, so the method reported
+  `negative` on more than half of the targets it was built for.** RCEKit
+  computes `a*b` in Python, where integers do not overflow. The interpreter on
+  the other side usually is not Python: JSP and ASPX are 3 of the 5 languages
+  this method writes, and both evaluate the expression as a signed 32-bit int.
+  A product past 2**31-1 therefore came back wrapped, disagreed with the value
+  RCEKit had computed, and the run reported `negative` against a target that is
+  fully exploitable -- the one failure this tool exists not to produce.
+
+  Measured against Tomcat 8.5.19 (CVE-2017-12615), writing the probe by PUT and
+  fetching it back. `97233*38786` was served as `-523688158` where RCEKit
+  expected `3771279138`; `4721*8093` came back as `38207053`, exactly. The
+  operand range drew a pair whose product overflows in **56%** of runs, and the
+  operands are drawn once per run, so there was no second probe to recover: more
+  than half of all runs against a JVM or .NET target lost.
+
+  The operands are now 4 digits apiece, which caps the product at 99,980,001 --
+  the range `eval` has always used against these same targets. Nothing about the
+  oracle changes: the product is still bracketed by two random tags and still
+  differenced against a payload-free control, which is what makes it unforgeable
+  rather than its magnitude.
+
+  The same run confirms now. `RKYBRDH<%=3253*8793%>RKICSMR` came back as
+  `RKYBRDH28603629RKICSMR` from the fetched file, and `write` reached
+  `confirmed` against real software for the first time.
+
+  Two tests, both written first and watched to fail: the drawn operands multiply
+  to something a signed 32-bit int can hold, across 400 seeds; and a store whose
+  evaluator wraps to 32 bits the way a JVM does reaches `confirmed` rather than
+  `negative`. A third test had pinned the operand width with a hard-coded
+  `\d{5}`; it reads the declared range now and asserts the operands fall inside
+  it, which the digit count had only implied.
+
+## [2.45.6] — 2026-09-26
+
+### Fixed
+
+- **The `write` probe carried whitespace, and some sinks tokenise before they
+  write.** The file content this method delivers is a language one-liner, and
+  its templates spelled the expression with spaces around it -- `<?= a*b ?>`,
+  `<%= a*b %>`. The content goes through the operator's own injection point, and
+  a sink that splits its input on whitespace never writes a valid file.
+
+  Measured against RRDtool 1.7.2, reached through Cacti 1.2.28's
+  `right_axis_label` (CVE-2025-24367), which builds the file from a
+  `LINE1:out:<content>` argument. `RKAAA<?=7*6?>RKBBB` wrote a 47-byte file with
+  the content intact. `RKAAA<?= 7*6 ?>RKBBB` wrote no file at all and answered
+  `ERROR: '7*6' is not a valid function name in 7*6`. The whitespace was the
+  whole difference.
+
+  Whitespace inside `<?= ?>` and `<%= %>` is optional, so the templates drop it:
+  nothing is lost and every sink of that shape is gained. Verified end to end
+  against the real sink rather than a fixture -- RCEKit generated
+  `RKYOOQS<?=69294*83370?>RKGFZQP`, RRDtool wrote it whole, and PHP answered
+  `RKYOOQS5777040780RKGFZQP`, which is the value RCEKit had computed for that
+  probe.
+
+  `jspx` keeps its spaces: it is an XML document whose root element carries
+  namespace attributes, and a sink that tokenises on whitespace was never going
+  to carry one. Two tests pin the rest -- the generated probe and the templates
+  themselves -- both written first and watched to fail.
+
+## [2.45.5] — 2026-09-25
+
+### Fixed
+
+- **The `deser` shape differential answered from evidence it had not
+  validated.** Three ways, each found by pointing the method at a live
+  fastjson 1.2.83 endpoint under vulhub and asking why it said what it said.
+
+  **Drift landed on whichever form went last.** The differential is read across
+  requests, so anything changing with the request *index* rather than with the
+  payload -- a rate limiter backing off, a filling log, a warming cache -- fell
+  on the form sent last, and noise was sent last every time. There are two
+  noise probes now, first and last, bracketing the structured pair. They are
+  one noise body sent twice, byte for byte, because the bracket asks whether
+  the endpoint answered *the same probe* alike and anything the target can see
+  a difference in it may answer a difference to: a tail beginning `n` made
+  fastjson say "error parse new" where every other tail said "syntax error".
+  A carrier whose two ends disagree is held at `inconclusive`. The engine
+  de-duplicates by payload on the per-probe path but not on the aggregate path
+  where `deser` lives, which is what makes one body twice possible; a test pins
+  that, because the bracket becomes a single request if it ever changes and a
+  drift check comparing an answer with itself passes forever.
+
+  **An endpoint echoing its input looked like a parser.** A response carrying a
+  fragment of the payload that begins at the format's magic, and not carrying
+  it in the payload-free control, is an echo and the shape channel cannot be
+  read through it -- `inconclusive`, not `negative`, because the channel was
+  unreadable rather than empty. The sentinels are anchored on the magic's
+  position in the payload rather than its start, since a probe is wrapped for
+  its injection context first and some wrappers are longer than the magic: an
+  `xml_cdata` pickle probe begins `<![CDATA[gASV`. They are matched raw, case
+  folded (because `_signature` folds case and the two halves of one oracle must
+  agree), and encoded -- base64 aligned on bytes rather than characters and
+  read from the first three-byte boundary at or past the magic, hex from the
+  magic itself.
+
+  **A format declaring no magic got a verdict anyway.** Without a magic there
+  is no sentinel, so an echoing endpoint cannot be told from a parsing one --
+  and the differential answers regardless, because the noise form is random
+  where a structured pair is not. Every shipped format declares one; a
+  `--template-file` need not, and the answer to a control that cannot be
+  validated is to say so.
+
+- **The page an operator plans traffic from still described three payloads.**
+  The bracket makes the shape oracle send four per ecosystem -- 20 requests per
+  carrier rather than 15, with the five the corpus ships -- and
+  `docs/reference.md` and the method's own docstring both still said three.
+  README advertises an execution plan that prints the exact probe count before
+  anything fires, so a page that undercounts it breaks that promise in the one
+  place someone reads before a monitored engagement.
+
+  Both now state four, and the arithmetic, and what the repeated probe is for.
+  A test holds the page to `SHAPE_FORMS` and to the ecosystem count, in both
+  directions: adding a form without updating the page fails it, and reverting
+  the page without touching the code fails it too. Nothing compared the two
+  before, which is how the count drifted the moment the form was added.
+
+- **The `negative` evidence line described a comparison it had not made.** "The
+  endpoint answers all three forms alike" was asserted rather than observed.
+  It now names what actually collapsed: every form alike, a truncated stream
+  answered as a complete one, or the noise form answered as a structured one.
+
+### Withdrawn before release
+
+- **A second route through the differential, reading noise as the control.** It
+  was written for the shape fastjson has -- a format resolving its type name
+  before the parse finishes answers a truncated stream exactly as it answers a
+  complete one, which collapses the original comparison on the very endpoints
+  it exists to find -- and it did reach `needs-review` there.
+
+  It is not in this release. "Noise differs from the structured pair" has too
+  many explanations that are not a parser. Drift and echo are closed above. The
+  third is not: a filter that refuses the random payload while letting the
+  structured ones through produces the same differential, no repetition exposes
+  it because the refusal is stable, and this verdict cannot see it -- refusal
+  is judged against the probe the verdict is anchored to, and that is the
+  well-formed one.
+
+  A format of that shape is reported `negative` by the shape differential and
+  reaches `deserialization-sink` through the DNS gadget instead, which is this
+  method's real oracle and rests on a callback rather than on the shape of a
+  response. Measured on the same target: 14 callbacks, each carrying a token it
+  could only have learned by resolving the name it was handed.
+
+## [2.45.4] — 2026-09-25
+
+### Fixed
+
+- **A compressed response body is a body the oracles cannot read, so a target
+  that executed the probe was reported `negative`.** Every in-band oracle --
+  `reflected`, `eval`, `file`, `write`, `boolean` -- confirms by finding a
+  value the target computed in the response. Nothing in the delivery layer
+  undid `Content-Encoding`, so a gzipped body arrived as bytes that *contain*
+  the computed value and do not spell it, and the search for a decimal number
+  came back empty. The verdict was `negative`: not "could not read this", but
+  "the probes reached the target and it is not vulnerable".
+
+  Measured against Apache HugeGraph 1.2.0 under vulhub. The probe
+  `echo RKPDSWY$((258675+956113))RKIEMTB$(echo RKLUQKL)RKPDSWY`, delivered
+  through the Gremlin API, came back HTTP 200 carrying
+  `RKPDSWY1214788RKIEMTBRKLUQKLRKPDSWY` -- the sum and the substitution
+  collapse, both of `ReflectedMath`'s proofs. Present after gunzip, absent in
+  the raw bytes, and the run reported `negative` across 620 probes.
+
+  What made it survive this long is that the same target confirmed on the same
+  run's *other* probes: HugeGraph gzips its 200s and leaves its 4xx errors
+  plain, so `eval` confirmed through a 400 that carried a Groovy exception
+  message while the 200 that carried real command execution was invisible. A
+  run that finds something is a run nobody rereads.
+
+  Both HTTP entry points decode now -- the verification/detection path and the
+  `--verify-chain` path -- through one helper, on the success body and the
+  `HTTPError` body alike, since an evaluator surfacing its value in a 500 is
+  the case that path exists for. The header is honoured whether or not RCEKit
+  asked for it, because HugeGraph compresses a response to a request that sent
+  no `Accept-Encoding` at all.
+
+  `gzip` and `deflate` only, both from the standard library, and `deflate`
+  tries the zlib wrapper before the raw stream because servers disagree about
+  which one that name means. `br` and `zstd` need a third-party module and this
+  tool has none to add; a body in either is returned as its raw bytes. Nothing
+  here raises: a body that claims an encoding it is not in comes back
+  undecompressed rather than ending a run that has already spent hundreds of
+  probes.
+
+  This does not widen what `confirmed` means. The oracle is unchanged -- a
+  computed value present in the response and absent from a payload-free
+  control -- and nothing is promoted into it. What changes is that the response
+  the oracle reads is the response the target sent.
+
+- **Decompression is bounded, because compression is where the target chooses
+  how much memory RCEKit allocates.** Reading a body at all is new here, and
+  one-shot decompression handed a blank cheque to the one party in the exchange
+  that is untrusted by definition -- the thing being tested. Measured: 130,478
+  bytes of gzip expand to 134,217,728, and 203,860 bytes hold 200 MB of zeros,
+  a ratio of 1:1028. This path runs once per probe.
+
+  The ceiling is 32 MiB per encoding step. Whatever was produced before it is
+  kept rather than discarded: the value the oracle wants is short, so searching
+  32 MB is a far better answer than searching nothing, and the only risk the
+  ceiling carries is a false negative -- never a false `confirmed`. A truncated
+  read is logged rather than passed off as a clean one, since a `negative`
+  decided on a partial body is not the same claim as a `negative` decided on
+  the whole of it.
+
+  Multi-member streams are still followed. `gzip.decompress` followed them, and
+  a ceiling that quietly became a truncation for a server that concatenates
+  members would be the same false negative in a new place.
 
 ## [2.45.3] — 2026-09-24
 
@@ -2264,6 +2700,11 @@ this file and have not been restated here.
 
 
 [Unreleased]: https://github.com/kabiri-labs/rcekit/compare/v2.36.0...HEAD
+[3.0.0]: https://github.com/kabiri-labs/rcekit/compare/v2.45.7...v3.0.0
+[2.45.7]: https://github.com/kabiri-labs/rcekit/compare/v2.45.6...v2.45.7
+[2.45.6]: https://github.com/kabiri-labs/rcekit/compare/v2.45.5...v2.45.6
+[2.45.5]: https://github.com/kabiri-labs/rcekit/compare/v2.45.4...v2.45.5
+[2.45.4]: https://github.com/kabiri-labs/rcekit/compare/v2.45.3...v2.45.4
 [2.45.3]: https://github.com/kabiri-labs/rcekit/compare/v2.45.2...v2.45.3
 [2.45.2]: https://github.com/kabiri-labs/rcekit/compare/v2.45.1...v2.45.2
 [2.45.1]: https://github.com/kabiri-labs/rcekit/compare/v2.45.0...v2.45.1

{rcekit-2.45.3 → rcekit-3.0.0}/CONTRIBUTING.md

@@ -83,12 +83,16 @@ in the clearly separated **Detection methods** section of `rcekit.py`
 
 To add one:
 
-1. Subclass `DetectionMethod`: set `name` and `tier` (`confirmed` for
-   execution-proven methods, `needs-review` for candidates — the two tiers are
-   never merged), then implement `applicable`, `build_probes`, and `confirm`.
+1. Subclass `DetectionMethod`: set `name` and `tier` (`executed` for
+   execution-proven methods; otherwise a tier named for what the target did,
+   like `timing-sink`, and `needs-review` only when the signal really is a
+   candidate — tiers are never merged), then implement `applicable`,
+   `build_probes`, and `confirm`. Also set `question`, which says whether this
+   asks *did the target execute my input* or something else; it does not follow
+   from the tier.
 2. Compute the expected value **locally** with random inputs and compare it
    against the payload-free control (reuse `self._search`, which is
-   encoding-aware). A verdict is `confirmed` only when the computed value is
+   encoding-aware). A verdict is `executed` only when the computed value is
    present and absent from the control.
 3. **Declare what the method costs and what it says.** `safety` is the
    `--verify-active-risk` rung it needs: `safe` when it only makes the target
@@ -119,10 +123,20 @@ To add one:
    bench case proves it reaches that verdict against the real software. It is
    not a per-PR gate, and a method whose case cannot run yet still ships --
    with the reason written down in `tests/bench/README.md`, not left implicit.
-7. Do not add a row to the README's **CVE table** without a bench run behind it.
-   That table is the reproduced claim, and it carries the version it was last
-   verified at. The **methods table** describes capability, and the unit suite
-   is what backs that.
+7. A row in the README's **coverage ledger** needs a run behind it, and its
+   `Bench case` column has to say which kind. `yes` means `tests/bench/`
+   reproduces it, target and negative control; that is the strong claim and it
+   carries the version it was last verified at. `not yet` means it was measured
+   by hand against the same build and nobody can re-run it on demand — honest,
+   weaker, and the reason the column is there. Never fill the column in ahead of
+   the case: a test reads it against `tests/bench/cases/` and
+   `confirmation-gifs/`.
+
+   Leave the `Advisory` column empty where the verdict does not depend on the
+   patch. A row proving a method against real software is worth recording;
+   labelling it with a CVE it does not reproduce is the overclaim the ledger
+   exists to prevent. The **methods table** describes capability in the
+   abstract, and the unit suite is what backs that.
 
 ## Adding a bench case
 
@@ -152,7 +166,7 @@ New detection coverage should arrive with a case. Every case needs a **negative
 control** — the runner refuses to load one without it — because a benchmark with
 no controls rewards aggressive probing instead of measuring accuracy. The
 control may be a patched build, the same target probed for the wrong class, or a
-weaker method that must stay below `confirmed` on a target where it happens to
+weaker method that must stay below `executed` on a target where it happens to
 be right.
 
 Run your case against the real target before submitting, and update the README