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
32 changes: 31 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3182,6 +3182,7 @@ and `[standing]` need a restart.
```
nodkey broker [--config FILE]
nodkey broker reload [--config FILE] [--timeout DURATION]
nodkey broker check [--config FILE] [--files DIR] [--credentials DIR]
nodkey run [--secret VAR=NAME]... [--grant-token FILE] [--reason TEXT] [--mask | --no-mask] -- COMMAND [ARGS...]
nodkey ssh-agent [--socket PATH]
nodkey ssh-grant --key NAME --user USER --host NAME... --for DURATION [--reason TEXT]
Expand Down Expand Up @@ -3312,7 +3313,36 @@ command cannot parse the config (then it sends no signal); 64 on wrong
usage. A tool that applies config changes, such as from git, runs it
after each change and undoes the change when it fails.

It stops on SIGTERM or SIGINT, also during the start, when the polling
`nodkey broker check` checks a config without a start, such as a new
config before it is applied (issue #173). It starts nothing, opens no
port, uses no network and needs no root. It parses the config with the
code of the start and of a reload (`config.ReadBrokerFiles`, the parser
of `LoadBroker`), with `known_hosts`, and then checks the files that the
config names with `CheckFilesAs`, for the user that runs it. `nodkey
doctor broker` uses the same two parts. It reads no credential:

- A file in `${CREDENTIALS_DIRECTORY}/` is skipped, and the output says
so. With `--credentials DIR`, `${CREDENTIALS_DIRECTORY}` stands for
DIR, and the check only finds a regular file `NAME` or `NAME.cred`
there. It opens none of them.
- With `--files DIR`, `known_hosts` is read from DIR, by the base name of
its path in the config, and not from that path. So a new config is
checked with its own new `known_hosts`, also in CI. The files of the
broker host (`tls_key`, the token and key files, the store programs and
the audit log) are then not checked; the output says so. Without
`--config`, the config is `DIR/broker.toml`.

So it does not find what only the content of a credential shows, such as
a TLS or SSH key that does not parse, or two `[key.*]` sections with the
same key in two files. The start and a reload still check these. A
`known_hosts` in `${CREDENTIALS_DIRECTORY}/` is not secret, and is the
one file there that the check reads: from the `--credentials` directory,
or from `--files`. A credential path with `..` in it is refused. Each line
of the output is cleaned with `claim.Line`, so text from the config
cannot add a line or change the terminal. It exits 0 when the config
passed, 1 with the reason when it did not, and 64 on wrong usage.

The broker stops on SIGTERM or SIGINT, also during the start, when the polling
stops for good (section 7), when its server fails, and when a write to
stderr fails (a log line or an audit anchor), such as after the reader
of stderr went away. The broker catches SIGPIPE with `signal.Notify`, so
Expand Down
13 changes: 13 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1485,6 +1485,19 @@ signal another process of the broker's user, or report a false result;
that user owns the broker already. The command cleans the text of the
file before it prints it.

`nodkey broker check` (issue #173) checks a config before it is applied.
It reads the config and `known_hosts`, from the paths in the config or
from `--files DIR`, and runs as any user. It opens no credential and no
key file: with `--credentials DIR` it only looks for the names. So a
config from a branch or a pull request can be checked in CI without a
secret. (A `known_hosts` in the credentials directory is read: it is not
secret.) It cleans each line of its output (`claim.Line`), so text in a
config from a pull request, such as a line break in a path, cannot add
lines to a CI log. A config that passes the check can still fail at the reload, on
a check that needs a credential; the reload then keeps the old config.
The check is no part of what the broker trusts: the broker checks every
config again when it loads it.

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
10 changes: 8 additions & 2 deletions cmd/nodkey/broker.go
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ var errPanicked = errors.New("it panicked; the panic value is not logged")

const brokerUsage = `Usage: nodkey broker [--config FILE]
nodkey broker reload [--config FILE] [--timeout DURATION]
nodkey broker check [--config FILE] [--files DIR] [--credentials DIR]

Run the broker: the daemon that holds the SSH keys and the access to the
secret stores. It asks the approver on Telegram before it hands out a
Expand All @@ -115,9 +116,11 @@ unit such as contrib/systemd/nodkey.service.
--config FILE the broker config (default /etc/nodkey/broker.toml)

It logs to stderr, which systemd keeps in the journal, with the anchors
of the audit log. SIGTERM or SIGINT stops it. SIGHUP reloads the config
without a restart; see "nodkey broker reload --help". So does a failed write to
of the audit log. SIGTERM or SIGINT stops it. So does a failed write to
stderr, such as after its reader is gone: it stops with exit code 1.
SIGHUP reloads the config without a restart; see "nodkey broker reload
--help". To check a config without a start, see "nodkey broker check
--help".

Exit codes: 0 stopped by SIGTERM or SIGINT, 1 any other error, 64 wrong
usage, 76 Telegram reports a polling conflict: the bot token may be
Expand All @@ -131,6 +134,9 @@ func runBroker(args []string, stdout, stderr io.Writer) int {
if len(args) > 0 && args[0] == "reload" {
return runBrokerReload(args[1:], stdout, stderr)
}
if len(args) > 0 && args[0] == "check" {
return runBrokerCheck(args[1:], stdout, stderr)
}
// A broken stderr must not end the broker with SIGPIPE in the middle
// of a line: the write fails instead, and the broker stops in its
// order (issue #73).
Expand Down
176 changes: 176 additions & 0 deletions cmd/nodkey/brokercheck.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
package main

import (
"errors"
"flag"
"fmt"
"io"
"io/fs"
"os"
"path/filepath"
"strings"

"github.com/code6x/nodkey/internal/claim"
"github.com/code6x/nodkey/internal/config"
"github.com/code6x/nodkey/internal/doctor"
)

const brokerCheckUsage = `Usage: nodkey broker check [--config FILE] [--files DIR] [--credentials DIR]

Check a broker config without starting the broker: the config file, and
the files that it names, get the same checks as at a start. It starts
nothing, opens no port, and uses no network. Run it as the broker's user
(on the broker host), or as any user with --files (such as in CI).

--config FILE the broker config (default /etc/nodkey/broker.toml,
or DIR/broker.toml with --files DIR)
--files DIR read known_hosts from DIR, by the base name of its
path in the config, and not from that path; so a new
config is checked with its own known_hosts. The files
of the broker host (the TLS key, the token and key
files, the store programs, the audit log) are then
not checked
--credentials DIR check that each ${CREDENTIALS_DIRECTORY}/NAME of the
config has a file NAME or NAME.cred in DIR; nothing
in it is read. Without it, these files are skipped

Exit codes: 0 the config is good, 1 it is not, 64 wrong usage.
`

// checkLineMax is the most runes of one cleaned line of the output.
const checkLineMax = 2000

// runBrokerCheck runs nodkey broker check (DESIGN.md section 15).
func runBrokerCheck(args []string, stdout, stderr io.Writer) int {
fs := flag.NewFlagSet("nodkey broker check", flag.ContinueOnError)
fs.SetOutput(io.Discard)
path := fs.String("config", "", "the broker config")
files := fs.String("files", "", "the directory of known_hosts")
creds := fs.String("credentials", "", "the directory of the credentials")
if err := fs.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
_, _ = io.WriteString(stdout, brokerCheckUsage)
return exitOK
}
return parseErrorCode(stderr, "broker check", err)
}
if fs.NArg() > 0 {
return usageFail(stderr, "broker check", fmt.Sprintf(
"unexpected argument %.64q; it takes only --config FILE, --files DIR and --credentials DIR", fs.Arg(0)))
}
for _, f := range []struct{ name, dir string }{{"--files", *files}, {"--credentials", *creds}} {
if f.dir == "" {
continue
}
if fi, err := os.Stat(f.dir); err != nil || !fi.IsDir() {
return usageFail(stderr, "broker check", f.name+" must name a directory that exists")
}
}
if *path == "" {
*path = defaultBrokerConfig
if *files != "" {
*path = filepath.Join(*files, "broker.toml")
}
}
res, err := checkBrokerConfig(*path, *files, *creds)
// A config from a pull request may hold any text, such as a line
// break in a path. Each line is cleaned, so that it cannot add lines
// to a CI log or change the terminal.
for _, s := range res.skipped {
_, _ = fmt.Fprintf(stdout, "skipped: %s\n", claim.Line(s, checkLineMax))
}
if err != nil {
_, _ = fmt.Fprintf(stderr, "nodkey broker check: %s; fix it as the error says (docs/setup.md section 7), "+
"then run nodkey broker check again\n", claim.Line(err.Error(), checkLineMax))
return exitFailure
}
_, _ = fmt.Fprintf(stdout, "nodkey broker check: %s passed the checks of a start\n", claim.Line(*path, checkLineMax))
return exitOK
}

// checkResult is what checkBrokerConfig did not check, in plain words.
type checkResult struct {
skipped []string
}

// checkBrokerConfig makes the config checks of a start on the config at
// path: config.ReadBrokerFiles parses it, as config.LoadBroker does for
// the start and a reload, and (*config.Broker).CheckFilesAs checks the
// files it names, as the user that runs this command. It reads no
// credential: a ${CREDENTIALS_DIRECTORY}/ file is skipped, or with
// credDir only found in credDir. With filesDir, known_hosts comes from
// filesDir, and the files of the broker host are not checked.
func checkBrokerConfig(path, filesDir, credDir string) (checkResult, error) {
var res checkResult
// ${CREDENTIALS_DIRECTORY} stands for credDir, or for the directory
// of the unit. Only this process sees the value; a value from the
// environment is not trusted (as in nodkey doctor broker).
dir := "/run/credentials/" + doctor.Unit
if credDir != "" {
abs, err := filepath.Abs(credDir)
if err != nil {
return res, fmt.Errorf("--credentials %s: %w", credDir, err)
}
dir = abs
}
if err := os.Setenv("CREDENTIALS_DIRECTORY", dir); err != nil {
return res, fmt.Errorf("cannot set CREDENTIALS_DIRECTORY: %w", err)
}
cfg, err := config.ReadBrokerFiles(path, filesDir)
if err != nil {
return res, err
}
private, err := cfg.PrivateFiles()
if err != nil {
return res, err
}
inCreds := func(p string) (string, bool) { return strings.CutPrefix(p, dir+"/") }
for _, f := range private {
name, ok := inCreds(f.Path)
switch {
case !ok:
if filesDir != "" {
res.skipped = append(res.skipped, f.Where+": a file of the broker host; --files checks only the "+
"config and known_hosts")
}
case !filepath.IsLocal(name):
return res, fmt.Errorf("config %s: %s: the path leaves ${CREDENTIALS_DIRECTORY}; write it as "+
"${CREDENTIALS_DIRECTORY}/NAME, with no \"..\"", path, f.Where)
case credDir == "":
res.skipped = append(res.skipped, fmt.Sprintf("%s: needs the credential %q; give --credentials DIR "+
"to check that it is there", f.Where, name))
default:
if err := credentialThere(dir, name); err != nil {
return res, fmt.Errorf("config %s: %s: %w", path, f.Where, err)
}
}
}
if filesDir != "" {
res.skipped = append(res.skipped, "the store programs and audit_log: files of the broker host; "+
"--files checks only the config and known_hosts")
return res, nil
}
self := uint32(os.Getuid()) //nolint:gosec // G115: a user ID fits in 32 bits on Linux.
skip := func(p string) bool { _, ok := inCreds(p); return ok }
return res, cfg.CheckFilesAs(self, skip)
}

// credentialThere checks that dir has a regular file name or name.cred.
// It reads nothing in it. name must pass filepath.IsLocal.
func credentialThere(dir, name string) error {
for _, n := range []string{name, name + ".cred"} {
fi, err := os.Stat(filepath.Join(dir, n))
switch {
case err == nil && fi.Mode().IsRegular():
return nil
case err == nil:
return fmt.Errorf("the credential %q in %s is not a regular file; put the encrypted credential there", n, dir)
case !errors.Is(err, fs.ErrNotExist):
return fmt.Errorf("cannot look for the credential %q in %s as this user (%w); give --credentials a "+
"directory that this user can enter, or check the credentials with nodkey doctor broker, as root",
n, dir, errors.Unwrap(err))
}
}
return fmt.Errorf("the credential %q is not in %s: there is no file %q or %q; make it as docs/setup.md "+
"section 3 shows", name, dir, name, name+".cred")
}
Loading
Loading