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
52 changes: 43 additions & 9 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,8 @@ max_files = 100000 # default 100000 files in one tree
max_tree_bytes = 1073741824 # default 1 GiB in one tree
allow_older = false # default false (rule 5)
refuse_symlinks = false # default false; true refuses a commit with a symlink that points out of the tree
settle = "30m" # default 0 (ask at once); ask only when the tip has not changed for this long, at most 168h
reask_after = "24h" # default 0 (never); ask a skipped or expired tip once more after this time (ask mode)

[listener]
user = "pullgate" # the user of the listener; owns the inbox
Expand Down Expand Up @@ -315,10 +317,30 @@ used again.
("the branch is back to the applied commit").
- tip = the SHA of the open question: nothing to do.
- tip is the held SHA, or was asked before and the question expired or
was skipped, or its check failed, or it was refused, or it failed
`max_failed_tries` times: nothing to do. `pullgate status NAME
--ask-again` clears this mark, and also closes an open question for
the tip (section 13).
was skipped, or its check failed, or it was refused, or its check
said "nothing to apply" (step 7), or it failed `max_failed_tries`
times: nothing to do. `pullgate status NAME --ask-again` clears this
mark, and also closes an open question for the tip (section 13).
- **`reask_after`** (default 0, off): in `ask` mode, a tip marked
skipped or expired is asked
once more when its mark is at least `reask_after` old and it is still
the tip. Asking sets the mark to asked; a second Skip or expiry sets
a new mark time, so the next ask comes only after the next wait. It
counts against `questions_per_day` like every question. `auto` mode
has no Skip, so `reask_after` does nothing there.
- **`settle`** (default 0, off): root keeps in its state the time it
first saw the tip (`tip_since`). A new tip, or a clock that went back
before that time, starts it again. While the tip is younger than
`settle`, the run logs "settling" and stops: no check, no question,
no notice. So three merges in ten minutes give one question, for the
last one, and a writer cannot keep moving the branch to make the
owner tap without reading. It also holds in `auto` mode. The time is
root's own: the commit date is written by the writer and is not
trusted. An open question for an older tip stays open while the new
tip settles: it is closed only when the new tip is asked (step 9), as
today while the new tip is checked. A state file from a version
before `settle` has no `tip_since`; the first run sets it to now, so
the tip it knew waits one settle time (fail closed).
- tip is not a descendant of the applied SHA (an older commit, a force
push, a rewritten branch) and `allow_older` is false: refuse. Send one
notice for this SHA and mark it refused. When `allow_older` is true,
Expand All @@ -328,7 +350,15 @@ used again.
send one notice per day, and do not ask.
6. Export the tree of the tip, and the tree of the applied SHA
(`PULLGATE_OLD_TREE`).
7. Run `check` as `check_user` (section 11). If it fails, mark the SHA
7. Run `check` as `check_user` (section 11). If it exits with status
**3**, the commit has nothing to apply on this host (for example only
docs, or files for other hosts): mark the SHA `nothing`, send no
message, and do not ask. The applied SHA stays as it is, so the next
question still lists every commit since the last real apply, and its
check and summary still compare with the last applied tree. In the
broken state (section 10) exit 3 is a failed check with its notice,
so the owner sees that a fix forward was not asked. Any other
non-zero status, a timeout or a signal is a failed check. If it fails, mark the SHA
"check failed", send a notice with the end of its output, and do not
ask. The same SHA is not checked again. In that output the tree paths
(`PULLGATE_TREE`, `PULLGATE_OLD_TREE`) become `NEW` and `OLD`. The
Expand Down Expand Up @@ -684,7 +714,9 @@ Their working directory is `PULLGATE_TREE`. Their umask is 022. Each has a timeo
(`check_timeout`, `apply_timeout`); on timeout the whole process group is
killed and the command counts as failed. pullgate keeps at most 64 KiB of
their output. The output of `apply` and `health` goes to the journal; the
report shows only the exit status. The output of `check` (its last lines)
report shows only the exit status. `check` exits 0 to pass, 3 for
"nothing to apply on this host" (section 7, step 7), and anything else to
fail. The output of `check` (its last lines)
and of `summary` goes into Telegram messages, after the cleaning of
section 12.

Expand Down Expand Up @@ -775,11 +807,13 @@ closed after a cut.
- `off`: `pullgate run` and `pullgate apply` do nothing.

`pullgate status NAME` prints the mode, the applied SHA, the open question,
the held SHA, the broken state ("broken since …, last error …"), the pause
file and an apply in progress. Flags:
the held SHA, the mark of the last tip (`nothing` reads "nothing (the check
found nothing to apply on this host)"), "settling until …" while the tip
waits for `settle`, the broken state ("broken since …, last error …"), the
pause file and an apply in progress. Flags:

- `--ask-again`: clear the marks of the last fetched tip (expired, skipped,
check failed, refused, failed, held), so the next run asks again. If a
check failed, nothing, refused, failed, held), so the next run asks again. If a
question for the tip is open (for example its message was lost), root
removes it from its state, then asks the listener to close its message.
The next run asks again with a new question ID and a new code. An
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,8 @@ deploy_key = "/etc/pullgate/NAME.key"
known_hosts = "/etc/pullgate/NAME.known_hosts"

[commands]
check = ["/path/to/check"] # optional; runs as check_user; a failure means no question
check = ["/path/to/check"] # optional; runs as check_user; a failure means no question;
# exit 3 means "nothing to apply on this host": no question, no message
summary = ["/path/to/summary"] # optional; runs as check_user; its output is in the question
apply = ["/path/to/apply"] # required; runs as root after Apply
health = ["/path/to/health"] # optional; runs as root after apply
Expand All @@ -296,6 +297,8 @@ questions_per_day = 10
approval_ttl = "12h"
max_failed_tries = 1
allow_older = false
settle = "0" # e.g. "30m": ask only when the branch has not changed for this long
reask_after = "0" # e.g. "24h": ask a skipped or expired commit once more after this time
```

The commands get these environment variables: `PULLGATE_SHA`,
Expand Down
24 changes: 23 additions & 1 deletion THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,11 @@ A clock that goes back before `asked` denies. A clock that jumps forward
expires questions early: this denies too. The listener checks expiry with its
own clock as well. Timeouts of commands use the monotonic clock.

`settle` counts from the time root first saw the tip; a clock that goes
back before that time starts the wait again. A clock that is wrong and then
corrected forward can make the wait shorter, like `approval_ttl` above.
That only asks sooner; it never applies anything.

*Left.* A clock that is set far back while a question is open can keep that
question valid longer than `approval_ttl`. The code still works only once.

Expand Down Expand Up @@ -382,7 +387,24 @@ repo URL must pass the same check as the clone, because root runs
*Attack.* Someone pushes many commits to tire the owner into tapping Apply.

*Defense.* At most one open question per instance; a newer tip replaces it.
`questions_per_day` caps the questions. A SHA is asked once.
`questions_per_day` caps the questions. A SHA is asked once, or once more
per `reask_after` after a Skip or an expiry; each of these counts against
`questions_per_day`. With `settle`, a tip is asked only when root has seen
it unchanged for that long, by root's own clock (not the commit date, which
the writer sets). So a writer who keeps moving the branch gets no question
at all, and the owner always has a question that stays the same while he
reads it.

*Check exit 3.* `check` runs as `check_user` on the commit's tree, so a
hostile commit can make it exit 3. That only marks the SHA `nothing`: no
question, no apply, and the applied SHA stays. It cannot apply anything,
and it is no worse than a check that fails. The next real commit is asked
with every commit since the last real apply, so nothing is hidden from the
owner. Root takes only the exit status; it reads nothing else from the
check.

*Left.* A writer can delay a question by pushing more often than `settle`.
That only delays; it never applies.

### T16. A bad release binary

Expand Down
2 changes: 2 additions & 0 deletions contrib/examples/ansible/playbooks.toml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ paths = ["ansible.cfg", "site.yml", "roles/pullgate/**", "**/sudoers*"]

[limits]
questions_per_day = 10
settle = "30m" # ask only when the branch has not changed for 30 minutes
reask_after = "24h" # ask a skipped or expired commit once more after a day
approval_ttl = "24h"

[listener]
Expand Down
2 changes: 2 additions & 0 deletions contrib/examples/config-file/config-repo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ paths = ["policy.toml"]

[limits]
questions_per_day = 10
settle = "30m" # ask only when the branch has not changed for 30 minutes
reask_after = "24h" # ask a skipped or expired commit once more after a day
approval_ttl = "12h"
max_failed_tries = 1

Expand Down
12 changes: 12 additions & 0 deletions internal/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,12 @@ type Limits struct {
MaxTreeBytes int64 `toml:"max_tree_bytes"`
AllowOlder bool `toml:"allow_older"`
RefuseSymlinks bool `toml:"refuse_symlinks"`
// Settle is how long the tip must stay the same before it is checked
// and asked (DESIGN.md section 7). 0 asks at once.
Settle Duration `toml:"settle"`
// ReaskAfter asks a skipped or expired tip once more when its mark is
// this old (DESIGN.md section 7). 0 never asks again.
ReaskAfter Duration `toml:"reask_after"`
}

// ListenerUser is the [listener] section of an instance.
Expand Down Expand Up @@ -196,6 +202,12 @@ func (c *Instance) validate() error {
if c.Limits.QuestionsPerDay < 0 || c.Limits.MaxFailedTries < 0 || c.Limits.MaxFiles < 0 || c.Limits.MaxTreeBytes < 0 {
return c.errf("[limits]", "a limit is below 0. Fix: use a positive number")
}
if c.Limits.Settle.Duration < 0 || c.Limits.Settle.Duration > MaxTTL {
return c.errf("[limits] settle", "must be at least 0 and at most 168h. Fix: use a time like \"30m\", or \"0\" to ask at once")
}
if c.Limits.ReaskAfter.Duration < 0 {
return c.errf("[limits] reask_after", "is below 0. Fix: use a time like \"24h\", or \"0\" to never ask again")
}
if c.Commands.CheckTimeout.Duration < 0 || c.Commands.ApplyTimeout.Duration < 0 {
return c.errf("[commands]", "a timeout is below 0")
}
Expand Down
15 changes: 14 additions & 1 deletion internal/config/config_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ func TestDefaults(t *testing.T) {
t.Fatal(err)
}
if c.Mode != "ask" || c.OnFailure != "pause" || c.Limits.QuestionsPerDay != 10 || c.Limits.MaxFailedTries != 1 ||
c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Commands.CheckUser != "pullgate-check" {
c.Limits.ApprovalTTL.Hours() != 12 || c.Limits.AllowOlder || c.Limits.Settle.Duration != 0 || c.Limits.ReaskAfter.Duration != 0 || c.Commands.CheckUser != "pullgate-check" {
t.Fatalf("defaults: %+v", c)
}
}
Expand All @@ -61,6 +61,9 @@ func TestRefused(t *testing.T) {
"url as option": strings.Replace(good, "ssh://git@git.example.com/owner/config-repo.git", "--upload-pack=x", 1),
"branch option": good + "[repo]\n",
"ttl too long": good + "[limits]\napproval_ttl = \"200h\"\n",
"settle too long": good + "[limits]\nsettle = \"200h\"\n",
"settle below 0": good + "[limits]\nsettle = \"-1m\"\n",
"reask below 0": good + "[limits]\nreask_after = \"-1h\"\n",
"absolute watch path": good + "[watch]\npaths = [\"/etc/x\"]\n",
"host html": `host = "<b>"` + good,
}
Expand Down Expand Up @@ -245,3 +248,13 @@ func TestCheckAPIURL(t *testing.T) {
}
}
}

func TestSettleAndReask(t *testing.T) {
c, err := Load(write(t, good+"[limits]\nsettle = \"30m\"\nreask_after = \"24h\"\n", 0o600), "x", uid())
if err != nil {
t.Fatal(err)
}
if c.Limits.Settle.Minutes() != 30 || c.Limits.ReaskAfter.Hours() != 24 {
t.Fatalf("settle %s, reask_after %s", c.Limits.Settle.Duration, c.Limits.ReaskAfter.Duration)
}
}
2 changes: 1 addition & 1 deletion internal/gate/apply.go
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ func (e *Env) handle(ctx context.Context, st *state.State, a spool.Approval) (Re
if a.Action == "skip" {
st.SetMark(q.SHA, state.MarkSkipped, now)
e.Log.Info("skipped", "sha", q.SHA)
e.reply(q.ID, "Skipped "+code(q.SHA)+". A new commit asks again.")
e.reply(q.ID, "Skipped "+code(q.SHA)+". "+e.skipHint())
return Skipped, false, e.Dir.Save(st)
}
r, err := e.applySHA(ctx, st, q)
Expand Down
Loading