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
34 changes: 31 additions & 3 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ can be less strict; each example sets what its `apply` needs.
| `/var/spool/pullgate/NAME/outbox` | root, group listener, 0770 (no setgid) | messages from root to the listener |
| `/var/spool/pullgate/NAME/outbox/*.json` | root, group listener, 0640 | one message |
| `/var/spool/pullgate/NAME/inbox` | listener, 0700 | approvals from the listener to root |
| `/var/spool/pullgate/NAME/check` | listener, 0700 | check requests from the listener to root |
| `/var/spool/pullgate/NAME/check` | listener, 0700 | check, status and pause requests from the listener to root |
| `/var/lib/pullgate-listener/state.json` | listener, 0600 | the listener's open questions |
| `/var/lib/pullgate/_update/` and `.../tmp/` | root, 0700 | the state, the lock and the downloads of `pullgate update` (section 15) |
| `/var/spool/pullgate/_update/` | as `NAME/` above | the outbox, inbox and check request of the updates |
Expand Down Expand Up @@ -390,8 +390,9 @@ six bytes `check\n`. It holds nothing from the message: not the text, not
a SHA, not a code. A check request can only start a normal run. It is not
an approval, and `pullgate apply` never reads this directory.

`pullgate-check@NAME.path` watches the file `check/request`
(`PathExists=`; another file there starts nothing) and starts `pullgate-run@NAME.service`, the unit of the timer. `pullgate run`,
`pullgate-check@NAME.path` watches the files `check/request`,
`check/status` and `check/pause` (`PathExists=`; another file there starts
nothing) and starts `pullgate-run@NAME.service`, the unit of the timer. `pullgate run`,
with the lock held (a run that had to wait for the lock, and then finds
no request, stops: another run took the request):

Expand Down Expand Up @@ -473,6 +474,33 @@ these hold, else it answers "This question is closed." and writes nothing:
Then it writes the approval, edits the question ("Apply tapped. Waiting for
the host." or "Skipped."), and answers the tap.

**`/status` and `/pause`** (code6x/pullgate#32). The same checks of the
sender, the chat and the edit hold, as for `/check`. The text is `/status`
(every instance), `/status NAME`, or `/pause NAME` (more words after NAME
are allowed and dropped: the reason never reaches root). The listener
writes a request file in the check directory: `status` or `pause`, with
exactly its name and a newline in it, and nothing from the message. The
same command for the same instance within a minute writes nothing, and
gets "asked less than a minute ago". Root
takes the requests in its run, as check requests (owned by the listener,
a regular file, the exact content; any other file is removed and does
nothing):

- `pause`: if there is no pause file, root writes one with the reason
`paused from Telegram at TIME` (the prefix `state.TelegramPause`; no
other reason starts with it). A pause file that is there is never
changed, so that a pause that pullgate or root set keeps its reason. The
pause is never rate-limited; its reply goes out at most once a minute.
The file is made with a hard link, which fails when the name exists, so
a pause that root writes at the same moment is never replaced.
- `status`: root sends a notice with the facts of `pullgate status`
(section 13), cleaned and in `<pre>`, at most once a minute. It is
read-only.
- Then the normal run goes on, so a stream of `/status` never stops the
fetches. After a `/pause`, the run ends as paused.

To go on after `/pause`, root runs `pullgate status NAME --resume`.

**`/check`.** The listener writes a check request (section 8) only when all
of these hold, else it writes nothing:

Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,19 @@ usual Apply question, or "No new commit (the applied commit is …)", or
- Without `pullgate-check@NAME.path`, the request waits for the next timer
run.

## Status and pause: `/status`, `/pause`

- `/status` (all instances) or `/status NAME`: the mode, the applied
commit, the last tip, the open question, paused or not and why, broken
or not. It changes nothing. At most one answer per instance a minute.
- `/pause NAME`: pauses the instance. Nothing is fetched, asked or applied
until root runs `pullgate status NAME --resume` on the host. If it is
paused already, the old pause stays as it is. A reason after NAME is not
sent to the host.

As with `/check`, only your user ID in your chat counts, and the listener
only writes a small request file; root does the work.

## Update pullgate: `/update`

Once a day `pullgate-update.timer` looks for a new release of pullgate. For
Expand Down
25 changes: 25 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -479,6 +479,31 @@ 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.

### T18b. `/status` and `/pause` from a stolen token or the listener

*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 `/status` never 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
`/pause` cannot replace the reason of a safety pause, and a later
limited `/resume` (code6x/pullgate#33) cannot use it to lift one.

They cannot resume, 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).

### T19. What the bot tells

*Attack or accident.* Someone sends the bot messages to learn what it runs,
Expand Down
6 changes: 4 additions & 2 deletions contrib/systemd/pullgate-check@.path
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
# Starts pullgate-run@NAME.service when the listener writes a check request
# for /check on Telegram (DESIGN.md section 8). The run is the normal run:
# for /check, /status or /pause on Telegram (DESIGN.md sections 8 and 9). The run is the normal run:
# the same unit, sandbox and lock. Root removes the request and allows at
# most one requested run per minute.
[Unit]
Description=pullgate check requests for %i

[Path]
# Only the request file counts, so another file in the directory does not
# Only the request files count, so another file in the directory does not
# start runs again and again.
PathExists=/var/spool/pullgate/%i/check/request
PathExists=/var/spool/pullgate/%i/check/status
PathExists=/var/spool/pullgate/%i/check/pause
Unit=pullgate-run@%i.service
# At most 10 starts a minute. This stops a loop when a run fails before it
# removes the request. The listener writes at most one request per instance
Expand Down
56 changes: 49 additions & 7 deletions internal/gate/check.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
package gate

import (
"strings"
"time"

"github.com/code6x/pullgate/internal/message"
"github.com/code6x/pullgate/internal/spool"

"github.com/code6x/pullgate/internal/state"
)

Expand All @@ -12,20 +16,58 @@ import (
const CheckInterval = time.Minute

// takeChecks reads and removes the files in the check directory, and
// returns how many were valid check requests. A bad file is logged and
// removed. An error of the directory counts as no request (fail closed).
func (e *Env) takeChecks() int {
n, bad, err := e.Spool.TakeChecks(e.Owners.ListenerUID)
// returns the valid requests. A bad file is logged and removed. An error
// of the directory counts as no request (fail closed).
func (e *Env) takeChecks() spool.Requests {
r, bad, err := e.Spool.TakeRequests(e.Owners.ListenerUID)
for _, b := range bad {
e.Log.Warn("bad check request, removed", "err", b)
}
if err != nil {
e.Log.Error("read the check requests", "err", err)
}
if n > 0 {
e.Log.Info("check request taken")
if r.Any() {
e.Log.Info("requests taken", "check", r.Check, "status", r.Status, "pause", r.Pause)
}
return r
}

// pauseRequest acts on /pause: it writes the pause file, unless there is
// one. A pause that is there already is never changed, so that a later
// /resume (code6x/pullgate#33) cannot lift it. The pause itself is never
// rate-limited; its reply is, once a minute.
func (e *Env) pauseRequest(st *state.State) {
now := e.now()
var text string
wrote, err := e.Dir.PauseIfNone(state.TelegramPause + now.UTC().Format("2006-01-02 15:04 MST"))
switch {
case err != nil:
e.Log.Error("write the pause file", "err", err)
text = "Error: " + e.Cfg.Name + " could not be paused. See the journal of the host."
case !wrote:
text = "⏸ " + e.Cfg.Name + " was paused already: " + message.Code(e.Dir.PauseReason())
default:
e.Log.Info("paused from Telegram")
text = "⏸ " + e.Cfg.Name + " is paused. Nothing is fetched, asked or applied. To go on, run as root: <code>pullgate status " + e.Cfg.Name + " --resume</code>"
}
if d := now.Sub(st.PauseNote); d >= CheckInterval || d <= -CheckInterval {
st.PauseNote = now
e.notice(text)
}
}

// statusRequest answers /status with the facts of "pullgate status",
// at most once a minute.
func (e *Env) statusRequest(st *state.State) {
now := e.now()
if d := now.Sub(st.StatusAt); d < CheckInterval && d > -CheckInterval {
e.Log.Warn("status request dropped: the last one was less than a minute ago")
return
}
return n
st.StatusAt = now
var b strings.Builder
e.statusText(&b, st)
e.notice("Status:\n" + message.Output(b.String(), 30))
}

// limitCheck enforces CheckInterval. It returns CheckLimited when the
Expand Down
115 changes: 115 additions & 0 deletions internal/gate/request_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
package gate

import (
"os"
"path/filepath"
"strings"
"testing"
"time"

"github.com/code6x/pullgate/internal/spool"
"github.com/code6x/pullgate/internal/state"
)

func (f *fixture) requestKind(kind string) {
f.t.Helper()
if err := f.env.Spool.Ensure(f.env.UID, f.env.Owners); err != nil {
f.t.Fatal(err)
}
if err := f.env.Spool.WriteRequest(kind); err != nil {
f.t.Fatal(err)
}
}

func TestStatusRequest(t *testing.T) {
f := newFixture(t, ``, "")
a := f.applyNew("one")
f.commit("second", "two", nil)
f.requestKind(spool.RequestStatus)
// /status never skips the normal run: a stream of them cannot stop
// fetches.
if r := f.run(); r != Asked {
t.Fatalf("run: %s", r)
}
ms := f.outbox()
if len(ms) != 2 || ms[0].Kind != spool.KindNotice || !strings.Contains(ms[0].Text, "applied:") ||
!strings.Contains(ms[0].Text, a) || !strings.Contains(ms[0].Text, "paused: no") || ms[1].Kind != spool.KindAsk {
t.Fatalf("status notice, then the question: %+v", ms)
}
// A second one within a minute is dropped.
f.requestKind(spool.RequestStatus)
f.run()
if len(f.outbox()) != 0 {
t.Fatal("a second /status within a minute must get no answer")
}
// It works while paused, and shows why.
f.now = f.now.Add(2 * time.Minute)
if err := f.env.Dir.Pause("paused by the owner"); err != nil {
t.Fatal(err)
}
f.requestKind(spool.RequestStatus)
f.run()
if !contains(f.outbox(), "paused: yes: paused by the owner") {
t.Fatal("the status must show the pause and its reason")
}
}

func TestPauseRequest(t *testing.T) {
f := newFixture(t, ``, "")
f.applyNew("one")
f.requestKind(spool.RequestPause)
f.run()
if !f.env.Dir.Paused() || !strings.HasPrefix(f.env.Dir.PauseReason(), state.TelegramPause+"2026-11-11 12:00") {
t.Fatalf("not paused from Telegram: %q", f.env.Dir.PauseReason())
}
if !contains(f.outbox(), "is paused. Nothing is fetched") {
t.Fatal("no reply")
}
f.commit("second", "two", nil)
if r := f.run(); r != Paused {
t.Fatalf("a paused instance does nothing: %s", r)
}
}

func TestPauseRequestKeepsAnOtherPause(t *testing.T) {
f := newFixture(t, ``, "")
if err := f.env.Dir.Ensure(); err != nil {
t.Fatal(err)
}
if err := f.env.Dir.Pause("the apply of x was cut off"); err != nil {
t.Fatal(err)
}
f.requestKind(spool.RequestPause)
f.run()
if f.env.Dir.PauseReason() != "the apply of x was cut off" {
t.Fatalf("a pause that is there must not change: %q", f.env.Dir.PauseReason())
}
if !contains(f.outbox(), "was paused already") {
t.Fatal("no reply")
}
}

// The listener can only write request files; a bad one pauses nothing.
func TestListenerCannotPauseByOtherFiles(t *testing.T) {
for _, c := range []struct{ name, content string }{
{"pause", "pause\nby a thief\n"},
{"paused", "x\n"},
{"state.json", `{"applied":""}`},
} {
t.Run(c.name, func(t *testing.T) {
f := newFixture(t, ``, "")
f.commit("first", "one", nil)
f.request()
if err := os.WriteFile(filepath.Join(f.env.Spool.CheckDir(), c.name), []byte(c.content), 0o600); err != nil {
t.Fatal(err)
}
f.run()
if f.env.Dir.Paused() {
t.Fatal("a bad request file must not pause")
}
if _, err := os.Lstat(filepath.Join(f.env.Spool.CheckDir(), c.name)); err == nil {
t.Fatal("root must remove the bad file")
}
})
}
}
11 changes: 10 additions & 1 deletion internal/gate/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,16 @@ func (e *Env) Run(ctx context.Context) (Result, error) {
if err != nil {
return "", err
}
requested := requests > 0
if requests.Pause > 0 {
e.pauseRequest(st)
paused = e.Dir.Paused()
}
if requests.Status > 0 {
e.statusRequest(st)
}
// Then the normal run goes on: /status never skips a fetch, and after
// /pause the paused check below ends the run.
requested := requests.Check > 0
if requested {
if r := e.limitCheck(st); r != "" {
return r, e.Dir.Save(st)
Expand Down
10 changes: 8 additions & 2 deletions internal/gate/status.go
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,13 @@ func (e *Env) Status(w io.Writer, f StatusFlags) error {
e.edit(closed.ID, "This question for "+code(closed.SHA)+" is closed: the owner ran --ask-again. The next run asks again.")
_, _ = fmt.Fprintf(w, "The open question %d for %s is closed. The next run asks again.\n", closed.ID, closed.SHA)
}
e.statusText(w, st)
return nil
}

// statusText writes the facts of the state, for "pullgate status" and
// /status.
func (e *Env) statusText(w io.Writer, st *state.State) {
show := func(k, v string) { _, _ = fmt.Fprintf(w, "%-12s %s\n", k+":", v) }
show("instance", e.Cfg.Name)
show("mode", e.Cfg.Mode)
Expand All @@ -92,14 +99,13 @@ func (e *Env) Status(w io.Writer, f StatusFlags) error {
show("broken", fmt.Sprintf("since %s, last error: %s", b.Since.Format("2006-01-02 15:04 MST"), b.Reason))
}
if e.Dir.Paused() {
show("paused", "yes: "+e.Dir.PauseFile())
show("paused", "yes: "+e.Dir.PauseReason()+" ("+e.Dir.PauseFile()+")")
} else {
show("paused", "no")
}
if st.InProgress != nil {
show("in progress", fmt.Sprintf("%s of %s since %s", st.InProgress.Phase, st.InProgress.SHA, st.InProgress.Started.Format("2006-01-02 15:04 MST")))
}
return nil
}

// forgetOpen removes the open question for sha from the state and returns
Expand Down
Loading