Status: accepted for version 0.1 on 2026-11-11.
This file says what pullgate protects, from whom, and where it stops. Read DESIGN.md first for the words and the flows.
A host that pulls its own config from a git repo changes whenever someone pushes to that repo. Whoever can push (a person, a CI job, a stolen key) can change the host, often as root. pullgate puts a person between the push and the change: the host applies one exact commit only after its owner taps Apply on a question that names that commit, and the rules of that gate live on the host, out of reach of the repo.
| asset | where it lives |
|---|---|
| the host itself (root) | the host |
| the gate: the instance config, the listener config, the units, the binary | /etc/pullgate, /etc/systemd/system, the binary path |
| the state: applied SHA, open questions, failed marks | /var/lib/pullgate/NAME/state.json |
| the deploy key (read-only) | /etc/pullgate |
| the bot token | the listener's token file or systemd credential |
| the approval decision | Telegram, the listener, the state |
| actor | trust |
|---|---|
| the owner (the person who taps) | Trusted. Their judgment is the check. |
| the owner's Telegram account and phone | Trusted. Anyone who can use this account can approve. |
| Telegram's servers | Trusted to deliver messages and to say truthfully who tapped. They see the question text: SHAs, commit subjects, file names and the summary output. |
| root on the host | Fully trusted. |
| the listener process and its user | Trusted only to pass on the owner's taps and /check messages. If it is taken over, it can approve an open question without the owner (T2), and start runs (at most one a minute, T18). It can never choose the SHA. |
check_user and the check/summary commands |
Not trusted with root. They read hostile data (T3). |
| the git server and everyone who can push | Not trusted. A commit may be hostile. |
| the network | Not trusted. SSH with a pinned host key protects the fetch. |
| other local users | Not trusted. |
the apply and health commands |
Trusted: the owner wrote them. They run as root on the approved tree. |
GitHub, the release workflow on main, and the gh that install.sh pins |
Trusted to build and serve the release that install.sh installs (T16, T17). |
- No change without a tap. In
askmode, root runsapplyonly for a SHA whose question the owner approved (or that a taken-over listener approved, T2). - The SHA is root's own. The applied SHA is the one root put in the question. Nothing outside root's state can choose it.
- No code from a new commit runs before the tap, and never as root.
- Forward only, unless the host config says otherwise.
- The gate is not in the repo. No commit can change who approves, what runs, or what is watched, except by an approved apply that installs it (T5).
Each threat says what an attacker can try, what stops it, and what is left.
Attack. Someone gets the bot token. They can call the Bot API as the bot: read updates, send messages, edit them.
Defense. A token cannot make a tap from the owner's user ID; Telegram signs
nothing, but it reports the real sender of a callback_query, and the
listener checks from.id and chat.id. A thief who runs their own
getUpdates steals the updates from the listener (two pollers conflict),
so taps can get lost: lost taps deny, they do not approve. The thief can
send a fake question to the owner, with buttons whose codes the listener
does not hold; a tap on it does nothing, because the listener holds the
only list of codes, and root checks the code against its own state. The
thief can also read new taps of the owner (the code of an open question)
but a code alone is useless without write access to the inbox.
The thief can also edit the text of a real question, so that harmless text
sits above real buttons for a hostile SHA. The listener counts a tap only on
a message that was never edited, whose text is the text Telegram gave back
when the listener sent it (DESIGN.md section 9).
/check. A token cannot send a message as the owner either. A message
that the thief sends to the bot, or in another chat, comes with the
thief's own from.id (or the wrong chat.id); the listener ignores it,
gives no answer and logs no text (DESIGN.md section 9). The thief can read
the owner's /check messages, but that tells only that the owner wants a
check. Even a request that the thief could forge would only start a normal
run: it fetches and asks; in ask mode it never applies.
Left. The thief can show the owner false text (a fake "applied" message), can hide questions, and can see the question text. Keep the token in a file only the listener user can read, or a systemd credential. Change it with BotFather when in doubt.
Attack. An attacker runs code as the listener user.
Defense. The listener user can write only to the inboxes and the outboxes.
An approval holds a code; root looks the code up in its own state, so the
listener cannot name a SHA, cannot approve a commit that root did not ask
about, cannot pass the time limit, and cannot replay a used code. Root reads
inbox files with O_NOFOLLOW, caps their size, needs the listener as owner,
and rejects unknown fields. The forward-only rule still holds. The listener
user can write in the outbox and the inbox. Root never follows a path there:
the spool directories above them are root-owned, root opens them with
os.OpenRoot, and creates files with O_CREAT|O_EXCL|O_NOFOLLOW under a
random name. So a symlink that the listener plants cannot make root write
or change a file elsewhere. Root gives an outbox file the listener's group
with fchown on the open file, never through a path, and no spool
directory has the setgid bit. So the run unit keeps RestrictSUIDSGID=yes
(DESIGN.md section 4).
Check requests. The listener can also write check requests at any time,
without the owner. A request holds no data: root checks it like an
approval (O_NOFOLLOW, regular file, owned by the listener, at most 64
bytes) and also needs the fixed name and content. It cannot name a SHA,
an instance other than its own directory, or an action. It can only start
the normal run sooner, with the same sandbox, lock and rules. Root keeps
the limit (one run per minute from requests) in its own state, so the
listener cannot make root fetch more often by writing files; a bad file
is not a request (T18).
Left. It can approve any open question (or a superseded one that has not
expired) without the owner, and it can hide or fake messages. So the
attacker still needs a hostile commit in the repo and the listener.
With check requests it can make root fetch and ask once a minute, and make
an auto instance apply a new commit sooner than the timer would; never a
commit that the timer would not apply.
Run the listener as its own user, with the hardened unit.
Attack. Someone who can push writes a commit made to hurt the host before or during the review.
- Its content. Before the tap, no file of the commit runs. git only
reads objects.
checkandsummaryread files as data, ascheck_user(not root), in a read-only tree, inside the run unit's sandbox. A parser bug in them hits onlycheck_user. They have a timeout and an output cap. A process ofcheck_userthat leaves its process group to fake a later check or summary is stopped withkill -KILL -1ascheck_userafter each command, and by systemd when the run unit ends. Use onecheck_userper instance. - A tree that changed. Trees are written to a temporary name and renamed
only when complete. Each process exports its own fresh trees and removes
them at the end;
applynever runs on a tree that a check, an earlier apply, or a crash left behind. - File names. Each path part is checked: no
.., no.git, no empty part, no NUL. Names with control or invisible characters, or with HTML, are cleaned and escaped before they are shown, so a name cannot fake a line of the question. - Commit subjects and summary output. The same cleaning; HTML-escaped,
each line capped. The output of a failed
checkkeeps its end, so the reason is not cut away; root's tree paths in it becomeNEWandOLD. The head of the question (host, instance, SHA, the warnings) always comes first, before any text from the commit. WARN:lines of the summary in the head.summaryruns ascheck_useron the commit's tree, so a hostile commit may make it printWARN:lines. They are shown only as cleaned code after⚠, at most 10 and a count, after the watched-path warnings. They never push out the fixed head lines (host, instance, SHA, the broken and held lines). Each is at most 220 characters after the escape, so all 10 take at most about 2250 of the 3400 that the head may use: the watched-path warnings, root's own, always keep room. Path warnings that still do not fit are counted ("⚠ … and N more warnings"), as before. Left: a hostile summary can print decoyWARN:lines first and push the owner's real ones into the "N more warnings from the summary" count; the owner'ssummaryshould print its own warnings first. They change nothing that root checks: the tap is bound to the code and the SHA in root's state.- The report file of
apply.applyruns as root and is the owner's own command, but it may copy text from the tree. Root makes the file itself, in its own trees directory, and reads it only when it is still that same file (same device and inode, a regular file, opened withO_NOFOLLOW), at most 64 KiB. Soapplycannot make root show another file by a symlink or a hard link. Its lines are cleaned and shown as code, at most 10 lines and 1500 characters. A rollback andhealthget no report file. - Hostile text shown as a link in a trusted message. A commit picks its
own file names, subjects and command output. Telegram turns text that
looks like a domain or a URL (
README.md,login.example.com), an@username, a#tagor a/commandinto something to tap, in a message from the owner's own bot, next to the Apply button. So all text from the repo is shown only inside<code>or<pre>, where Telegram makes none of these, and only through one function (DESIGN.md section 12). Link previews are off for every message, so a link that slips through still shows no preview. A test feeds hostile values into every field of every message kind. - A short SHA that looks right. Messages show 12 characters of a SHA
(48 bits). Someone could grind a commit whose short SHA matches one the
owner expects. This does not change what is applied: root applies the
full SHA from its own state, and the tap is bound to the question code,
not to the text. The question also shows the full SHA once, on its last
line, and
pullgate statusshows the full applied SHA. - Symlinks. They are written as symlinks and never followed by
pullgate. The tree is written with
O_NOFOLLOW|O_EXCLinto directories that pullgate made itself, so a symlink cannot make pullgate write outside the tree. A repeated name, or a path below a file or symlink, stops the export; git checks the objects on fetch (transfer.fsckObjects). A symlink whose target is absolute or holds..gets a warning in the head of the question, so the owner sees it before root'sapplymay follow it;refuse_symlinks = truerefuses such a commit. A command that reads the tree must not follow symlinks blindly (the docs say so). - Large trees.
max_filesandmax_tree_bytesstop the export. The question has a fixed size. git output is capped. .gitattributesfilters. pullgate never checks out and never runsgit archive; it writes blobs itself, so nofilter,textconv,export-substorexport-ignoreruns. git runs without system and global config, so no filter is defined anyway.- Submodules. Not fetched, not written (
--no-recurse-submodules, mode 160000 is skipped), listed as a warning. - LFS. Not used. An LFS pointer file is written as the small text file it is.
- A hostile commit that the owner approves. The apply then runs as root on purpose. pullgate cannot stop a bad change that the owner approves; it makes sure the owner sees the full SHA, the subjects, the changed files, and a warning for each watched path.
Attack. If another user can write the git directory, they can set
core.fsmonitor, hooks, or core.sshCommand in config, and git runs
it as root.
Defense. Rule 6: root owns the clone in a root-only directory, checks the
git directory, all its contents and all parents before every git command,
and refuses on any problem. git runs with core.hooksPath=/dev/null,
core.fsmonitor=false, no system or global config, and an empty
environment.
Attack. The repo holds the instance config, a unit, or the binary, and
apply installs them. A commit that weakens the gate (mode = "auto", a
new owner ID, no watch list) is approved by mistake.
Defense. pullgate cannot know what apply installs. It reads its config
once per process, so the running apply and its rollback use the gate of
the process that started them. The owner should keep the gate files out of
the repo, or list them in watch, so the question shows "⚠ Watched path
changed" for them. The listener's owner ID and chat ID are in a separate
file that apply should not touch.
A rollback after such an apply. If the new gate fails health, the
rollback runs the old apply on the old tree, with the commands of the
current process (the old gate). So a rollback puts the old gate files back
when apply installs them. If the new gate did break pullgate itself (for
example a bad binary that apply installed), the next run fails to start
and the owner sees the failed unit; the gate does not repair what apply
installed. Let apply not install pullgate: /update does that, with
every check of install.sh and a way back (T20).
Left. An approved commit can change everything. This is the price of having the host manage itself.
Attack or accident. apply fails, and running it again on the old tree
fails too. The host may be half changed.
Defense. With on_failure = "rollback", a failed rollback makes the
instance broken (DESIGN.md section 10) and reports it once, with the
reason. Nothing is applied until the owner taps Apply on a fix
forward: a newer commit on top of the failed one, asked with a strong
warning. The failed commit and the old commit are never asked again, and
no rollback is tried against the half state. In auto mode the owner is
asked too. Only a fix forward that passes health, or root with
pullgate status NAME --resume, ends it. It never ends by itself, and no
message from Telegram ends it, so a stolen bot token or a compromised
listener (T2) cannot lift it: the most they can do is not deliver a tap.
A pause file still stops everything, also while broken. With on_failure = "pause" there is no
rollback: the failed SHA is held, and the owner can fix it forward. The
applied SHA does not change after a failure.
Attack. The branch is moved to a commit that does not descend from the applied SHA, maybe to undo a fix or to hide history.
Defense. Forward only: the run refuses the tip, sends one notice, and marks
the SHA refused. Root checks it again at apply time. Only
allow_older = true in the host config allows it, and then the question
has a warning line.
Attack. The branch is set back to an older commit that was skipped, failed, or was applied earlier (a downgrade).
Defense. An ancestor of the applied SHA is refused (T7). A SHA that was
skipped, failed its check, failed its apply, or whose question expired, is
not asked again unless --ask-again is used. The state keeps these marks.
Attack or accident. A tap is lost; or a tap arrives late; or a tap is replayed; or an old message is tapped.
Defense. A lost tap means no apply (fail closed); the question expires and
the SHA waits for a new commit or --ask-again. The listener forgets a code
after the first tap and after the question is closed, so a second tap, or a
tap on a closed or expired question, writes nothing. The listener also
keeps the last 200 update IDs it handled and ignores an update with one of
them, a tap or a /check alike. Root removes a question
from its state before it acts, so a replayed approval finds no question.
Root checks the time limit itself. --ask-again removes an open question
for the tip from root's state (its message may be lost), so a tap on it,
even one already written, finds no question; the new question has a new
code. A question lost in the outbox is not silent: the listener tells the
owner when it removes an outbox file that it cannot read, and names the
instance, but shows no part of the file. A tap on a superseded question that the
listener took before it handled the close still applies the old SHA
(rule 2); the forward-only check still holds then.
Accident. Power is lost while apply runs, or just after it, before the
state is written.
Defense. Root syncs in_progress to disk before it starts apply. On the
next start, in_progress means "unknown result": pullgate writes the pause
file, marks the SHA failed, and reports. It does not guess. The state is
written to a temporary file, synced, and renamed, so it is never half
written.
The update of pullgate itself (T20) has the same rule. Root syncs
in_progress before it touches the binary. The old binary gets a second
name (.pullgate.prev, a hard link in the same directory). install.sh
writes the new file under a temporary name, syncs it, and renames it over
pullgate; a rollback renames .pullgate.prev back. A rename in one
directory replaces the name in one step, so after a crash or a power loss
the host has the old binary or the new one, never none and never a part of
one. The next start of pullgate update sees in_progress, reports "the
update was cut off" with what pullgate version says, and does not guess.
A test stops the update at each step and checks this
(TestCrashInTheSwap).
Accident or attack. The host clock jumps forward or back.
Defense. Time limits are checked by root with its own clock against times
it recorded itself: an approval counts only when asked <= now < expires.
A clock that goes back before asked denies. A clock that jumps forward
expires questions early: this denies too. The listener checks expiry with its
own clock as well. Timeouts of commands use the monotonic clock.
settle counts from the time root first saw the tip; a clock that goes
back before that time starts the wait again. A clock that is wrong and then
corrected forward can make the wait shorter, like approval_ttl above.
That only asks sooner; it never applies anything.
Left. A clock that is set far back while a question is open can keep that
question valid longer than approval_ttl. The code still works only once.
Attack. A local user, or the listener, puts files in the inbox.
Defense. Only the listener user can write the inbox. Root needs the listener as the file owner, a regular file, at most 1 KiB, valid JSON without unknown fields, and a code that matches its state. A bad file is removed and logged. The path unit then has nothing left and stops.
The check directory. A check request has no code, so a code cannot
protect it. It needs none, because it cannot cause an apply: it only
starts the normal run, which asks (or, in auto mode, does what the timer
does). Only the listener user can write the directory. Root needs the
listener as owner, a regular file through O_NOFOLLOW, at most 64 bytes,
the name request and the content check\n. Root removes every file in
the directory before it acts, and a bad file is not a request.
pullgate apply never reads this directory, and a check request put in
the inbox is a bad approval. A run that finds only bad files removes them
and goes on as a normal run, without a reply. The limit of T18 holds for
every valid request; the trigger limit of the path unit holds for every
file.
Attack. A fake server, or a server that sends huge or broken data.
Defense. SSH with StrictHostKeyChecking=yes and a pinned known hosts file
from the host config; a read-only deploy key; no other protocols. git has
a timeout and an output cap. The tree export has caps.
Downloads of releases (T17, T20). For /update, root also downloads
from GitHub, with the built-in install.sh: HTTPS only, also after a
redirect (--proto '=https' --proto-redir '=https'), TLS 1.2 or newer, a
size limit for each file (1 MiB, 64 MiB for a tarball), a time limit for
each download and 20 minutes for the whole script. A redirect may go to
another HTTPS host (GitHub serves its files from other hosts); the
SHA-256 and the attestation, not the host name, prove the file. The
script takes only the member pullgate out of the tarball, and only
after the attestation passed. GNU tar refuses members with .. and
removes a leading /; a pullgate that is a link, a device or not a
regular file is refused. Root never runs anything else from the tarball.
Attack. A local user can write the config, the deploy key, the known hosts file, the program of a command, or a directory above one of them.
Defense. pullgate refuses to start then (DESIGN.md section 4). A local
repo URL must pass the same check as the clone, because root runs
git-upload-pack in it. The listener checks its own config and token file.
Attack. Someone pushes many commits to tire the owner into tapping Apply.
Defense. At most one open question per instance; a newer tip replaces it.
questions_per_day caps the questions. A SHA is asked once, or once more
per reask_after after a Skip or an expiry; each of these counts against
questions_per_day. With settle, a tip is asked only when root has seen
it unchanged for that long, by root's own clock (not the commit date, which
the writer sets). So a writer who keeps moving the branch gets no question
at all, and the owner always has a question that stays the same while he
reads it.
Check exit 3. check runs as check_user on the commit's tree, so a
hostile commit can make it exit 3. That only marks the SHA nothing: no
question, no apply, and the applied SHA stays. It cannot apply anything,
and it is no worse than a check that fails. The next real commit is asked
with every commit since the last real apply, so nothing is hidden from the
owner. Root takes only the exit status; it reads nothing else from the
check.
Left. A writer can delay a question by pushing more often than settle.
That only delays; it never applies.
Attack. The pullgate binary runs as root. Whoever can publish a release
ships code to root on every host that installs it.
Defense. A release is the merge of the release pull request on main
(docs/releasing.md). Only the release App can create a v* tag, nobody can
move one, releases are immutable, and the release environment needs the
owner's approval. The build job is read-only and checks that the tag is the
commit of the run. Each tarball has a SHA-256 in SHA256SUMS and a build
provenance attestation tied to release.yml on main. Check both before
you install (docs/releasing.md, "Verify a download"), or let install.sh
check them (T17).
Attack. install.sh runs as root and puts a binary that root runs later.
An attacker tries to make it install a file that the release workflow did
not build, or an older build under a newer name. Or a local user changes a
file or a directory that the script uses while it runs. Or the
environment of root changes what tar, curl or gh do.
What the script trusts.
- GitHub: to serve the release files and the answer of its API over HTTPS, and to run the release workflow on its own runners.
- The release workflow identity: only
https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main, on a runner that GitHub hosts, may have built the tarball. Sigstore's public trusted root says whether the attestation is valid. - The pinned gh: gh 2.102.0, checked against a SHA-256 for each CPU that
is written in the script. Or a gh that the owner gives with
--gh: it must be 2.93.0 or newer, and only root may change it. - The script itself: the owner downloads it over HTTPS and reads it before running it.
- The host: root, and the programs in
/usr/sbin:/usr/bin:/sbin:/bin.
Defense. (DESIGN.md section 16.) The script installs nothing unless every
check passes: exactly one line in SHA256SUMS for the tarball, and its
SHA-256 matches; gh attestation verify with the bundle of the release,
--repo code6x/pullgate, the identity above and
--deny-self-hosted-runners; the new binary prints pullgate X.Y.Z of the
version asked for. The attestation proves which workflow built a file, not
its version, so the version check stops an older build under a newer name.
The new binary runs only after the attestation passed. Every download has
a size limit, uses HTTPS only with TLS 1.2 or newer, and reads no
.curlrc. The script removes a list of variables that change tar,
gzip, curl, OpenSSL, gh, name lookups, libc and the dynamic loader, sets
LC_ALL=C, and as root uses a fixed PATH. pullgate and gh run with a time
limit (timeout), and curl has its own. It writes the new file to the disk before the rename. gh runs with no token and an empty config. Only root may
change the bin directory, the old binary, TMPDIR, the new temporary
directory and the --gh file, and each directory above them. A directory
above them that others can write is accepted only with the sticky bit, as
/tmp has. The old
binary must be a regular file, never a link. The new file replaces the old
one by a rename in the same directory, as the last step.
What is left. Whoever controls the release workflow on main (T16), or
GitHub itself, can ship a binary that passes. The script cannot check
itself: a changed copy of install.sh can do anything, so read it before
you run it. The list of removed variables is a block list: a variable that
is not on it, or one that acts before the first line runs (such as
SHELLOPTS when sh is bash), still reaches the programs. Who controls
root's environment controls root already; to be sure, start the script
with env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh install.sh. The proxy
variables stay on purpose: TLS and the attestation protect what comes
through a proxy. The old binary runs once, as root, to print its version; only
root can change it, so this gives nothing new to an attacker. The script
restarts nothing.
Attack. The owner, by mistake, or a taken-over listener sends many
/check requests, so the host fetches all the time and loads the git
server.
Defense. Root allows at most one run per minute from the check directory.
It keeps the time in its own state, not in the listener. A run that finds a
request inside that minute removes it, does not fetch, and sends at most one
reply per minute. A clock that goes back by less than a minute does not
pass the limit. Many /check messages before root reads them are one
file (a fixed name). The path unit starts the same run unit as the timer,
and systemd never starts it twice at once; the lock keeps a run and an
apply apart. A run that sees a request while the lock is held waits for
it, instead of starting again and again. The listener writes at most one
request per instance in 10 seconds, so a burst of /check from the owner
does not reach the trigger limit of the path unit.
Left. One fetch per minute, and one reply per minute. A taken-over
listener can write requests fast enough to hit the trigger limit of the
path unit; systemd then stops the path unit, and /check does nothing
until the owner resets it (DESIGN.md section 8). The run unit has no start
limit, so the timer goes on. This denies; it never approves. A clock jump back of more than
a minute allows one more run.
Attack. Someone with the bot token, or a compromised listener, sends
/status or /pause, or writes the request files directly.
Defense and what is left. The request files hold only their kind; root reads its own state and acts. So the most they can do:
- See a status: the mode, the SHAs, the open question, the pause and
broken reasons. With the token they can read the questions anyway, which
show more. The status holds no key or token. It shows the error texts
that were sent in notices already (the broken reason), and nothing new.
Root answers at most once a minute, and a
/statusnever skips the normal run, so a stream of them cannot stop the fetches. - Pause an instance. This only stops work: it never applies or
approves anything. A thief can deny work in other ways already (not
deliver a tap). Root never changes a pause file that is there (it makes
the file with a hard link, which fails if the name exists), so a
/pausecannot replace the reason of a safety pause, and a later limited/resume(#33) cannot use it to lift one.
/resume and /ask-again (#33) can undo a stop, so
they are limited. /resume lifts only a pause whose file is exactly what
/pause writes (root's regular file, one link, one line in that form):
the only pause a thief could set anyway. So if the owner suspects the
token or the listener, the owner pauses as root (pullgate status NAME --pause): a token holder can lift a /pause. /resume moves the file
aside and checks that it is the file it checked, so a pause that root
writes at the same moment is put back and stays. A pause that pullgate set after a
cut-off apply, or that root set, stays, and so does the broken state
(T6). /ask-again clears only an expired mark or an open question; it
never re-asks a commit that the owner skipped or that failed, was held or
was refused, so a thief cannot re-ask a skipped commit and hope for a
wrong tap. A new question still needs the owner's tap, and counts in
questions_per_day.
Apart from that, they cannot approve or change the state: the state directory is root's (0700), and any other file in the check directory is removed and does nothing (a test).
Attack or accident. Someone sends the bot messages to learn what it runs, or the owner's client sends many messages.
Defense. Only the owner, in the owner's chat, gets an answer: /help, the
usage text of /check, or "Not a command". Others get nothing, so the bot
does not tell strangers that it exists. The /help text is fixed: the
commands, the instance names and the pullgate status commands. It holds
no secret, no path and nothing about the host beyond the instance names,
which every question shows too (with the host value). It never repeats the text of a message.
The /help reply and the "Not a command" reply are each sent at most
once per minute.
Left. Someone with the bot token can read the help, as they can read every question.
The update replaces the program that is the gate. A wrong or bad binary removes the gate on that host. So it has the same rules as a commit, and more checks.
Attack: a bad binary. An attacker serves a tarball that the release
workflow did not build, or an older build under a newer name.
Defense. Root runs the copy of install.sh that is built into the
running binary, so the code that checks is the code that was checked and
installed before. Before the question is sent it checks the SHA-256
from SHA256SUMS and runs gh attestation verify with the release bundle
and the release workflow identity. No code of the release runs before the
tap: --check-only does not run the new binary. On Apply it downloads the
files again and does every check of T17 again, and also runs the new
binary's pullgate version. On Apply, the tarball must also have the SHA-256 that the
question showed (--sha256), so Apply installs only that file (rule 2). The
attestation check is required. There is no setting that skips it.
[updates] gh names the gh that checks, as install.sh --gh does; it must
be gh 2.93.0 or newer and only root may change it. A release that fails a
check gets a warning notice, never a question and never the "/update" hint.
Attack: a stolen bot token. The thief can send /update as a message,
but only the owner's user ID in the owner's chat counts (rule 4), and a
message holds nothing: the listener writes the six bytes check\n. A
forged request only makes root look for a release and ask. The thief
cannot tap as the owner (T1). Root takes the version and the SHA-256 from
its own state, never from the approval.
Attack: a compromised listener. It can write requests and approvals in
/var/spool/pullgate/_update/, as for an instance (T2, T12). An approval
counts only with the code of the open question, within 12 hours, once. It
cannot name a version or a file.
Attack: a published release that is bad (T16 failed). Forward only:
root never installs the same or an older version from Telegram (its own
check, and install.sh --forward-only). The owner taps Apply after reading
the release notes. A release is never installed without a tap: the daily
notice only says "send /update". The owner can install a pinned version by
hand with install.sh --version X.Y.Z.
Accident: the new binary does not start. Root keeps the old binary as
.pullgate.prev until the new one works: it runs pullgate version, gets
the units of the new binary (pullgate units), installs the ones that
changed, reloads systemd, restarts the units, restarts the listener last,
and checks that the listener is still active 5 seconds later. When a step
fails, it puts the old binary and the old unit files back, reloads,
restarts the listener, and reports. The new listener sends the report of
a good update, so the report also shows that it runs.
The units. Root writes only files named pullgate-*.service, .timer
or .path in /etc/systemd/system, at most 32 of 64 KiB, that the new
(attested) binary carries. A unit that is a link (for example masked) is
left alone. Drop-ins are never changed: they are listed in the report, so
the owner sees a workaround that a release made unneeded. A unit that the
owner disabled stays disabled; only a unit that is new in this version is
enabled.
Name space. The updates use /var/lib/pullgate/_update/ and
/var/spool/pullgate/_update/. An instance name matches
[a-z0-9][a-z0-9-]{0,31}, so no instance can be named _update, and an
instance named pullgate has its own directories (TestUpdateQuestionsAreTheirOwn).
Left. Whoever controls the release workflow on main, or GitHub, can
ship a binary that passes (T16); the owner's tap is the last check. A
build from the source (pullgate dev) does not update itself.
Attack. The person who sets up a host pastes a script that someone else
wrote. The script writes its own owner_id into listener.toml, and so
gets the bot and every Apply. Or the token leaks: into the shell history,
a process list, a log, or the environment of a child program. Or someone
else sends the pairing code first, or guesses it.
Defense. pullgate bootstrap (DESIGN.md section 17):
- The IDs come only from the Telegram message that carries the one-time
code. No flag, config key or variable sets them; a planted
listener.tomlis replaced at the pairing. Bootstrap refuses unknown options, such as--owner-id.--api-urltakes only the real Bot API or a test server on127.0.0.1: a pasted script cannot send the pairing through a server that changes the sender ID. The listener'sapi_urlis parsed the same way, sohttp://127.0.0.1:80@hostis refused. - The code is 8 random digits, valid for 10 minutes, printed only on the console of the host. 5 wrong codes stop the pairing, so a guess works with a chance of 5 in 100 million. The right code counts only from a private chat with a person; from a group it stops the pairing, because others saw it. A wrong code, a group or a timeout writes nothing.
- The token is read with
systemd-ask-password(no echo, no history, no argument) or from stdin. It is checked withgetMe, stored with mode 0600, and never printed. Programs that bootstrap starts get onlyPATHandLC_ALL. - The deploy key is made on the host; only the public key is printed. The
host key of
github.comcomes from the binary, with its fingerprint shown; another git host needs a file that the owner checked.
Left. Someone who sees the console of the host during the pairing can
send the code first. Check the chat: bootstrap sends "paired" to the chat
that won. A pasted script can still do anything else as root; bootstrap
only takes away the quiet way to plant the owner ID. If the failed run
leaves an old listener.toml, bootstrap says that it did not write it.
- An attacker who is root on the host.
- A program that a command runs and that pullgate did not check (for
example a tool that
applycalls by name). The owner writesapply. - An attacker who controls the owner's Telegram account.
- A bad change that the owner approves on purpose.
- Signed commits (planned later).