From 5aef3c76a65ec376a8aed761ca9d45500786215d Mon Sep 17 00:00:00 2001 From: Benji Trapp Date: Tue, 17 Nov 2026 11:53:51 +0100 Subject: [PATCH] fix(rescue): a stuck beacon the server could name was filed as nameless MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A rescue record carrying the implant id was dropped into the unattributable list while the server held that very id in `agents[name]["id"]`. `_agent_id` is assigned in exactly one place, the HTTPS registration reply, and no other transport sends `action=register`: the DNS, SMB and QUIC paths set `_registered` and never the name. So a process whose HTTPS leg is dead for its whole life stamps `fingerprint(implant_id)`, and `_handle_rescue` compared the record against fleet names only. That is not the case the design reasoned about. §5 covered "an implant that never reached anything", which has no agent row and is rightly unattributable. But an implant id is one per host and stable across restarts -- a known limit in its own right -- so the row from an earlier process is still in the fleet holding that id. A host seen last week, HTTPS now down, beacon restarted: the server knew exactly who it was and said nobody could claim it. That is the shape this channel exists for. The fingerprint is now matched in two passes: fleet names across the whole fleet first, then implant ids. The name is the stronger signal -- a beacon can only stamp one if this server handed it that name -- and two bytes collide once in 65536, which offering a second candidate per agent doubles, so when both match the name wins. An empty id matches nobody: `fingerprint("")` is a fixed value and a row carrying no id would otherwise claim every rescue from a beacon that had not yet learned who it was. None of this is a new mechanism. `_handle_beacon` resolves an implant id for a check-in that arrives without one, and `_handle_register` does it to recognise a returning host. This path was the one that did not. A second defect, found by the test written for the first: the handler set `last_channel = "dns"` and then called `_handle_beacon`, which sets it to "http" on every call, by design -- it cannot tell the HTTPS, SMB and QUIC relays apart on the agent socket. The mark was therefore destroyed one line after it was written, on BOTH match paths, since the channel shipped. Measured before the fix: fleet name -> last_channel='http' stuck=True implant id -> last_channel='http' stuck=True So the interface read "http" for a beacon whose only working leg was DNS. The bookkeeping now runs first and the mark is written after it. Verified against a running server, not only in-process: an agent registered as raccoon-bandit with implant id 3948e54c95459fd4, a rescue stamped fingerprint(implant)=0c00 where the fleet name would have been 6fbc, and the diagnosis arrived on that agent's row with last_channel='dns'. Eight tests, seven of them new and three of those red first. The design doc gets an amendment and a marker at §5, following the precedent of 2026-11-02-ev-calibration-amendment.md. --- .../2026-11-12-dns-rescue-channel-design.md | 12 +- ...-11-17-dns-rescue-attribution-amendment.md | 109 +++++++++++++++ software/c2/server.py | 45 ++++++- software/tests/test_dns_rescue.py | 125 ++++++++++++++++++ 4 files changed, 287 insertions(+), 4 deletions(-) create mode 100644 docs/superpowers/specs/2026-11-17-dns-rescue-attribution-amendment.md diff --git a/docs/superpowers/specs/2026-11-12-dns-rescue-channel-design.md b/docs/superpowers/specs/2026-11-12-dns-rescue-channel-design.md index e9091d6..a93bf50 100644 --- a/docs/superpowers/specs/2026-11-12-dns-rescue-channel-design.md +++ b/docs/superpowers/specs/2026-11-12-dns-rescue-channel-design.md @@ -287,6 +287,16 @@ sent and still shown — as an unattributed rescue, which is a real and useful thing to see — because a drop-box that never managed to register is precisely the case with the least other evidence. +> **Corrected by `2026-11-17-dns-rescue-attribution-amendment.md`.** A process +> that never registered is not the only one without an `_agent_id`: it is set +> only in the HTTPS registration reply, and nothing else registers, so a +> beacon whose HTTPS leg is dead never learns its name. An implant id is one +> per host and stable across restarts, so the agent row from an earlier +> process is still in the fleet holding that id. The server now matches the +> fingerprint against fleet names first and implant ids second, which is what +> `_handle_beacon` and `_handle_register` already do. An implant with no agent +> row anywhere is still unattributable, still kept, still shown. + ### 6. The listener On a name whose marker label is `r`: take the two payload labels, @@ -332,7 +342,7 @@ implant. | The accumulator is cleared each cycle: a failure from an earlier cycle never appears in a later rescue | same | | A DNS leg that answered with no tasking still counts as "the resolver answered", so the rescue fires; a DNS leg that failed to resolve does not | same | | DNS delivering tasking suppresses the rescue entirely, and leaves SMB and QUIC untried, as the loop already does | same | -| A rescue from an implant with no agent id is sent and shown unattributed | same | +| A rescue from an implant with no agent id **anywhere in the fleet** is sent and shown unattributed; one whose implant id is on an agent row reaches that row — see `2026-11-17-dns-rescue-attribution-amendment.md` | same | | A rescue query whose payload does not decrypt is answered exactly like any other, so the listener is no oracle | `test_listeners.py` | | The listener holds no key on the rescue path | the two existing relay tests, unchanged | | One rescue per exhaustion event, and none after an upstream leg recovers | the new file | diff --git a/docs/superpowers/specs/2026-11-17-dns-rescue-attribution-amendment.md b/docs/superpowers/specs/2026-11-17-dns-rescue-attribution-amendment.md new file mode 100644 index 0000000..7d64120 --- /dev/null +++ b/docs/superpowers/specs/2026-11-17-dns-rescue-attribution-amendment.md @@ -0,0 +1,109 @@ +# Amendment: attributing a rescue from a beacon that never learned its name + +**Date:** 2026-11-17 +**Amends:** `2026-11-12-dns-rescue-channel-design.md`, §5 "Before registration" +and the acceptance table +**Status:** implemented +**Occasion:** Measured in a running server. A rescue record carrying the +*implant* id was filed as unattributable while the server held that very id in +`agents[name]["id"]`. The operator was shown "a stuck beacon nobody can claim" +about a host the server could name. + +The implementation was faithful to the design. The design's reasoning covered +one case and the code covered only that case. + +--- + +## 1 What the design said + +> **Before registration.** The beacon uses `self._agent_id or +> self._implant_id`. An implant that never reached anything has no agent id, so +> the rescue carries the implant id and the server cannot attach it to an agent +> row. It is still sent and still shown — as an unattributed rescue, which is a +> real and useful thing to see — because a drop-box that never managed to +> register is precisely the case with the least other evidence. + +Everything in that paragraph is true of the case it describes: an implant that +has **never** registered has no agent row, so there is nothing to attach it to, +and keeping the record is the right call. + +## 2 What it missed + +A process that never registered is not the only process without an +`_agent_id`. Measured in the code: + +- `_agent_id` is assigned in exactly one place, `beacon.py:_register_https`. +- No other transport sends `action=register`. The DNS, SMB and QUIC paths set + `_registered`, never the name. +- An implant id is **one per host and stable across restarts** — a known limit + recorded in `AGENT.md` in its own right. + +So take a host that registered last week and whose HTTPS leg is now dead. The +beacon restarts. The agent row from the earlier process is still in the fleet, +holding that host's implant id in `info["id"]`. The new process cannot learn +its fleet name — nothing but HTTPS hands it out — so it stamps the implant id, +and the server compared the record against fleet names only. + +That is not an edge case. **It is the shape this channel was built for:** HTTPS +down, DNS the only leg that answers. + +## 3 The correction + +`_handle_rescue` matches in two passes over the fleet: + +1. `fingerprint(agent_id)` — the fleet name, across every agent. +2. `fingerprint(info["id"])` — the implant id, across every agent, skipping any + record whose id is empty. + +A fleet name is tried first and across the whole fleet before any implant id is +considered, because it is the stronger signal: a beacon can only stamp a fleet +name if this server handed it that name in a registration reply. Two bytes of +fingerprint collide once in 65536, and offering a second candidate per agent +doubles that, so when both kinds match the name wins. + +An empty id identifies nobody. `fingerprint("")` is a fixed value, so a record +carrying no id would otherwise claim every rescue from a beacon that had not +yet learned who it was — and the first such record in the dict would take all +of them. + +This is not a new mechanism in this server. `_handle_beacon` resolves an +implant id to a fleet name for a check-in that arrives without one, and +`_handle_register` does it to recognise a returning host. The rescue path was +the one that did not. + +**§5 still holds for the case it describes.** An implant with no agent row +anywhere is still unattributable, still kept, still shown — and the acceptance +row "a rescue from an implant with no agent id is sent and shown unattributed" +now means what it says: *no agent id anywhere in the fleet*, not *no agent id +in this process*. + +## 4 A second defect, found by the test for the first + +`_handle_rescue` set `info["last_channel"] = "dns"` and then called +`_handle_beacon`, which sets `last_channel = "http"` on every call — by +design, because it cannot tell the HTTPS, SMB and QUIC relays apart on the +agent socket. The rescue path's own mark was therefore overwritten one line +after it was written, on **both** match paths, and had been since the channel +shipped. + +Measured before the fix, with an agent whose rescue matched by fleet name: + +``` +fleet name -> last_channel='http' stuck=True +implant id -> last_channel='http' stuck=True +``` + +So the interface showed `http` for a beacon whose only working leg was DNS. +The bookkeeping now runs first and the mark is written after it. + +This was not in the brief. It surfaced because a test asserted the state the +handler claimed to produce rather than only the state it was asked about. + +## 5 What is not changed + +- The beacon is untouched. It could be taught to learn its name from a + transport other than HTTPS, but nothing other than HTTPS registers, so there + is no name to learn; that would be a different change to a different layer. +- The record format, the label arithmetic, the latch and the listener are + untouched. +- The unattributable list keeps its purpose and its cap. diff --git a/software/c2/server.py b/software/c2/server.py index 01fcc1a..4bcd0c2 100644 --- a/software/c2/server.py +++ b/software/c2/server.py @@ -2942,11 +2942,50 @@ def _handle_rescue(payload: dict, crypto: ServerCrypto): klass, code = record[leg] stuck[leg] = [names.get(klass, "unknown"), code] + def _claim(agent_id, info): + info["stuck"] = stuck + answer = _handle_beacon({"agent_id": agent_id}, crypto) + # After the check-in bookkeeping, not before. `_handle_beacon` sets + # `last_channel = "http"` on every call, by design: it means "the + # last contact came in over the agent socket", which it cannot tell + # apart from the SMB and QUIC relays. A rescue is relayed over that + # same socket, so it would be marked "http" -- and this handler's + # own `last_channel = "dns"`, written one line earlier, was wiped + # out before anyone could read it. The interface then showed "http" + # for a beacon whose only working leg was DNS, which is the exact + # situation this channel exists for. + info["last_channel"] = "dns" + return answer + + # Two passes, and the order is the whole design. A fleet name is the + # stronger signal -- a beacon can only stamp one if this server told it + # that name in a registration reply -- so it is tried across the whole + # fleet before any implant id is considered. Two bytes of fingerprint + # collide once in 65536, and offering a second candidate per agent + # doubles that; when both kinds match, the name wins. for agent_id, info in agents.items(): if dns_rescue.fingerprint(agent_id) == record["fingerprint"]: - info["stuck"] = stuck - info["last_channel"] = "dns" - return _handle_beacon({"agent_id": agent_id}, crypto) + return _claim(agent_id, info) + + # The implant id, because a beacon often cannot know its fleet name. + # `_agent_id` is set in exactly one place -- the HTTPS registration + # reply -- and no other transport sends `action=register`, so a process + # whose HTTPS leg was down throughout its life stamps its implant id + # instead. That id is stable per host, so the agent record from an + # earlier process is still here holding it in `info["id"]`, and the + # operator was being told nobody could claim a host the server could + # name. `_handle_beacon` and `_handle_register` both already resolve an + # implant id this way; this path was the one that did not. + # + # An empty id identifies nobody: `fingerprint("")` is a fixed value, so + # a record carrying no id would otherwise claim every rescue sent by a + # beacon that had not yet learned who it was. + for agent_id, info in agents.items(): + implant_id = info.get("id") or "" + if (implant_id + and dns_rescue.fingerprint(implant_id) + == record["fingerprint"]): + return _claim(agent_id, info) unattributed_rescues.append(stuck) del unattributed_rescues[:-_RESCUE_UNATTRIBUTED_MAX] diff --git a/software/tests/test_dns_rescue.py b/software/tests/test_dns_rescue.py index ba428ff..9279651 100644 --- a/software/tests/test_dns_rescue.py +++ b/software/tests/test_dns_rescue.py @@ -1387,6 +1387,17 @@ def test_a_rescue_reaches_the_matching_agent_record(self): self.assertEqual(stuck["https"], ["auth_required", 407]) self.assertTrue(stuck["dns_answered"]) + def test_the_agent_is_marked_as_last_heard_over_dns(self): + # `_handle_rescue` sets `last_channel = "dns"` and then calls + # `_handle_beacon`, which sets it to "http" on every check-in -- + # so the mark the rescue path deliberately made was destroyed one + # line later, and the interface showed "http" for a beacon whose + # only working leg was DNS. Exactly backwards, and exactly in the + # situation this channel exists for. + self._deliver(self._record()) + self.assertEqual( + self.server_mod.agents[self.agent].get("last_channel"), "dns") + def test_it_reads_as_a_sentence_an_operator_can_act_on(self): self._deliver(self._record()) summary = self.server_mod.agents[self.agent]["stuck"]["summary"] @@ -1502,6 +1513,120 @@ def _strip_js_literals(js): return "".join(out) +class TestARescueFromABeaconThatNeverLearnedItsName(unittest.TestCase): + """The fingerprint may be of the implant id, and the server knows it. + + An implant stamps `fingerprint(self._agent_id or self._implant_id)`, and + `_agent_id` is set in exactly one place: the HTTPS registration reply. + No other transport sends `action=register`, so a beacon whose HTTPS leg + is down for the whole life of its process never learns its fleet name + and stamps its implant id instead. + + That is not a rare shape. An implant id is one per host and stable + across restarts (a known limit in its own right), so the agent record + from an earlier process is still in the fleet, holding that very id in + `info["id"]`. The server compared the record only against fleet names, + dropped the diagnosis into the unattributable list, and showed the + operator "a stuck beacon nobody can claim" about a host it could name. + + Matching an implant id to a fleet name is not new here: `_handle_beacon` + does it for a check-in that arrives without one, and `_handle_register` + does it to recognise a returning host. The rescue path was the one that + did not. + """ + + def setUp(self): + import tempfile + + from software.c2 import server as server_mod + + self.server_mod = server_mod + self.crypto = server_mod.ServerCrypto(_KEY) + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.app = server_mod.create_app(self.crypto, "operator-token", + pathlib_Path(tmp.name)) + server_mod.agents.clear() + del server_mod.unattributed_rescues[:] + self.addCleanup(server_mod.agents.clear) + self.addCleanup(lambda: server_mod.unattributed_rescues.clear()) + self.agent = "clumsy-raccoon" + self.implant = "3948e54c95459fd4" + server_mod.agents[self.agent] = { + "id": self.implant, "hostname": "h", "last_seen": "now", + "caps": [], + } + + def _deliver(self, stamped_with): + raw = dns_rescue.pack( + {"https": (dns_rescue.CLASSES["timed_out"], 0), + "dns": (dns_rescue.CLASSES["answered"], 0)}, + dns_rescue.FLAG_DNS_ANSWERED, + dns_rescue.fingerprint(stamped_with)) + wrapped = self.crypto.wrap( + {dns_rescue.WRAPPER_KEY: base64.b64encode(raw).decode()}) + with self.app.test_request_context("/api/v1/beacon", json=wrapped): + return self.server_mod._handle_rescue( + self.crypto.unwrap(wrapped) or {}, self.crypto) + + def test_a_rescue_stamped_with_the_implant_id_reaches_its_agent(self): + self._deliver(self.implant) + stuck = self.server_mod.agents[self.agent].get("stuck") + self.assertIsNotNone( + stuck, "the server holds this implant id in info['id'] and " + "still could not place the diagnosis") + self.assertEqual(stuck["https"], ["timed_out", 0]) + + def test_it_is_not_also_filed_as_unattributable(self): + # Both would be worse than neither: the operator would see a claim + # that nobody owns this record next to the record on its own row. + self._deliver(self.implant) + self.assertEqual(self.server_mod.unattributed_rescues, []) + + def test_the_agents_last_channel_says_dns(self): + # The same bookkeeping a fleet-name match does. A rescue only ever + # arrives over the DNS relay. + self._deliver(self.implant) + self.assertEqual( + self.server_mod.agents[self.agent].get("last_channel"), "dns") + + def test_a_fleet_name_still_matches(self): + self._deliver(self.agent) + self.assertIsNotNone(self.server_mod.agents[self.agent].get("stuck")) + + def test_an_id_matching_neither_is_still_unattributable(self): + self._deliver("a-host-that-never-registered") + self.assertIsNone(self.server_mod.agents[self.agent].get("stuck")) + self.assertEqual(len(self.server_mod.unattributed_rescues), 1) + + def test_a_record_with_no_implant_id_does_not_swallow_the_fingerprint(self): + # `fingerprint("")` is a fixed value, so an agent record carrying no + # id would match every rescue a beacon sent before it knew who it + # was -- and the first such record in the dict would claim all of + # them. An empty id identifies nobody. + self.server_mod.agents["nameless-raccoon"] = { + "id": "", "hostname": "", "last_seen": "now", "caps": [], + } + self._deliver("") + self.assertIsNone( + self.server_mod.agents["nameless-raccoon"].get("stuck")) + self.assertEqual(len(self.server_mod.unattributed_rescues), 1) + + def test_the_fleet_name_wins_when_two_records_could_claim_it(self): + # Two bytes of fingerprint collide once in 65536, and adding a + # second candidate per agent doubles the chance. When both kinds + # match, the fleet name is the stronger signal: the beacon only + # stamps one if the server told it that name. + other = "tidy-raccoon" + self.server_mod.agents[other] = { + "id": self.agent, "hostname": "h2", "last_seen": "now", + "caps": [], + } + self._deliver(self.agent) + self.assertIsNotNone(self.server_mod.agents[self.agent].get("stuck")) + self.assertIsNone(self.server_mod.agents[other].get("stuck")) + + class TestTheTwoGuisDoNotShareHelpers(unittest.TestCase): """The operator page may not call a helper only the agent page has.