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.