Repository navigation
fix(rescue): a stuck beacon the server could name was filed as nameless - #8
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_idis assigned in exactly one place —beacon.py:_register_https— and no other transport sendsaction=register. The DNS, SMB and QUIC paths set_registeredand 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
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, thenfingerprint(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_beaconresolves an implant id for a check-in that arrives without one, and_handle_registerdoes 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_rescuesetlast_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:The interface read
httpfor 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_rescuesis 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:
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 fromtools/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.