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
45 changes: 41 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,15 @@ jobs:
with:
go-version-file: ${{ matrix.go == 'go.mod' && 'go.mod' || '' }}
go-version: ${{ matrix.go == 'stable' && 'stable' || '' }}
- name: Install ssh and sshd for the SSH tests
# The tests of internal/sshauth run the real ssh and sshd. GitHub
- name: Install ssh and sshd for the SSH tests, and PyYAML
# The tests of internal/sshauth run the real ssh and sshd, and the
# tests of contrib/ansible/check-data need PyYAML. GitHub
# sets CI=true, and then these tests fail instead of skip when a
# program is missing.
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install --yes --no-install-recommends openssh-client openssh-server
sudo apt-get install --yes --no-install-recommends openssh-client openssh-server python3-yaml
# The package starts the system ssh service; the tests run their
# own sshd, so stop it and keep port 22 closed.
sudo systemctl disable --now ssh.socket ssh.service || true
Expand All @@ -63,7 +64,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: shellcheck install.sh and contrib/pullgate
- name: shellcheck install.sh, contrib/pullgate and contrib/ansible
# 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 @@ -83,6 +84,7 @@ jobs:
# 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)
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh contrib/ansible/build.sh contrib/ansible/test/ci.sh
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
Expand Down Expand Up @@ -121,6 +123,41 @@ jobs:
# and image that it makes. It fails if one is left.
run: go test -race -tags e2e ./test/e2e/...

ansible:
name: ansible role
runs-on: ubuntu-latest
timeout-minutes: 30
env:
# Two releases with a Sigstore bundle: the test installs OLD, updates
# it to NEW, and installs NEW. Update both by hand after a release.
ANSIBLE_TEST_OLD: 0.6.0
ANSIBLE_TEST_NEW: 0.7.0
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# The test takes install.sh and the unit from the tags.
fetch-depth: 0
- name: Install ansible-lint
# Fixed versions. Dependabot does not update them. Update them by
# hand, both together.
run: |
set -euo pipefail
python3 -m venv "${RUNNER_TEMP}/ansible"
"${RUNNER_TEMP}/ansible/bin/pip" install --quiet ansible-core==2.21.6 ansible-lint==26.11.0
- name: ansible-lint
working-directory: contrib/ansible
run: |
set -euo pipefail
export PATH="${RUNNER_TEMP}/ansible/bin:$PATH"
ansible-lint --version
ansible-lint --strict --profile production .
- name: The role in a Debian container with systemd
# contrib/ansible/test/ci.sh: both sides, a second run with no
# change, the unit of the tag, a wrong SHA-256, an older and a
# newer version. It removes the containers and the image.
run: sh contrib/ansible/test/ci.sh "$ANSIBLE_TEST_OLD" "$ANSIBLE_TEST_NEW"

vuln:
runs-on: ubuntu-latest
steps:
Expand Down
9 changes: 9 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,15 @@ jobs:
# 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"
# The Ansible recipe (contrib/ansible): the role, the playbooks
# and check-data. build.sh puts the install.sh and the unit of
# this tag into the role, and pins their SHA-256 in it. A host
# installs it from here, checked as the binaries are.
name="nodkey_${VERSION}_ansible"
stage="${RUNNER_TEMP}/${name}"
sh contrib/ansible/build.sh "$VERSION" . "$stage"
(cd "$stage" && export LC_ALL=C && tar --sort=name --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
8 changes: 8 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@ Planned. Each v1 issue adds its part.
"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/ansible/` - the Ansible recipe: the role `roles/nodkey` (broker
or agent side), the playbooks `broker-host.yml` and `agent-host.yml`
for a data file, `check-data`, and `build.sh`, which makes the recipe
of a release with the `install.sh` and the unit of the tag (DESIGN.md
section 18, THREAT-MODEL.md T53). Its tests are in
`contrib_ansible_linux_test.go`, at the root of the module, and
`contrib/ansible/test/ci.sh`, which runs the role in a container with
systemd. The release packs it as `nodkey_VERSION_ansible.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
69 changes: 67 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4609,8 +4609,9 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`):
version and creates the GitHub Release. A job then builds static Linux
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
of `contrib/pullgate/` and `LICENSE`), the tarball of the Ansible
recipe (`nodkey_<version>_ansible.tar.gz`, below), 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.
Expand Down Expand Up @@ -4643,6 +4644,70 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`):
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.
- The Ansible recipe (`contrib/ansible/`, issue #193) installs nodkey
on the broker host or an agent machine (THREAT-MODEL.md T53). It is a
plain role, `contrib/ansible/roles/nodkey`, not an Ansible collection:
a host uses it from a checked release file by its path, with no Galaxy
and no second place to publish. Two fixed playbooks
(`playbooks/broker-host.yml`, `playbooks/agent-host.yml`) run it from
one data file, and `check-data` checks that file. `build.sh` makes the
recipe of one release: it copies `install.sh` and
`contrib/systemd/nodkey.service` of the tag into the role, and writes
their SHA-256 and the version into `roles/nodkey/vars/main.yml`. The
release packs it as `nodkey_<version>_ansible.tar.gz`. The source in
the repository has none of these files, and refuses to run. The rules:
- The role of release X installs only nodkey X, with the `install.sh`
and the unit of the tag vX. `nodkey_version` must be X.
- Before any change, the role checks the SHA-256 of its `install.sh`
and its unit against the pins, and the SHA-256 of `install.sh` again
after the copy to the host. Before it runs the installed nodkey
(`tasks/installed.yml`, also run by the playbooks), it checks that the
file is a plain file and no link, and that only root can change it
and `/`, `/usr`, `/usr/local` and `/usr/local/bin`.
- The first install runs that `install.sh` with `--version X`: the
checks of the SHA-256 in `SHA256SUMS`, of the attestation and of the
version. An update runs only `nodkey update --version X` of the
installed binary, so the checks come from the checked nodkey on the
host, never from the role. Forward only: the role refuses a version
older than the installed one, and an installed nodkey that is not a
release. Then `nodkey version` must print X.
- Broker side: the user and group `nodkey`, `/etc/nodkey` (root,
`0755`), `/etc/nodkey/credentials` (root, `0700`, left empty) and the
unit of the tag, unchanged, in `/etc/systemd/system/nodkey.service`.
It never writes `broker.toml`, `known_hosts`, a drop-in or a
credential. With `nodkey_broker_config`, it runs
`nodkey broker check --config` as the user `nodkey`. A changed binary
or unit writes the mark `/var/lib/nodkey-ansible/restart-due` at once,
and a handler at the end of the play runs `systemctl daemon-reload`
and `systemctl try-restart nodkey` (only a `daemon-reload` and a
message when `nodkey_restart` is false), then removes the mark. A run
that finds the mark does the restart, so a play that failed after an
update does not leave it undone. It never enables or starts the
broker. A unit that differs is kept as a backup file.
- Agent side, with `nodkey_ssh_agent_user`: the user unit
`/etc/systemd/user/nodkey-ssh-agent.service` with `ConditionUser=`,
enabled for all accounts by a link in
`/etc/systemd/user/default.target.wants`, and linger for the
account. The role never writes into a home directory, which the
agent can change (a link there would turn a write as root into a
write anywhere). With no account, it removes the unit and its link.
- The playbooks take the path of the data file
(`-e nodkey_data_file=PATH`), copy it to a private temporary
directory, run `check-data` on the copy, and only then read the same
copy into one variable with `include_vars name:`. So no key of the
file becomes a variable of its own, which could change a pin of the
role. `check-data` accepts only the keys of the side, each with its
type, refuses a key that is there twice, and a version older than
the installed one (`--installed`, which is required; it never runs
nodkey). A text value may hold only the characters of a path or an
account name, so no value is an Ansible template, and a config path
must be in `/etc/nodkey/`. It prints no value of the file, and a key
name only if it is plain. The role needs ansible-core 2.19 or newer.
- Its tests: `contrib_ansible_linux_test.go` tests `check-data` and
`build.sh`; `contrib/ansible/test/ci.sh`, in the CI job `ansible`,
runs both sides in a Debian stable container with systemd, against
two real releases. CI runs `ansible-lint` with the `production`
profile on it.
- `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
66 changes: 66 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1827,6 +1827,72 @@ What nodkey does not do:
- The git host is one more outbound connection of the broker host.
Risk that remains: low, when the owner reads every `⚠` line.

**T53. The Ansible role installs a changed nodkey or unit, as root.**
The role in `contrib/ansible/` (DESIGN.md section 18) runs as root on
the broker host or an agent machine, and downloads a release. The new
parties: the copy of the role on the machine that runs Ansible, and,
with the playbooks, the data file of the host and who can write it.
What nodkey does:
- **The same checks as `install.sh`, and no way to skip them.** The
first install runs the `install.sh` of the tag, which checks the
SHA-256 in `SHA256SUMS`, the attestation with `gh attestation verify`
and the version of the new binary (T20). An update runs only
`nodkey update --version X` of the installed nodkey, so its checks
come from the checked binary on the host, not from the role, a play or
a repo. The role has no setting to skip the attestation or any other
check.
- **The role comes checked, from the release.** The release file
`nodkey_VERSION_ansible.tar.gz` holds the role, the playbooks and
`check-data`, with the `install.sh` and the unit of the tag in the
role, and their SHA-256 pinned in `roles/nodkey/vars/main.yml`. It is
in `SHA256SUMS` and covered by the build attestation of the release,
as the binaries are. The guide (`contrib/ansible/README.md`) checks it
with both, and unpacks it into a directory that only root can change.
The role checks the pinned SHA-256 of its `install.sh` and unit before
any change, and the source in the repository refuses to run.
- **It runs no file that someone else can change.** Before it runs the
installed `/usr/local/bin/nodkey` as root, the role and the playbooks
check that it is a plain file, no link, and that only root can change
it and each directory above it, as `install.sh` does. On an agent
machine, the agent may be able to change such a file.
- **Forward only.** The role refuses a version older than the installed
one, so a change of the version cannot take a host back to an older
release with a known bug. It installs only the version of its own
release, with the unit of the same tag.
- **The data file is only data.** The playbooks copy the file to a
private directory, run `check-data` on the copy, and read the same
copy with `include_vars name:` into one variable: only known keys,
each with its type. A key of the file cannot set a pin or another
setting of the role. Ansible renders a text value with `{{` as a
template; `check-data` allows only the characters of a path or an
account name, so no value of the file is a template. A config path of
the file must be in `/etc/nodkey/`, so a failed check shows no line of
a file elsewhere. Keep no secret in `/etc/nodkey/` that the user
`nodkey` can read: the credentials are in `credentials/`, which only
root can enter. The role writes no
`broker.toml`, no drop-in and no credential; the credential directory
stays an empty slot (`0700`, root).
- On an agent machine, the role writes no file in the home directory of
the account, which the agent controls: a link there would turn a
write as root into a write anywhere.
What nodkey does not do:
- It cannot protect a role that is run from a place that someone else
can change: then that person can change any task, which runs as root.
Run it only from the checked release file, from a directory that only
root can change.
- Who can write the data file can only confirm the version of the
recipe that is installed on the host, turn the restart on or off,
and, on an agent machine, choose the account of the user unit. Who
installs a newer recipe on the host chooses the release. A restart
ends all grants. Nobody can choose an older release or a file that is
not checked through the data file.
- A version that the role pins was checked only by its build; a bad
release is a bad release (T20).
- When a play fails after an update, the old binary may still run until
the next run that passes: the mark `/var/lib/nodkey-ansible/restart-due`
makes that run restart it.
Risk that remains: low, when the role comes from a checked release file.

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
Loading
Loading