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
24 changes: 22 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -105,13 +105,33 @@ jobs:
exit 1
fi

units-first-run:
name: first run under the units
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
- name: Build
run: CGO_ENABLED=0 go build -trimpath -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate
- name: The first run and the listener under the real units
# A fresh install with contrib/systemd/ and no drop-in: pullgate run
# under pullgate-run@.service, then pullgate listen under
# pullgate-listen.service against a fake Telegram. A unit setting
# that breaks a run fails here (issue #19).
run: sudo sh test/units/first-run.sh "${RUNNER_TEMP}/pullgate"

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: shellcheck install.sh
- name: shellcheck install.sh and test/units/first-run.sh
# A fixed release of ShellCheck, checked by its SHA-256. Dependabot
# does not update it. Update it by hand: the version and the SHA-256
# of shellcheck-VERSION.linux.x86_64.tar.xz together.
Expand All @@ -127,7 +147,7 @@ jobs:
echo "${SHELLCHECK_SHA256} $dir/shellcheck.tar.xz" | sha256sum --strict -c -
tar -xJf "$dir/shellcheck.tar.xz" -C "$dir"
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh test/units/first-run.sh
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
Expand Down
28 changes: 27 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,8 @@ can be less strict; each example sets what its `apply` needs.
| `/var/lib/pullgate/NAME/auto-approval` | root, 0600 | the approval that `auto` mode writes (section 13) |
| `/var/lib/pullgate/NAME/trees/` | root, 0711 | the trees of one process (section 6) |
| `/var/spool/pullgate/` and `/var/spool/pullgate/NAME/` | root, 0755 | the spool |
| `/var/spool/pullgate/NAME/outbox` | root, group listener, 0770 | messages from root to the listener |
| `/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/lib/pullgate-listener/state.json` | listener, 0600 | the listener's open questions |
Expand Down Expand Up @@ -132,6 +133,22 @@ in the same directory. `/var/spool/pullgate` and `NAME/` are owned by root
and pass the check of section 6, so the listener cannot swap `outbox`,
`inbox` or `check` for a symlink.

**No setgid bit on the outbox.** Root gives each outbox file the group of
the listener user itself: it creates the file, then calls `fchown` on the
open file (group only) and `fchmod` to 0640, all before the rename. So the
listener never sees an outbox file with another group, and no directory
needs the setgid bit. This matters because `pullgate-run@.service` sets
`RestrictSUIDSGID=yes`, which refuses every `chmod` that sets a setuid or
setgid bit. Version 0.1.0 made the outbox `2770`, and its first run failed
under the unit (issue #19). The other choice was to remove
`RestrictSUIDSGID=yes` from the run unit. We keep it: the run unit runs as
root with `CAP_FOWNER`, and it must never make a setuid or setgid file.
`Ensure` also takes the setgid bit off an outbox made by 0.1.0. Removing a
bit is allowed under `RestrictSUIDSGID=yes`. Because root is not in the
listener's group, the `fchown` needs `CAP_CHOWN`: every unit that runs
`pullgate run` or `pullgate apply` must keep it. Without it, root cannot
write to the outbox, and the owner gets no question and no reply.

## 5. The instance config

```toml
Expand Down Expand Up @@ -673,6 +690,15 @@ and `pullgate`. They never use the network. They show that the script
installs nothing when a check fails (section 16), and that it installs when
all checks pass. CI also runs a pinned ShellCheck on the script.

`test/units/first-run.sh` runs on CI as root, on the throwaway runner. It
installs the binary and the units of `contrib/systemd/` as the README
says, with no drop-in. It runs the first `pullgate run` under the real
`pullgate-run@.service`, checks the owners and modes of section 4, then
runs `pullgate listen` under the real `pullgate-listen.service` against a
fake Telegram on `127.0.0.1`, and checks that the listener sent the
question and removed it from the outbox. So a unit setting that breaks a
run or the listener fails CI.

## 15. Not in version 0.1

- Self-update of pullgate. `install.sh` updates it only when root runs
Expand Down
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,22 @@ The run unit sets `MemoryDenyWriteExecute=yes`, which also holds for
`check` and `summary`. A command that needs a JIT (for example Node.js) does
not work there.

### Update from 0.1.0

In 0.1.0 the first `pullgate run` failed under `pullgate-run@.service`
with `chmod .../outbox: operation not permitted` (issue #19). A host may
have a drop-in with `RestrictSUIDSGID=no` for the run unit as a
workaround. Newer versions do not need it. After you update the binary:

1. Find the drop-in: `systemctl cat pullgate-run@NAME.service` shows each
file and its path. It is in `/etc/systemd/system/pullgate-run@.service.d/`
or in `/etc/systemd/system/pullgate-run@NAME.service.d/`.
2. Remove the line `RestrictSUIDSGID=no`, or the whole file when that is
all it holds.
3. Run `systemctl daemon-reload`.

The next run takes the setgid bit off the outbox by itself.

## Development

```sh
Expand Down
5 changes: 4 additions & 1 deletion THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,10 @@ 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.
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
Expand Down
4 changes: 3 additions & 1 deletion contrib/systemd/pullgate-apply@.service
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# pullgate apply NAME: act on approvals as root (DESIGN.md sections 9, 10).
# It runs the owner's apply and health commands. What they need decides
# how strict this unit can be, so the sandbox here is light. Add more in a
# drop-in for your instance, for example:
# drop-in for your instance. Keep CAP_CHOWN if you set
# CapabilityBoundingSet=: root needs it to give its replies in the outbox
# the listener's group (DESIGN.md section 4). For example:
# systemctl edit pullgate-apply@config-repo.service
# The example configs in contrib/examples say what fits them.
[Unit]
Expand Down
3 changes: 2 additions & 1 deletion contrib/systemd/pullgate-run@.service
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ TimeoutStartSec=30min
KillMode=control-group

# Sandbox. Root needs: CAP_SETUID/CAP_SETGID to run check as check_user,
# CAP_CHOWN/CAP_FOWNER to fix the spool owners, CAP_DAC_OVERRIDE to remove
# CAP_CHOWN/CAP_FOWNER to fix the spool owners and to give each outbox file
# the listener's group (DESIGN.md section 4), CAP_DAC_OVERRIDE to remove
# files in the listener's inbox, CAP_KILL to stop a check that runs too long.
CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_DAC_OVERRIDE CAP_KILL
AmbientCapabilities=
Expand Down
8 changes: 4 additions & 4 deletions internal/gate/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,19 @@ const (
func (e *Env) head() string { return message.Head(e.Cfg.Host, e.Cfg.Name) }

func (e *Env) notice(text string) {
if err := e.Spool.Send(spool.Message{Kind: spool.KindNotice, Text: e.head() + "\n" + text}); err != nil {
if err := e.Spool.Send(e.Owners.ListenerGID, spool.Message{Kind: spool.KindNotice, Text: e.head() + "\n" + text}); err != nil {
e.Log.Error("write a notice to the outbox", "err", err)
}
}

func (e *Env) reply(q int64, text string) {
if err := e.Spool.Send(spool.Message{Kind: spool.KindReply, Question: q, Text: e.head() + "\n" + text}); err != nil {
if err := e.Spool.Send(e.Owners.ListenerGID, spool.Message{Kind: spool.KindReply, Question: q, Text: e.head() + "\n" + text}); err != nil {
e.Log.Error("write a reply to the outbox", "err", err)
}
}

func (e *Env) edit(q int64, text string) {
if err := e.Spool.Send(spool.Message{Kind: spool.KindEdit, Question: q, Text: e.head() + "\n" + text}); err != nil {
if err := e.Spool.Send(e.Owners.ListenerGID, spool.Message{Kind: spool.KindEdit, Question: q, Text: e.head() + "\n" + text}); err != nil {
e.Log.Error("write an edit to the outbox", "err", err)
}
}
Expand Down Expand Up @@ -340,7 +340,7 @@ func (e *Env) decide(ctx context.Context, st *state.State, tip string) (Result,
e.Log.Info("auto mode: apply queued", "sha", tip)
return AutoQueued, nil
}
if err := e.Spool.Send(spool.Message{Kind: spool.KindAsk, Question: nq.ID, Code: c, Expires: nq.Expires, Text: text}); err != nil {
if err := e.Spool.Send(e.Owners.ListenerGID, spool.Message{Kind: spool.KindAsk, Question: nq.ID, Code: c, Expires: nq.Expires, Text: text}); err != nil {
return undo(err)
}
st.AskTimes = append(st.AskTimes, now)
Expand Down
10 changes: 5 additions & 5 deletions internal/listener/listener_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ func newL(t *testing.T) *lfix {
// ask puts a question in the outbox and lets the listener send it.
func (f *lfix) ask(id int64, c string) int64 {
f.t.Helper()
if err := f.d.Send(spool.Message{Kind: spool.KindAsk, Question: id, Code: c, Expires: f.now.Add(time.Hour), Text: "pullgate on <b>example-host</b>\nApply this commit?"}); err != nil {
if err := f.d.Send(os.Getegid(), spool.Message{Kind: spool.KindAsk, Question: id, Code: c, Expires: f.now.Add(time.Hour), Text: "pullgate on <b>example-host</b>\nApply this commit?"}); err != nil {
f.t.Fatal(err)
}
f.l.Outbox(context.Background())
Expand Down Expand Up @@ -131,7 +131,7 @@ func TestTapsThatDoNotCount(t *testing.T) {
f.tap(owner, chat, msg, "a:"+code)
},
"closed question": func(f *lfix, msg int64) {
if err := f.d.Send(spool.Message{Kind: spool.KindEdit, Question: 1, Text: "closed"}); err != nil {
if err := f.d.Send(os.Getegid(), spool.Message{Kind: spool.KindEdit, Question: 1, Text: "closed"}); err != nil {
f.t.Fatal(err)
}
f.l.Outbox(context.Background())
Expand Down Expand Up @@ -159,7 +159,7 @@ func TestTapsThatDoNotCount(t *testing.T) {

func TestExpiredAskIsNotSent(t *testing.T) {
f := newL(t)
if err := f.d.Send(spool.Message{Kind: spool.KindAsk, Question: 1, Code: code, Expires: f.now.Add(-time.Minute), Text: "old"}); err != nil {
if err := f.d.Send(os.Getegid(), spool.Message{Kind: spool.KindAsk, Question: 1, Code: code, Expires: f.now.Add(-time.Minute), Text: "old"}); err != nil {
t.Fatal(err)
}
f.l.Outbox(context.Background())
Expand All @@ -186,8 +186,8 @@ func TestStateSurvivesRestart(t *testing.T) {
func TestReplyAndNotice(t *testing.T) {
f := newL(t)
msg := f.ask(1, code)
_ = f.d.Send(spool.Message{Kind: spool.KindReply, Question: 1, Text: "applied"})
_ = f.d.Send(spool.Message{Kind: spool.KindNotice, Text: "notice"})
_ = f.d.Send(os.Getegid(), spool.Message{Kind: spool.KindReply, Question: 1, Text: "applied"})
_ = f.d.Send(os.Getegid(), spool.Message{Kind: spool.KindNotice, Text: "notice"})
f.l.Outbox(context.Background())
ms := f.tg.Messages()
if len(ms) != 3 || ms[1].ReplyTo != msg || ms[2].Text != "notice" {
Expand Down
29 changes: 20 additions & 9 deletions internal/spool/spool.go
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,9 @@ const MaxCheck = 64
// Ensure makes the spool of the instance with the owners and modes of
// DESIGN.md section 4. Base and Base/NAME belong to root (uid) and must
// pass the check of rule 6; outbox and inbox are fixed through an open
// directory, never through a path.
// directory, never through a path. No directory gets the setgid bit:
// pullgate-run@.service has RestrictSUIDSGID=yes, which refuses a chmod
// that sets it. Send gives each outbox file its group itself.
func (d Dirs) Ensure(uid uint32, o Owners) error {
for _, p := range []string{d.Base, d.inst()} {
if err := os.Mkdir(p, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
Expand All @@ -114,7 +116,7 @@ func (d Dirs) Ensure(uid uint32, o Owners) error {
uid, gid int
mode os.FileMode
}{
{"outbox", int(uid), o.ListenerGID, 0o770 | os.ModeSetgid},
{"outbox", int(uid), o.ListenerGID, 0o770},
{"inbox", o.ListenerUID, o.ListenerGID, 0o700},
{"check", o.ListenerUID, o.ListenerGID, 0o700},
} {
Expand Down Expand Up @@ -150,8 +152,9 @@ func seqName() string {

// writeIn writes data as a new file in dir, through os.Root: a random
// temporary name with O_EXCL|O_NOFOLLOW, then a rename in the same dir to
// final (a new sequence name when final is "").
func writeIn(dir string, data []byte, mode os.FileMode, final string) error {
// final (a new sequence name when final is ""). With gid >= 0 the file gets
// that group before it is renamed, so a reader never sees it with another.
func writeIn(dir string, data []byte, mode os.FileMode, gid int, final string) error {
root, err := os.OpenRoot(dir)
if err != nil {
return fmt.Errorf("open %s: %w", dir, err)
Expand All @@ -163,6 +166,9 @@ func writeIn(dir string, data []byte, mode os.FileMode, final string) error {
return fmt.Errorf("write in %s: %w", dir, err)
}
_, err = f.Write(data)
if err == nil && gid >= 0 {
err = f.Chown(-1, gid)
}
if err == nil {
err = f.Chmod(mode)
}
Expand All @@ -185,13 +191,18 @@ func writeIn(dir string, data []byte, mode os.FileMode, final string) error {
return nil
}

// Send writes a message to the outbox (root).
func (d Dirs) Send(m Message) error {
// Send writes a message to the outbox (root). The file is owned by root,
// with group gid (the group of the listener user, Owners.ListenerGID) and
// mode 0640, so the listener can read it (DESIGN.md section 4).
func (d Dirs) Send(gid int, m Message) error {
if gid < 0 {
return errors.New("write in the outbox: no group for the listener. This is a bug in pullgate")
}
b, err := json.Marshal(m)
if err != nil {
return err
}
return writeIn(d.Outbox(), b, 0o640, "")
return writeIn(d.Outbox(), b, 0o640, gid, "")
}

// WriteApproval writes an approval to the inbox (the listener).
Expand All @@ -200,13 +211,13 @@ func (d Dirs) WriteApproval(a Approval) error {
if err != nil {
return err
}
return writeIn(d.Inbox(), b, 0o600, "")
return writeIn(d.Inbox(), b, 0o600, -1, "")
}

// WriteCheck writes a check request (the listener). It always has the same
// name, so many requests before root reads them are one file.
func (d Dirs) WriteCheck() error {
return writeIn(d.CheckDir(), []byte(CheckContent), 0o600, CheckFile)
return writeIn(d.CheckDir(), []byte(CheckContent), 0o600, -1, CheckFile)
}

// HasCheck reports whether the check directory holds a file whose name
Expand Down
Loading
Loading