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
5 changes: 4 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: shellcheck install.sh
- name: shellcheck install.sh and contrib/pullgate
# 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 @@ -80,6 +80,9 @@ jobs:
tar -xJf "$dir/shellcheck.tar.xz" -C "$dir"
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh
# The scripts of the pullgate recipe source lib.sh from their own
# directory.
(cd contrib/pullgate && "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh -x -- *.sh)
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
Expand Down
12 changes: 11 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,16 @@ jobs:
tar --owner=0 --group=0 --numeric-owner --mode=go-w --mtime="$mtime" \
-C "$stage" -cf - nodkey LICENSE README.md | gzip -9n > "dist/${name}.tar.gz"
done
# The pullgate recipe (contrib/pullgate, docs/setup.md). A host
# installs it from here, checked by SHA256SUMS and the
# attestation as the binaries are, never from a config repo.
name="nodkey_${VERSION}_pullgate"
stage="${RUNNER_TEMP}/${name}"
mkdir -p "$stage"
cp contrib/pullgate/* LICENSE "$stage/"
# LC_ALL=C: the same order of the names on every runner.
(cd "$stage" && export LC_ALL=C && tar --owner=0 --group=0 --numeric-owner --mode=go-w --mtime="$mtime" \
-cf - -- *) | gzip -9n > "dist/${name}.tar.gz"
cd dist
sha256sum -- *.tar.gz > SHA256SUMS
cat SHA256SUMS
Expand Down Expand Up @@ -147,7 +157,7 @@ jobs:
subject-path: dist/*.tar.gz
# The attestation is also a file of the release. With this file,
# gh attestation verify --bundle needs no GitHub login. One bundle
# covers both tarballs.
# covers all tarballs.
- name: Save the attestation bundle
env:
BUNDLE: ${{ steps.attest.outputs.bundle-path }}
Expand Down
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,11 @@ Planned. Each v1 issue adds its part.
`nodkey preapprove` (sections 8 and 15), and `nodkey agent-browser-plugin`
(section 21.10), with recorded requests of agent-browser in
`testdata/`.
- `contrib/pullgate/` - the pullgate recipe: the broker host pulls its
config from git, and the owner taps each change (docs/setup.md,
"Change the config from git with pullgate"; THREAT-MODEL.md T52). Its
tests are in `contrib_pullgate_linux_test.go`, at the root of the
module. The release packs it as `nodkey_VERSION_pullgate.tar.gz`.
- `contrib/systemd/` - the example systemd unit of the broker, with
encrypted credentials and a sandbox (DESIGN.md section 16).
- `docs/` - the guides for people:
Expand Down
40 changes: 36 additions & 4 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4585,10 +4585,42 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`):
(section 15). See docs/releasing.md.
- release-please keeps a release pull request open. Merging it tags the
version and creates the GitHub Release. A job then builds static Linux
binaries (`CGO_ENABLED=0`, amd64 and arm64, `-trimpath`), a
`SHA256SUMS` file, and a build provenance attestation. The attestation
is also a file of the release (`nodkey_<version>.sigstore.json`), so it
can be checked with no GitHub login.
binaries (`CGO_ENABLED=0`, amd64 and arm64, `-trimpath`), the tarball
of the pullgate recipe (`nodkey_<version>_pullgate.tar.gz`: the files
of `contrib/pullgate/` and `LICENSE`), a `SHA256SUMS` file of all
tarballs, and a build provenance attestation of all of them. The
attestation is also a file of the release
(`nodkey_<version>.sigstore.json`), so it can be checked with no GitHub
login.
- The pullgate recipe (`contrib/pullgate/`, issue #102) lets the broker
host pull `broker.toml` and `known_hosts` from a git repo with
pullgate, which asks the owner on its own bot and applies a commit only
after a tap (THREAT-MODEL.md T52). It is four scripts and a shared
`lib.sh`. `check.sh` (check user): both files are plain files,
`nodkey broker check --files` passes, and the commit changes no part
of the gate (`nkp_host_parts` in `lib.sh`: `listen`, `tls_key`, the
paths of `known_hosts` and `audit_log`, `[telegram]`, `[ntfy]`, a new
or changed `[store.*]`); `apply.sh` checks this again as root, also in
a rollback. `summary.sh` (check user):
`nodkey broker config-diff --short --max-chars 1200` from the applied
commit, or from the live config on the first apply, with
`⚠ needs a broker restart: all grants end` first when needed, and a
`⚠` line when the live config is not the applied commit. `apply.sh`
(root): checks the files again with the credential names, refuses to
run while a copy of the old files from an earlier failed restore is
left (`/etc/nodkey/pullgate-old`), installs
them with the owner and mode of the live files, then reloads or
restarts; on a failure it puts the old files back, reloads or restarts
again, and fails. `health.sh` (root): waits until `reload-status.json`
names the unit's main process, a result of `started` or `loaded`, and
the SHA-256 of the live `broker.toml`. The one rule for "reload or
restart" is in `lib.sh`: a reload only when every line of the full
`config-diff` is about a client, secret, project, SSH key (not a new
key or file: credentials load only at the start) or a host key of
`known_hosts`; anything else, or a failed compare, is a restart. Its
tests (`contrib_pullgate_linux_test.go`) run the scripts with `/bin/sh`
against a fake `systemctl` and a fake `nodkey broker reload`, with the
real `nodkey` for the check and the diff. CI runs shellcheck on them.
- `install.sh`, at the root of the repository, installs a release on the
host itself, as root: the broker host or an agent machine. It needs
`sh`, `curl`, `tar`, `gzip`, `sha256sum`, `install`, `mktemp`, `stat`
Expand Down
72 changes: 72 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1755,6 +1755,78 @@ What nodkey does not do:
broker's memory than for one `bws secret get`.
Risk that remains: low, for a broker host that is safe (section 7).

**T52. A change of the config from git, with pullgate, gives access that
the owner did not mean.**
With the recipe in `contrib/pullgate/` (docs/setup.md, "Change the
config from git with pullgate"), the broker host pulls `broker.toml` and
`known_hosts` from a private git repo. pullgate applies a commit only
after the owner taps Apply on its own Telegram bot. The new parties: who
can write the repo, the read-only deploy key, the git host, pullgate's
bot token, and the scripts that run as root.
What nodkey does:
- **The gate is the tap on the host, not CI.** A writer of the repo,
or of its CI, can push any commit, also one that widens access. CI
can check a config, but it runs where the writer has power, so it is
only a help. The broker host applies nothing without the owner's tap
on the exact commit that pullgate shows, and pullgate refuses an older
commit or a rewritten branch.
- The question shows `nodkey broker config-diff` (T42 and DESIGN.md
section 15): each change that widens access starts with `⚠`, and
these lines come first in the summary. A line about a secret names its store item by
the last 8 characters of its ID, so a commit cannot point a trusted
name at another item unseen. A change that needs a restart says so
first, because it ends every grant. A live config that differs from
the applied commit (a change by hand) is a `⚠` line too. The guide
says: tap Skip on a `⚠` line that you did not ask for.
- **A commit cannot change the gate.** The approval channel
(`[telegram]`, `[ntfy]`), `listen`, `tls_key`, the paths of
`known_hosts` and `audit_log`, and a new or changed `[store.*]` are
refused by `check.sh` and again by `apply.sh` as root, also in a
rollback. Else a commit could point the channel at its own server, or
a token file at another credential that the broker holds, and approve
its own requests. These changes stay a step on the host, as root.
- **The scripts are installed on the host, never run from the repo
tree.** They come from the release asset
`nodkey_VERSION_pullgate.tar.gz`, which is in `SHA256SUMS` and
covered by the build attestation of the release, as the binaries are.
The guide installs them only after both checks, owned by root. A
commit cannot change the scripts, the instance config or the units:
they are not in the repo.
- `check.sh` and `summary.sh` run as an unprivileged check user and read
the commit only as data, with nodkey's own parser. Both files must be
plain files, not symlinks, and pullgate refuses a symlink out of the
tree and a large tree (`refuse_symlinks`, `max_files`,
`max_tree_bytes`). A commit may not change the paths of `known_hosts`
and `audit_log`, a store's program or files, or the channel's token
file (see below). It can still name another SSH key file: that is a
`⚠` line and a restart, and the gate is the owner's tap.
- `apply.sh` checks the files again as root with `nodkey broker check`,
with the names of the credentials, before it installs them. The broker
checks the config a third time when it loads it (fail closed). On a
failed reload or restart, the old files go back, and pullgate rolls
back to the last good commit; if that fails too, it pauses and says
so.
- The repo holds no secret value: the config names secrets only by
credential paths and item IDs. A new credential is still a step on the
host, as root.
What nodkey does not do:
- It cannot protect the owner who taps Apply without reading the `⚠`
lines. A careless tap applies what a writer of the repo wrote.
- pullgate puts the summary after the commits and the changed files, and
cuts a long message from the end. A writer of the repo can push many
commits with long subjects, so that the summary, with its `⚠` lines,
is cut off. The recipe keeps the summary short (1200 characters) and
the repo small (`max_files = 20`), and the guide says: tap Skip when
the question has no complete summary, and read the full list on the
host.
- Who can read the repo learns the names of the clients, secrets, keys,
hosts and item IDs, and the approver's Telegram user ID. Keep the repo
private, and give the deploy key read access only.
- pullgate's bot token, the deploy key and pullgate itself are outside
nodkey: pullgate's own THREAT-MODEL.md covers them.
- The git host is one more outbound connection of the broker host.
Risk that remains: low, when the owner reads every `⚠` line.

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
21 changes: 21 additions & 0 deletions contrib/pullgate/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# The pullgate recipe of nodkey

These files let the broker host pull its config from a private git repo
with [pullgate](https://github.com/code6x/pullgate). The owner taps
Apply on Telegram for each commit. A config that fails goes back to the
last good one by itself.

- `nodkey-broker.toml`: the pullgate instance config.
- `check.sh`: checks a new commit, as the check user.
- `summary.sh`: the change list in the question, as the check user.
- `apply.sh`: installs the two files and reloads or restarts the broker,
as root. It puts the old files back on a failure.
- `health.sh`: waits for the broker to say that it runs the new config,
as root.
- `lib.sh`: the part that the scripts share, such as the one rule for
"reload or restart".

Install them from a release of nodkey (`nodkey_VERSION_pullgate.tar.gz`),
checked as docs/setup.md says, and never from a config repo. The steps
are in [docs/setup.md](../../docs/setup.md), "Change the config from git
with pullgate".
105 changes: 105 additions & 0 deletions contrib/pullgate/apply.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
#!/bin/sh
# The apply of the pullgate recipe of nodkey. pullgate runs it as root
# after the owner tapped Apply, and again with the last good commit in a
# rollback. It is safe to run again: it installs two files and reloads or
# restarts the broker.
#
# On a failure it puts the old files back, reloads or restarts the broker
# again, and exits with 1. Then pullgate rolls back, or pauses.
set -u
umask 077
. "${0%/*}/lib.sh"

new=${PULLGATE_TREE:?PULLGATE_TREE is not set; pullgate sets it}
stage=$NKP_ETC/pullgate-new
keep=$NKP_ETC/pullgate-old

# moved is set once the new files are in $NKP_ETC. Before that, a failure
# removes the stage and the copy: the live files did not change.
moved=
fail() {
echo "nodkey apply: $*"
[ -n "$moved" ] || rm -rf "$stage" "$keep"
exit 1
}

nkp_files_ok "$new" || fail "fix the config repo"
nkp_files_ok "$NKP_ETC" || fail "set up $NKP_ETC by hand first (docs/setup.md section 7)"
# known_hosts goes to $NKP_ETC/known_hosts. check.sh refuses a commit that
# moves it, so the live config must name that path.
kh=$(nkp_top_key "$NKP_ETC/broker.toml" known_hosts) ||
fail "cannot read known_hosts = \"...\" at the top of $NKP_ETC/broker.toml; write it as one plain line"
[ "$kh" = "$NKP_ETC/known_hosts" ] ||
fail "the live config has known_hosts = \"$kh\"; this recipe needs \"$NKP_ETC/known_hosts\""

# Stage the new files with the owner and mode of the live ones, and keep
# a copy of the live ones. A stage or a copy from an earlier run that was
# cut off is removed first.
# $keep is left only when an earlier apply could not put the old files
# back. It may hold the only copy of a good config: never remove it here.
[ ! -e "$keep" ] || {
moved=1
fail "$keep is left from an earlier apply; compare it with $NKP_ETC, put back what is right, remove it, then run pullgate status \$PULLGATE_INSTANCE --resume"
}
rm -rf "$stage" || fail "cannot remove $stage; remove it by hand, as root"
mkdir -m 0700 "$stage" "$keep" || fail "cannot make $stage and $keep"
for f in $NKP_FILES; do
cur=$NKP_ETC/$f
install -m "$(stat -c %a "$cur")" -o "$(stat -c %u "$cur")" -g "$(stat -c %g "$cur")" "$new/$f" "$stage/$f" ||
fail "cannot install $stage/$f; read the error above, and check the space and the modes in $NKP_ETC"
cp -p "$cur" "$keep/$f" || fail "cannot copy $cur to $keep; read the error above, and check the space in $NKP_ETC"
done

# The checks of a start again, as root, with the names of the credentials.
if [ -d "$NKP_CREDENTIALS" ]; then
nodkey broker check --files "$stage" --credentials "$NKP_CREDENTIALS" || fail "nodkey broker check refused the new config"
else
nodkey broker check --files "$stage" || fail "nodkey broker check refused the new config"
fi

# The same rule as check.sh, again as root: also a rollback, which runs no
# check, must not change the gate.
nkp_host_parts "$NKP_ETC" "$stage" ||
fail "refused: the commit changes a part that only root on the host may change (docs/setup.md, \"What stays a step on the host\")"

action=$(nkp_action "$NKP_ETC" "$stage")
# A broker that does not run cannot reload. So apply.sh also starts a
# broker that was stopped: pause the instance first to keep it stopped.
systemctl is-active --quiet "$NKP_UNIT" || action=restart
echo "nodkey apply: the change needs a $action"

moved=1
for f in $NKP_FILES; do
mv -f "$stage/$f" "$NKP_ETC/$f" || fail "cannot move $stage/$f to $NKP_ETC; the old files are in $keep"
done
rmdir "$stage"

if nkp_run "$action"; then
rm -rf "$keep"
echo "nodkey apply: done, with a $action"
exit 0
fi

if [ "${PULLGATE_ROLLBACK:-}" = 1 ]; then
# The files that are live now are of the commit that failed: keep the
# last good ones in place, and try a restart.
rm -rf "$keep"
if [ "$action" = reload ] && nkp_run restart; then
echo "nodkey apply: the rollback reload failed, the restart worked"
exit 0
fi
echo "nodkey apply: the rollback failed; the last good files are in $NKP_ETC; read journalctl -u $NKP_UNIT"
exit 1
fi

echo "nodkey apply: the $action failed; the old files go back"
for f in $NKP_FILES; do
mv -f "$keep/$f" "$NKP_ETC/$f" || fail "cannot put $keep/$f back; put it in $NKP_ETC by hand, as root"
done
rmdir "$keep"
if nkp_run "$action"; then
echo "nodkey apply: the old config runs again"
else
echo "nodkey apply: the $action with the old config failed too; read journalctl -u $NKP_UNIT"
fi
exit 1
40 changes: 40 additions & 0 deletions contrib/pullgate/check.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
#!/bin/sh
# The check of the pullgate recipe of nodkey. pullgate runs it as the
# check user, on the new commit, before it asks the owner. It reads the
# tree only as data and runs nothing from it. A failure means no question:
# the owner gets the end of this output instead.
set -u
. "${0%/*}/lib.sh"

new=${PULLGATE_TREE:?PULLGATE_TREE is not set; pullgate sets it}

if ! nkp_files_ok "$new"; then
echo "Fix: put broker.toml and known_hosts at the root of the config repo, as plain files."
exit 1
fi

# The checks of a start, without the files of the host.
if ! nodkey broker check --files "$new"; then
echo "Fix the config in the repo; run nodkey broker check --files DIR on a copy of it first."
exit 1
fi

kh=$(nkp_top_key "$NKP_ETC/broker.toml" known_hosts)
if [ "$kh" != "$NKP_ETC/known_hosts" ]; then
echo "The live config in $NKP_ETC/broker.toml needs known_hosts = \"$NKP_ETC/known_hosts\" on one plain line for this recipe."
echo "Fix: change it on the host, as root (docs/setup.md, \"The config repo\")."
exit 1
fi

# A commit may not change the parts of the gate itself (lib.sh,
# nkp_host_parts), such as the approval channel or a store, or the paths
# of known_hosts and the audit log: apply.sh installs known_hosts in
# $NKP_ETC, and health.sh reads the status file next to the audit log.
if ! nkp_host_parts "$NKP_ETC" "$new"; then
echo "Refused: a commit may not change listen, tls_key, the paths of known_hosts or audit_log,"
echo "[telegram], [ntfy] or a [store.*] (or the compare with $NKP_ETC failed)."
echo "Fix: make such a change on the host, as root (docs/setup.md, \"What stays a step on the host\"),"
echo "then commit the same files. The check user must be able to read $NKP_ETC/broker.toml and known_hosts."
exit 1
fi
echo "The config passed nodkey broker check."
Loading
Loading