diff --git a/DESIGN.md b/DESIGN.md index 895edb1..03f4f72 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -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. diff --git a/README.md b/README.md index f823af5..16487dc 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 10d7f7b..6738c8d 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -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. diff --git a/internal/listener/listener.go b/internal/listener/listener.go index 5b85255..fc6d9bc 100644 --- a/internal/listener/listener.go +++ b/internal/listener/listener.go @@ -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 { @@ -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, ""+html.EscapeString(n)+"") + } + return strings.Join([]string{ + "pullgate commands:", + "/check: look for a new commit now, on every instance", + "/check NAME: the same, on one instance", + "/help: this list", + "", + "Instances: " + strings.Join(names, ", "), + "", + "A question has two buttons. Apply applies that one commit. Skip skips it; a newer commit is asked again.", + "", + "On the host, as root:", + "pullgate status NAME: the mode, the applied commit, the open question, paused or not", + "pullgate status NAME --pause and --resume: stop and start the instance", + "pullgate status NAME --ask-again: 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 /help for the list.") + return + } if help { l.sendReply(ctx, m, "Use /check for all instances, or /check NAME. NAME is one of: "+html.EscapeString(strings.Join(l.Cfg.Instances, ", "))+".") } @@ -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: diff --git a/internal/listener/listener_test.go b/internal/listener/listener_test.go index 2ad416e..b497726 100644 --- a/internal/listener/listener_test.go +++ b/internal/listener/listener_test.go @@ -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) { @@ -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 /check")): 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 /help 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 { @@ -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{"/check", "/check NAME", "/help", "" + inst + "", "" + inst2 + "", "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)