Skip to content

fix(rescue): a stuck beacon the server could name was filed as nameless - #8

Merged
BenjiTrapp merged 1 commit into
mainfrom
fix/dns-only-attribution
Nov 17, 2026
Merged

BenjiTrapp merged 1 commit into
mainfrom
fix/dns-only-attribution

Conversation

@BenjiTrapp

Copy link
Copy Markdown
Owner

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 told "a stuck beacon nobody can claim" about a host the server could name.

Found while showing the feature to its author. Independent of #6 and #7.

Why a beacon stamps its implant id

_agent_id is assigned in exactly one place — beacon.py:_register_https — 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 has no fleet name to stamp.

Why the server knows it anyway

An implant id is one per host and stable across restarts — a known limit in its own right. The agent row from an earlier process is still in the fleet, holding that id.

So: a host seen last week, HTTPS now down, beacon restarted. The server knows exactly who it is. It said nobody could claim it.

That is the shape this channel exists for. Not an edge case.

What the design assumed

Before registration. […] An implant that never reached anything has no agent id […] It is still sent and still shown — as an unattributed rescue […] because a drop-box that never managed to register is precisely the case with the least other evidence.

True of the case it describes. The restart on a known host was not considered. §5 now carries a correction marker and there is an amendment doc, following the precedent of 2026-11-02-ev-calibration-amendment.md.

The fix

Two passes over the fleet: fingerprint(agent_id) across all agents first, then fingerprint(info["id"]). The fleet name is the stronger signal — a beacon can only stamp one if this server handed it that name — and two bytes of fingerprint collide once in 65536, which a second candidate per agent doubles. When both match, the name wins. An empty id matches nobody: fingerprint("") is a fixed value and a row with no id would otherwise claim every rescue from a beacon that had not yet learned who it was.

Not a new mechanism here: _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 for the first

_handle_rescue set last_channel = "dns" and then called _handle_beacon, which sets it to "http" on every call — by design, since it cannot tell the HTTPS, SMB and QUIC relays apart. The mark was destroyed one line after it was written, on both paths, since the channel shipped:

fleet name  -> last_channel='http'  stuck=True
implant id  -> last_channel='http'  stuck=True

The interface read http for a beacon whose only working leg was DNS. Bookkeeping now runs first, the mark after.

On main this moves the record from invisible to visible

Worth knowing: on main, unattributed_rescues is write-only — no route reads it, the GUI does not show it, and no log line is written. The route, the GUI panel and the log entry all arrive with #6. So on main as it stands, a rescue that misses attribution is effectively discarded, and this fix is the difference between a diagnosis nobody can read and one on the agent's row.

Evidence

Against a running server, not only in-process:

registered as raccoon-bandit, implant id 3948e54c95459fd4
stamped with fingerprint('3948e54c95459fd4') = 0c00
the fleet name would be  fingerprint('raccoon-bandit') = 6fbc

on the agent row:  stuck = HTTPS: timed out; DNS: answered; SMB: not tried; QUIC: not tried
                   last_channel = 'dns'

Eight tests, seven new, three of those red first. 3446 tests green.

A correction to something I said earlier

I first reported that every DNS-only beacon is permanently unattributable, based on an agent whose id ended in -dns. That suffix does not exist in production code — it comes from tools/demo_env.py, which appends the transport and registers out of band precisely because nothing registers over DNS. I measured a harness construct and generalised from it. The real case is narrower than that claim and broader than the design's: it is any host the fleet already knows whose beacon restarted without HTTPS.

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.
@BenjiTrapp
BenjiTrapp merged commit b1ba5ea into main Nov 17, 2026
@BenjiTrapp
BenjiTrapp deleted the fix/dns-only-attribution branch November 17, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant