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
46 changes: 32 additions & 14 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,9 @@ These rules come from issue #1. Each one has tests (section 14).
approve and which paths get a warning come only from the host config:
`/etc/pullgate/NAME.toml` and `/etc/pullgate/listener.toml`. pullgate
never reads any setting from the repo. A commit cannot change the gate.
2. **One exact commit.** The question shows the full SHA. Apply applies only
that SHA, even when a newer commit arrives in between.
2. **One exact commit.** The question shows the full SHA once, on its last
line. Apply applies only that SHA, even when a newer commit arrives in
between. The tap is bound to the question (its code), not to the text.
3. **No code from the new commit runs before Apply.** Before the tap,
pullgate only fetches the commit and reads it with git. The optional
`check` and `summary` commands may read the tree as data. They run as an
Expand Down Expand Up @@ -606,26 +607,43 @@ pullgate on <b>HOST</b>, instance <b>NAME</b>
⚠ The last apply (SHA) failed. (only when a SHA is held)
⚠ This commit is not a descendant of … (only with allow_older)
Apply this commit?
<code>FULL SHA</code>
<code>SHORT SHA</code>
First apply: there is no applied commit yet. All N files are listed.
or: Since <code>APPLIED SHA</code>:
⚠ Watched path changed: path
⚠ Symlink out of the tree: path → target
⚠ Submodule skipped: path
or: Since <code>SHORT APPLIED SHA</code>:
⚠ Watched path changed: <code>path</code>
⚠ Symlink out of the tree: <code>path</code> → <code>target</code>
⚠ Submodule skipped: <code>path</code>

Commits (N):
• subject
• <code>subject</code>
Changed files (N):
• path
• <code>path</code>
Summary:
<pre>output of the summary command</pre>
Full: <code>FULL SHA</code>
```

Text from the commit (subjects, paths, symlink targets, summary output) is
cleaned before it is shown: control and invisible characters become `?`
(newlines stay only in the summary output), each line is cut to 200
characters, and then it is HTML-escaped. At most 50 commit subjects are
read.
**SHAs.** Every message shows a SHA as its first 12 characters, in
`<code>`. The question, as it is sent, shows the full SHA once, on its last line
("Full:"), so it can be copied and compared. That line stays after a cut.
(After a tap, the listener adds its note below it.) Logs,
the state and `pullgate status` keep the full SHA. Root applies the full
SHA from its own state, never a SHA from the text.

**Text from the repo is only shown as code.** Text from the repo, the
commit, or a command that ran on it (paths, subjects, symlink targets,
submodule paths, the output of `summary` and `check`, and errors that may
hold any of them) is put into a message only by `message.Code` (one line in
`<code>`) or `message.Output` (lines in `<pre>`). Telegram makes no link,
mention, hashtag or bot command of text inside `<code>` or `<pre>`, so a
file named `README.md` or `login.example.com` stays plain text. The escape
function is not exported, so other code cannot put repo text into a message
another way; a test also checks the gate code for its own HTML. Before that,
the text is cleaned: control and invisible characters (also right-to-left
marks) become `?` (newlines stay only in the summary output), each line is
cut to 200 characters, and then it is HTML-escaped. At most 50 commit
subjects are read. Every message and every edit is sent with link previews
off.

The message must fit one Telegram message (4096 characters). pullgate cuts
it to 3800 characters, counted on the escaped text in UTF-16 units: the head
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@ root applies it, with a health check and a rollback or a hold.
- **The gate lives on the host.** What runs, who may approve and which paths
get a warning come from `/etc/pullgate`, never from the repo. A commit
cannot change the gate.
- **One exact commit.** The question shows the full SHA. Apply applies only
that SHA, even when a newer commit arrives in between.
- **One exact commit.** The question shows a short SHA at the top and the
full SHA once, on its last line. Apply applies only that full SHA, even
when a newer commit arrives in between.
- **No code from the new commit runs before Apply.** Optional `check` and
`summary` commands read the commit as data, as an unprivileged user.
- **Only the listener holds the bot token.** It runs as its own user and
Expand Down
16 changes: 16 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,22 @@ or during the review.
- **Commit subjects and summary output.** The same cleaning; HTML-escaped,
each line capped. The head of the question (host, instance, SHA, the
warnings) always comes first, before any text from the commit.
- **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 `#tag` or a `/command` into 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 status` shows the full applied SHA.
- **Symlinks.** They are written as symlinks and never followed by
pullgate. The tree is written with `O_NOFOLLOW|O_EXCL` into directories
that pullgate made itself, so a symlink cannot make pullgate write
Expand Down
4 changes: 3 additions & 1 deletion internal/gate/apply.go
Original file line number Diff line number Diff line change
Expand Up @@ -318,4 +318,6 @@ func (e *Env) afterApply(st *state.State) {
st.Questions = keep
}

func esc(err error) string { return message.Esc(err.Error()) }
// esc shows an error in a message, in <code>: it may hold text from the
// repo (DESIGN.md section 12).
func esc(err error) string { return message.Code(err.Error()) }
3 changes: 2 additions & 1 deletion internal/gate/check_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import (
"testing"
"time"

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

Expand Down Expand Up @@ -52,7 +53,7 @@ func TestCheckRequestStartsANormalRun(t *testing.T) {
if r := f.run(); r != Nothing {
t.Fatalf("run: %s", r)
}
if !contains(f.outbox(), "No new commit. The applied commit is <code>"+f.state().Applied+"</code>") {
if !contains(f.outbox(), "No new commit. The applied commit is <code>"+message.Short(f.state().Applied)+"</code>") {
t.Fatal("the reply must name the applied SHA")
}
}
Expand Down
13 changes: 7 additions & 6 deletions internal/gate/gate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
"testing"
"time"

"github.com/code6x/pullgate/internal/message"
"github.com/code6x/pullgate/internal/spool"
"github.com/code6x/pullgate/internal/state"
)
Expand Down Expand Up @@ -39,7 +40,7 @@ func TestFirstRunAsksWithAllFilesThenApplies(t *testing.T) {
if f.read("live") != "one" || f.state().Applied != sha {
t.Fatalf("not applied: live %q, state %q", f.read("live"), f.state().Applied)
}
if !contains(f.outbox(), "✅ Applied <code>"+sha) {
if !contains(f.outbox(), "✅ Applied <code>"+message.Short(sha)+"</code>") {
t.Error("no report")
}
// The next run has nothing to do.
Expand All @@ -56,7 +57,7 @@ func TestSecondCommitGetsOldTreeAndForwardOnly(t *testing.T) {
t.Fatalf("run: %s", r)
}
q := f.ask()
if !strings.Contains(q.Text, "Since <code>"+a+"</code>") || !strings.Contains(q.Text, "old value one") || !strings.Contains(q.Text, "• second") {
if !strings.Contains(q.Text, "Since <code>"+message.Short(a)+"</code>") || !strings.Contains(q.Text, "old value one") || !strings.Contains(q.Text, "• <code>second</code>") {
t.Fatalf("the question must show the old tree and the commits:\n%s", q.Text)
}
f.tap(q.Code, "apply")
Expand All @@ -76,7 +77,7 @@ func TestSecondCommitGetsOldTreeAndForwardOnly(t *testing.T) {
t.Fatalf("an older commit must be refused, got %s", r)
}
ms := f.outbox()
if !contains(ms, "Refused <code>"+a) || contains(ms, "Apply this commit?") {
if !contains(ms, "Refused <code>"+message.Short(a)+"</code>") || contains(ms, a) || contains(ms, "Apply this commit?") {
t.Fatal("a refusal sends a notice and no question")
}
// It is not offered again.
Expand Down Expand Up @@ -155,7 +156,7 @@ func TestTapOnSupersededQuestionAppliesOldSHA(t *testing.T) {
t.Fatalf("run: %s", r)
}
q := f.ask()
if !strings.Contains(q.Text, "<code>"+b+"</code>") || !strings.Contains(q.Text, "Since <code>"+a) {
if !strings.Contains(q.Text, "<code>"+message.Short(b)+"</code>") || !strings.Contains(q.Text, "Since <code>"+message.Short(a)+"</code>") {
t.Fatalf("the new question is wrong:\n%s", q.Text)
}
}
Expand Down Expand Up @@ -506,7 +507,7 @@ func TestFailingApplyRollsBack(t *testing.T) {
if !strings.Contains(f.read("log"), "apply "+a+" old="+b+" rb=1 failed="+b) {
t.Fatalf("the rollback env is wrong:\n%s", f.read("log"))
}
if !contains(f.outbox(), "Rolled back to <code>"+a) {
if !contains(f.outbox(), "Rolled back to <code>"+message.Short(a)+"</code>") {
t.Fatal("no report")
}
// max_failed_tries = 1: not asked again.
Expand Down Expand Up @@ -588,7 +589,7 @@ func TestOnFailurePauseHoldsAndAsksNewer(t *testing.T) {
t.Fatalf("a newer commit is asked: %s", r)
}
q := f.ask()
if !strings.Contains(q.Text, "⚠ The last apply (<code>"+b+"</code>) failed.") {
if !strings.Contains(q.Text, "⚠ The last apply (<code>"+message.Short(b)+"</code>) failed.") {
t.Fatalf("the warning is missing:\n%s", q.Text)
}
f.tap(q.Code, "apply")
Expand Down
150 changes: 150 additions & 0 deletions internal/gate/repotext_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
package gate

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

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

var codeOrPre = regexp.MustCompile(`(?s)<code>.*?</code>|<pre>.*?</pre>`)

// repoMarkers are parts of the hostile values below. None may be seen
// outside <code> and <pre> in any message (code6x/pullgate#29).
var repoMarkers = []string{"README.md", "example.com", "example.org", "a href", "@username", "#tag", "/command"}

const hostileLine = `README.md login.example.com https://example.com/x docs.example.org/setup <a href="https://example.com">Apply</a> @username #tag /command`

func checkRepoText(t *testing.T, ms []spool.Message) {
t.Helper()
for _, m := range ms {
if message.Len(m.Text) > 4096 {
t.Errorf("%s message too long: %d", m.Kind, message.Len(m.Text))
}
out := codeOrPre.ReplaceAllString(m.Text, "")
for _, k := range repoMarkers {
if strings.Contains(out, k) {
t.Errorf("%s message holds %q outside <code>/<pre>:\n%s", m.Kind, k, m.Text)
}
}
}
}

// TestHostileCommitTextIsOnlyCode runs a commit with hostile file names, a
// hostile subject and hostile command output through a failed check, a
// question, and a failed apply, and checks every message.
func TestHostileCommitTextIsOnlyCode(t *testing.T) {
f := newFixture(t, ``, "")
files := map[string]string{"README.md": "x", "login.example.com": "x", "policy/@username.toml": "x", "#tag": "x"}
// 1. A check that fails with hostile output.
f.script("check.sh", "echo '"+hostileLine+"'\necho '"+hostileLine+"' >&2\nexit 1\n")
f.commit("first "+hostileLine, "one", files)
if r := f.run(); r != CheckFailed {
t.Fatalf("run: %s", r)
}
ms := f.outbox()
if !contains(ms, "<pre>README.md login.example.com") {
t.Fatalf("the notice must show the check output: %+v", ms)
}
checkRepoText(t, ms)
// 2. A question with a hostile summary.
f.script("check.sh", "true\n")
f.script("summary.sh", "echo '"+hostileLine+"'\n")
f.commit("second "+hostileLine, "two", map[string]string{"fail-apply": "x", "docs.example.org": "x"})
if r := f.run(); r != Asked {
t.Fatalf("run: %s", r)
}
ms = f.outbox()
checkRepoText(t, ms)
var q spool.Message
for _, m := range ms {
if m.Kind == spool.KindAsk {
q = m
}
}
for _, want := range []string{"<code>README.md</code>", "<code>login.example.com</code>", "<code>second " + strings.ReplaceAll(strings.ReplaceAll(hostileLine, "<", "&lt;"), ">", "&gt;")[:60]} {
if !strings.Contains(q.Text, want) {
t.Errorf("missing %q in the question:\n%s", want, q.Text)
}
}
// 3. A failed apply whose command prints hostile text.
f.script("apply.sh", "echo '"+hostileLine+"'\necho '"+hostileLine+"' >&2\nexit 2\n")
f.tap(q.Code, "apply")
if r := f.apply(); r != Held {
t.Fatalf("apply: %s", r)
}
ms = f.outbox()
if !contains(ms, "failed") {
t.Fatalf("no failure report: %+v", ms)
}
checkRepoText(t, ms)
}

// TestHostileSymlinkRefusalIsOnlyCode: the refused notice names a path
// from the commit; it is inside <code> too.
func TestHostileSymlinkRefusalIsOnlyCode(t *testing.T) {
f := newFixture(t, ``, "[limits]\nrefuse_symlinks = true\n")
name := "login.example.com @username #tag"
if err := os.Symlink("../../x", filepath.Join(f.r.Work, name)); err != nil {
t.Fatal(err)
}
f.commit("link", "one", nil)
if r := f.run(); r != CheckFailed {
t.Fatalf("run: %s", r)
}
ms := f.outbox()
if !contains(ms, "login.example.com") {
t.Fatalf("the notice must name the path: %+v", ms)
}
checkRepoText(t, ms)
}

// TestGateBuildsNoRepoTextItself: the gate code makes no HTML from text by
// itself; it uses message.Code, message.SHA and message.Output, which put
// the text in <code> or <pre> (code6x/pullgate#29).
func TestGateBuildsNoRepoTextItself(t *testing.T) {
names, err := filepath.Glob("*.go")
if err != nil {
t.Fatal(err)
}
for _, n := range names {
if strings.HasSuffix(n, "_test.go") {
continue
}
b, err := os.ReadFile(n)
if err != nil {
t.Fatal(err)
}
// The listener's own messages hold only instance names from its
// config, never repo text; root's messages are built here.
for _, bad := range []string{"html.EscapeString", "<pre>", "\"<code>\"", "\"<code>\" +", "Sprintf(\"<code>"} {
if strings.Contains(string(b), bad) {
t.Errorf("%s uses %q: put repo text in a message only with message.Code, message.SHA or message.Output", n, bad)
}
}
}
}

// TestNoticesShowShortSHAs: notices and replies show 12 characters of a
// SHA, and an apply still installs the full SHA (code6x/pullgate#30).
func TestNoticesShowShortSHAs(t *testing.T) {
f := newFixture(t, ``, "")
a := f.commit("first", "one", nil)
f.run()
q := f.ask()
if strings.Count(q.Text, a) != 1 || !strings.Contains(q.Text, "\nFull: <code>"+a+"</code>") {
t.Fatalf("the question shows the full SHA once:\n%s", q.Text)
}
f.tap(q.Code, "apply")
if r := f.apply(); r != Applied || f.state().Applied != a || !strings.Contains(f.read("log"), "apply "+a) {
t.Fatalf("the apply must use the full SHA: %s %q", r, f.read("log"))
}
ms := f.outbox()
if contains(ms, a) || !contains(ms, "<code>"+message.Short(a)+"</code>") {
t.Fatalf("the report must show only the short SHA: %+v", ms)
}
}
Loading
Loading