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
18 changes: 16 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -482,8 +482,22 @@ a few seconds ago" (section 8, the start limit). When a request cannot be
written (for example the host never ran pullgate for NAME, so the directory
does not exist), it replies that the request was not saved. To the owner in
the chat, a text that starts with `/check` but does not match gets the
usage text, which lists the instances and never repeats the message. A
message of another user, or in another chat, gets no answer. The listener
usage text, which lists the instances and never repeats the message.

**`/help`.** When the text is exactly `/help`, from `owner_id`, in
`chat_id`, not edited, the listener replies with a fixed list: the
commands (`/check`, `/check NAME`, `/help`), the instance names from
`instances`, what Apply and Skip do, and the root commands for the host
(`pullgate status NAME`, `--pause`, `--resume`, `--ask-again`), at most
once per minute. The
listener does not know the mode or the pause file of an instance (root's
files), so the list points to `pullgate status NAME` for them. Any other
text of the owner in the chat that is not a command (does not start with
`/check`) gets one reply, "Not a command. Send /help for the list.", at
most once per minute (in memory), so a stuck client or a long paste cannot
fill the chat. A message of another user, or in another chat, or an
edited message, gets no answer, so the bot does not tell strangers that it
exists. The listener
never logs the text of a message: only why it was ignored and the sender
ID.

Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,14 @@ To see the version of a binary, run `pullgate --version` or
`pullgate version`. Both print `pullgate X.Y.Z` and exit 0. A build from
the source without `-ldflags "-X main.version=..."` prints `pullgate dev`.

## Commands: `/help`

Send the bot `/help` to get the list of commands, the instances of this
listener, what Apply and Skip do, and the `pullgate status` commands for
the host. Any other text from you (not a command) gets one short reply:
"Not a command. Send /help for the list.", at most once a minute.
Messages from other users, or in other chats, get no answer.

## Check now: `/check`

The timer runs every 5 minutes. After a push you do not have to wait: send
Expand Down
17 changes: 17 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -444,6 +444,23 @@ 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.

### T19. What the bot tells

*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.

## 6. Out of scope

- An attacker who is root on the host.
Expand Down
59 changes: 58 additions & 1 deletion internal/listener/listener.go
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,8 @@ type Listener struct {
mu sync.Mutex
st State
lastCheck map[string]time.Time // in memory: the last check request per instance
lastHint time.Time // in memory: the last "Not a command" reply
lastHelp time.Time // in memory: the last /help reply
}

func hash(s string) string {
Expand Down Expand Up @@ -405,15 +407,68 @@ func (l *Listener) check(cq *telegram.CallbackQuery) (*Question, string, string)
return q, action, ""
}

// checkCommand is the one command the listener takes (DESIGN.md section 9).
// checkCommand asks for a run now (DESIGN.md section 9).
const checkCommand = "/check"

// helpCommand lists what the bot can do.
const helpCommand = "/help"

// HintGap is the least time between two "Not a command" replies, so that a
// stuck client or a long paste cannot make the bot fill the chat.
const HintGap = time.Minute

// helpText is the answer to /help. It holds no secret and nothing about
// the host beyond the instance names, which every question shows too.
func (l *Listener) helpText() string {
var names []string
for _, n := range l.Cfg.Instances {
names = append(names, "<b>"+html.EscapeString(n)+"</b>")
}
return strings.Join([]string{
"<b>pullgate</b> commands:",
"<code>/check</code>: look for a new commit now, on every instance",
"<code>/check NAME</code>: the same, on one instance",
"<code>/help</code>: this list",
"",
"Instances: " + strings.Join(names, ", "),
"",
"A question has two buttons. <b>Apply</b> applies that one commit. <b>Skip</b> skips it; a newer commit is asked again.",
"",
"On the host, as root:",
"<code>pullgate status NAME</code>: the mode, the applied commit, the open question, paused or not",
"<code>pullgate status NAME --pause</code> and <code>--resume</code>: stop and start the instance",
"<code>pullgate status NAME --ask-again</code>: ask again about the newest commit of the branch",
}, "\n")
}

// command handles a message. Only "/check" or "/check NAME" of the owner,
// in the chat, unedited, counts. The text of a message is never logged.
func (l *Listener) command(ctx context.Context, m *telegram.Message) {
names, why, help := l.checkNames(m)
if why == "help" {
now := l.now()
if d := now.Sub(l.lastHelp); d < HintGap && d > -HintGap {
l.Log.Info("message ignored", "reason", "a second /help within a minute", "from", fromID(m))
return
}
l.lastHelp = now
l.Log.Info("help sent", "from", fromID(m))
l.sendReply(ctx, m, l.helpText())
return
}
if names == nil {
l.Log.Info("message ignored", "reason", why, "from", fromID(m))
if why == "not a command" {
// The owner, in the chat: one short hint, at most once per
// HintGap. The text is never repeated.
now := l.now()
if d := now.Sub(l.lastHint); d < HintGap && d > -HintGap {
return
}
l.lastHint = now
l.sendReply(ctx, m, "Not a command. Send <code>/help</code> for the list.")
return
}
if help {
l.sendReply(ctx, m, "Use <code>/check</code> for all instances, or <code>/check NAME</code>. NAME is one of: "+html.EscapeString(strings.Join(l.Cfg.Instances, ", "))+".")
}
Expand Down Expand Up @@ -461,6 +516,8 @@ func (l *Listener) checkNames(m *telegram.Message) ([]string, string, bool) {
return nil, "not the configured chat", false
case m.EditDate != 0:
return nil, "an edited message", false
case m.Text == helpCommand:
return nil, "help", false
case !strings.HasPrefix(m.Text, checkCommand):
return nil, "not a command", false
case m.Text == checkCommand:
Expand Down
98 changes: 84 additions & 14 deletions internal/listener/listener_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -343,20 +343,21 @@ func TestCheckCommandsThatDoNotCount(t *testing.T) {
text string
edited bool
help bool // the owner gets the usage text
hint bool // the owner gets "Not a command"
}{
"another user": {owner + 1, chat, "/check", false, false},
"another chat": {owner, chat + 1, "/check", false, false},
"edited message": {owner, chat, "/check", true, false},
"unknown name": {owner, chat, "/check other", false, true},
"extra text": {owner, chat, "/check " + inst + " now", false, true},
"two spaces": {owner, chat, "/check " + inst, false, true},
"to another bot": {owner, chat, "/check@otherbot", false, true},
"name with @": {owner, chat, "/check@otherbot " + inst, false, true},
"other text": {owner, chat, "hello", false, false},
"command in a line": {owner, chat, "please /check", false, false},
"other user, known": {owner + 1, chat, "/check " + inst, false, false},
"trailing new line": {owner, chat, "/check\n", false, true},
"upper case command": {owner, chat, "/CHECK", false, false},
"another user": {owner + 1, chat, "/check", false, false, false},
"another chat": {owner, chat + 1, "/check", false, false, false},
"edited message": {owner, chat, "/check", true, false, false},
"unknown name": {owner, chat, "/check other", false, true, false},
"extra text": {owner, chat, "/check " + inst + " now", false, true, false},
"two spaces": {owner, chat, "/check " + inst, false, true, false},
"to another bot": {owner, chat, "/check@otherbot", false, true, false},
"name with @": {owner, chat, "/check@otherbot " + inst, false, true, false},
"other text": {owner, chat, "hello", false, false, true},
"command in a line": {owner, chat, "please /check", false, false, true},
"other user, known": {owner + 1, chat, "/check " + inst, false, false, false},
"trailing new line": {owner, chat, "/check\n", false, true, false},
"upper case command": {owner, chat, "/CHECK", false, false, true},
}
for n, c := range cases {
t.Run(n, func(t *testing.T) {
Expand All @@ -369,7 +370,9 @@ func TestCheckCommandsThatDoNotCount(t *testing.T) {
switch {
case c.help && (len(ms) != 1 || ms[0].Chat != chat || !strings.Contains(ms[0].Text, "Use <code>/check</code>")):
t.Fatalf("the owner must get the usage text: %+v", ms)
case !c.help && len(ms) != 0:
case c.hint && (len(ms) != 1 || ms[0].Text != "Not a command. Send <code>/help</code> for the list."):
t.Fatalf("the owner must get the hint: %+v", ms)
case !c.help && !c.hint && len(ms) != 0:
t.Fatalf("no answer may be sent: %+v", ms)
}
for _, m := range ms {
Expand All @@ -381,6 +384,73 @@ func TestCheckCommandsThatDoNotCount(t *testing.T) {
}
}

// TestHelp: /help from the owner in the chat gets the list, which names
// each instance (code6x/pullgate#26).
func TestHelp(t *testing.T) {
f, _ := newL2(t)
f.say(owner, chat, "/help", false)
ms := f.tg.Messages()
if len(ms) != 1 || ms[0].Chat != chat || ms[0].ReplyTo == 0 {
t.Fatalf("want one reply: %+v", ms)
}
for _, want := range []string{"<code>/check</code>", "<code>/check NAME</code>", "<code>/help</code>", "<b>" + inst + "</b>", "<b>" + inst2 + "</b>", "Apply", "Skip", "--pause", "--resume", "--ask-again"} {
if !strings.Contains(ms[0].Text, want) {
t.Errorf("the help must hold %q:\n%s", want, ms[0].Text)
}
}
if strings.Contains(ms[0].Text, token) || strings.Contains(ms[0].Text, f.l.Cfg.SpoolDir) {
t.Error("the help must hold no secret and no path")
}
if f.d.HasCheck() {
t.Error("/help writes no request")
}
// A second /help within a minute gets nothing.
f.say(owner, chat, "/help", false)
if len(f.tg.Messages()) != 1 {
t.Fatal("a second /help within a minute must get no reply")
}
}

// TestHelpAndHintNotForOthers: /help and other text from another user, in
// another chat, or edited, get no reply.
func TestHelpAndHintNotForOthers(t *testing.T) {
for _, c := range []struct {
from, chat int64
edited bool
}{{owner + 1, chat, false}, {owner, chat + 1, false}, {owner + 1, chat + 1, false}, {owner, chat, true}} {
f := newL(t)
f.say(c.from, c.chat, "/help", c.edited)
f.say(c.from, c.chat, "hello", c.edited)
if ms := f.tg.Messages(); len(ms) != 0 {
t.Fatalf("%+v: no reply may be sent: %+v", c, ms)
}
}
}

// TestHintOncePerMinute: other text from the owner gets the hint once; a
// second one in the same minute gets nothing; after a minute it comes
// again.
func TestHintOncePerMinute(t *testing.T) {
f := newL(t)
f.say(owner+1, chat, "hi", false) // a stranger does not use up the hint
f.say(owner, chat, "hello", false)
f.now = f.now.Add(30 * time.Second)
f.say(owner, chat, "a long paste", false)
if ms := f.tg.Messages(); len(ms) != 1 || !strings.Contains(ms[0].Text, "Not a command") {
t.Fatalf("want one hint: %+v", ms)
}
f.now = f.now.Add(31 * time.Second)
f.say(owner, chat, "hello again", false)
if ms := f.tg.Messages(); len(ms) != 2 {
t.Fatalf("a minute later the hint comes again: %+v", ms)
}
// /help is not limited by the hint.
f.say(owner, chat, "/help", false)
if ms := f.tg.Messages(); len(ms) != 3 || !strings.Contains(ms[2].Text, "commands") {
t.Fatalf("/help must answer: %+v", ms)
}
}

func TestReplayedUpdateIsIgnored(t *testing.T) {
f := newL(t)
f.say(owner, chat, "/check", false)
Expand Down
Loading