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
66 changes: 66 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -1060,3 +1060,69 @@ download that stops in the middle runs nothing. The steps:
A trap removes the temporary directory and a new file that was not renamed
yet, at every exit. A failure exits with 1, and its last line says that
nothing was installed. What the script trusts: THREAT-MODEL.md, T17.

## 17. Bootstrap (`pullgate bootstrap`)

`pullgate bootstrap` sets up a new host, as root, after the binary is
installed and the users, the directories and the units are in place
(README "Install"). Its goal: nobody types or pastes the owner ID or the
chat ID, and the token never shows.

```
pullgate bootstrap [--token-stdin] [--api-url URL]
--instance NAME --repo URL [--branch B] [--apply PROGRAM] [--known-hosts FILE]
[--instance NAME2 ...]
```

It must run as root, and `/etc/pullgate` and its parents must be safe
(rule 6). `--api-url` takes only `https://api.telegram.org` or a test
server on `http://127.0.0.1:PORT` (no user info): another server would see
the token and could plant the IDs. A test server gets a loud warning.
`listener.toml` lists only the instances of this run: give every instance
of the host in each run.

1. **Checks first.** Every instance name, URL and branch is checked, and
an ssh URL to a host other than `github.com` needs `--known-hosts`. A
new instance (no `NAME.toml`) needs `--apply`. Nothing is asked or
written before these pass.
2. **The token.** It runs `systemd-ask-password` (no echo, not in the
shell history, not an argument), or with `--token-stdin` reads the
first line of stdin. It must look like a bot token. `getMe` checks it.
The token is never printed, never in an error, never an argument, and
never in the environment of a program that bootstrap starts: each one
gets only `PATH` and `LC_ALL`.
3. **Pairing.** It makes a one-time code of 8 random digits, valid for 10
minutes, and prints it on the console. It skips the updates that came
before the code. It reads messages with `getUpdates`. A message that is
not a number (for example `/start`) is skipped. Any other number is a
wrong code; at 5 wrong codes it stops. The right code (compared in
constant time) counts only from a **private** chat with a person: chat
type `private`, the sender is not a bot, and the sender ID is the chat
ID. The right code from a group or a channel stops it: the code is used
up. Then it writes `bot-token` (root, 0600) and `listener.toml` (root,
group of the listener, 0640; written first) with `owner_id` and `chat_id` from that
message, replacing any file that was there. A wrong code, a group, a
timeout or an error writes nothing; an old `listener.toml` stays, and
bootstrap says that it did not write it. It confirms the updates, so
the listener does not see the code, and sends "paired" to the chat.
There is no flag, config key or variable that sets these IDs.
4. **Each instance.** For an ssh URL: it makes `NAME.key` with `ssh-keygen
-t ed25519` (an existing key is kept only if it is a regular file of
root; a `.pub` without a key is refused), sets it to 0600, and prints the
public key with "add it as a read-only deploy key". It writes
`NAME.known_hosts` from the `github.com` ed25519 key that the binary
carries, or from `--known-hosts FILE`, and prints the SHA256 fingerprint
of each key, to compare with what the git host publishes. A local URL
needs neither. If `NAME.toml` does not exist, it writes a minimal one:
`mode = "ask"`, `on_failure = "pause"`, the repo, the key, the known
hosts, `apply` and `check_user = "pullgate-check-NAME"`. An existing
`NAME.toml` is kept, with its own repo, key and known hosts: then no
key or known hosts file is made, and the probe uses the config. Then it runs `git ls-remote` (section 6: the same git
flags and ssh options) every 10 seconds, for at most 30 minutes, until
the branch can be read.
5. It does not run `pullgate doctor` or enable the units yet (code6x/pullgate#28).

**pullgate's own files.** `listener.toml`, `bot-token`, `NAME.key`,
`NAME.known_hosts` and the instance `mode` belong to pullgate. A later
config tool, for example Ansible run by an instance, must not write them.
`listener.toml` says so in its first lines.
56 changes: 43 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,19 +99,49 @@ install -d -m 0711 /var/lib/pullgate
cp contrib/systemd/* /etc/systemd/system/
```

1. Make a Telegram bot with BotFather. Put its token in
`/etc/pullgate/bot-token` (owner root, mode 0600).
2. Find your Telegram user ID and the chat ID of your private chat with the
bot. Write `/etc/pullgate/listener.toml` from
[contrib/examples/listener.toml](contrib/examples/listener.toml).
3. Make a **read-only** deploy key for the repo:
`ssh-keygen -t ed25519 -N '' -f /etc/pullgate/NAME.key`. Add the public key
to the repo as a read-only deploy key.
4. Pin the host key of the git server in `/etc/pullgate/NAME.known_hosts`.
Check the fingerprint against the one your git host publishes.
5. Write `/etc/pullgate/NAME.toml` (owner root, mode 0600). Start from one of
the examples below.
6. Start it:
Then set it up with **`pullgate bootstrap`**, as root, on a console of
the host:

```sh
pullgate bootstrap --instance config-repo --repo git@github.com:example/config-repo.git \
--apply /usr/local/lib/config-repo/apply.sh
```

1. Make a Telegram bot with BotFather first. Bootstrap asks for its token
with `systemd-ask-password`: it does not show the token, does not keep
it in the shell history, and does not take it as an argument. It checks
the token with Telegram, and stores it as `/etc/pullgate/bot-token`
(owner root, mode 0600). For automation, `--token-stdin` reads it from
the first line of stdin instead.
2. **Pairing.** Bootstrap prints a one-time code of 8 digits, valid for 10
minutes. Send it to the bot, in your **private** chat with it.
Bootstrap takes your user ID and the chat ID from that message, and
writes `/etc/pullgate/listener.toml`. Nobody types or pastes an ID, so
a script that someone else wrote cannot plant one. A wrong code (5 of
them stop it), a group chat or a timeout writes nothing. Stop
`pullgate-listen.service` while bootstrap runs, if it is running.
3. For each `--instance NAME --repo URL` (and `--branch`, default `main`):
it makes the deploy key on the host (`/etc/pullgate/NAME.key`; the
private key never leaves the host) and prints the public key. Add it
to the repo as a **read-only** deploy key. It pins the host key of the
git server in `/etc/pullgate/NAME.known_hosts`: for `github.com` from
the key that pullgate carries, with its fingerprint, to compare with the
one GitHub publishes; for another git host from `--known-hosts FILE`
(make it with `ssh-keyscan`, and compare the fingerprints). If
`/etc/pullgate/NAME.toml` does not exist, it writes a minimal one with
`--apply PROGRAM` (owner root, mode 0600); add `check`, `health` and
`watch` as the examples below show. Then it waits until `git ls-remote`
can read the branch.
4. Bootstrap does not enable the units yet. Do it as below.

Each run writes `listener.toml` with the instances of that run only: give
every instance of the host each time.

`listener.toml`, the token, the deploy key and the known hosts file are
pullgate's own files: no other config tool (for example Ansible, run by
an instance) may write them.

Start it:

<!-- install-test:start -->
```sh
Expand Down
37 changes: 37 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -563,6 +563,43 @@ instance named `pullgate` has its own directories (`TestUpdateQuestionsAreTheirO
ship a binary that passes (T16); the owner's tap is the last check. A
build from the source (`pullgate dev`) does not update itself.

### T21. Setup: a planted owner ID, the token entry, the pairing code

*Attack.* The person who sets up a host pastes a script that someone else
wrote. The script writes its own `owner_id` into `listener.toml`, and so
gets the bot and every Apply. Or the token leaks: into the shell history,
a process list, a log, or the environment of a child program. Or someone
else sends the pairing code first, or guesses it.

*Defense.* `pullgate bootstrap` (DESIGN.md section 17):

- The IDs come only from the Telegram message that carries the one-time
code. No flag, config key or variable sets them; a planted
`listener.toml` is replaced at the pairing. Bootstrap refuses unknown
options, such as `--owner-id`. `--api-url` takes only the real Bot API
or a test server on `127.0.0.1`: a pasted script cannot send the
pairing through a server that changes the sender ID. The listener's
`api_url` is parsed the same way, so `http://127.0.0.1:80@host` is
refused.
- The code is 8 random digits, valid for 10 minutes, printed only on the
console of the host. 5 wrong codes stop the pairing, so a guess works
with a chance of 5 in 100 million. The right code counts only from a
private chat with a person; from a group it stops the pairing, because
others saw it. A wrong code, a group or a timeout writes nothing.
- The token is read with `systemd-ask-password` (no echo, no history, no
argument) or from stdin. It is checked with `getMe`, stored with mode
0600, and never printed. Programs that bootstrap starts get only `PATH`
and `LC_ALL`.
- The deploy key is made on the host; only the public key is printed. The
host key of `github.com` comes from the binary, with its fingerprint
shown; another git host needs a file that the owner checked.

*Left.* Someone who sees the console of the host during the pairing can
send the code first. Check the chat: bootstrap sends "paired" to the chat
that won. A pasted script can still do anything else as root; bootstrap
only takes away the quiet way to plant the owner ID. If the failed run
leaves an old `listener.toml`, bootstrap says that it did not write it.

## 6. Out of scope

- An attacker who is root on the host.
Expand Down
23 changes: 22 additions & 1 deletion cmd/pullgate/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import (
"time"

"github.com/code6x/pullgate"
"github.com/code6x/pullgate/internal/bootstrap"
"github.com/code6x/pullgate/internal/config"
"github.com/code6x/pullgate/internal/gate"
"github.com/code6x/pullgate/internal/listener"
Expand All @@ -43,6 +44,11 @@ commands:
update [--config FILE] look for a new release of pullgate, and install
one after a tap (pullgate-update.service runs it, as root)
units print the units this binary carries, as JSON
bootstrap [--token-stdin] --instance NAME --repo URL [--branch B]
[--apply PROGRAM] [--known-hosts FILE] [--instance ...]
set up a new host, as root: the bot token (with no echo),
the pairing with the owner's chat by a one-time code, the
deploy key and the host key of each instance
version`

func main() {
Expand Down Expand Up @@ -77,7 +83,7 @@ func run(args []string, stdout, stderr io.Writer) int {
}
rest := fs.Args()
if len(rest) == 0 {
return usageErr(stderr, "give a command: run, apply, status, listen, update, units or version")
return usageErr(stderr, "give a command: run, apply, status, listen, update, units, bootstrap or version")
}
log := slog.New(slog.NewTextHandler(stderr, nil))
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
Expand Down Expand Up @@ -129,6 +135,21 @@ func run(args []string, stdout, stderr io.Writer) int {
}
return 0
}
case "bootstrap":
o, err := bootstrap.Parse(rest[1:])
if err != nil {
return usageErr(stderr, err.Error())
}
o.EtcDir, o.Out, o.Err = *configDir, stdout, stderr
if euid != 0 {
log.Error("bootstrap", "err", "it must run as root. Fix: run it with sudo, or as root")
return 1
}
if err := bootstrap.Run(ctx, o); err != nil {
log.Error("bootstrap", "err", err)
return 1
}
return 0
case "listen":
lf := flag.NewFlagSet("listen", flag.ContinueOnError)
lf.SetOutput(io.Discard)
Expand Down
Loading
Loading