Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/superpowers/specs/2026-11-12-dns-rescue-channel-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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 |
Expand Down
109 changes: 109 additions & 0 deletions docs/superpowers/specs/2026-11-17-dns-rescue-attribution-amendment.md
Original file line number Diff line number Diff line change
@@ -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.
45 changes: 42 additions & 3 deletions software/c2/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
125 changes: 125 additions & 0 deletions software/tests/test_dns_rescue.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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.

Expand Down