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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,18 @@ uses [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

- `lockhttp console` takes `--runtime-gids GID,...` (lockkit's hub flags,
`console.HubOptions`), as the other locks' consoles do (#69,
lockhub#212): a client of the console's socket holding one of those gids
is unconfined (`runtime_group`), refused with `CodeUnconfined` unless the
profile sets `unconfined = true` (non-production). An invalid list is a
usage error (exit 3), and the other hub flags (`--hub`, `--instance`,
...) are still refused: the console is policy-only. This release is the
first that takes the flag: lockhub adds `"lockhttp": "<this release>"`
to `family.RuntimeGIDsSince`.

## [0.11.0] - 2026-11-14

Built on lockkit v0.20.0. Needs lea v0.16.0 or later for `LEA_LOCKHTTP=1`.
Expand Down
19 changes: 15 additions & 4 deletions cmd/lockhttp/console.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,27 @@ func (e env) configPath(flagVal string) (string, error) {
// account's own session (`lox run` runs it). It serves the approved policy
// to the gate and asks its human about every loosening; the gate asks
// lockhub, never this console, about held requests. It is lockkit's
// policy-only console: it takes no hub flags (lox run passes none) and
// approves no request.
// policy-only console and approves no request. It registers lockkit's hub
// flags as the other locks' consoles do, for --runtime-gids (lockhub#212):
// a socket peer holding one of those gids is unconfined (runtime_group).
// The others (--hub, --instance, ...) are refused: it has no hub.
func runConsole(e env, args []string) int {
const usage = "lockhttp console [--profile P] [--config FILE]"
const usage = "lockhttp console [--profile P] [--config FILE] [--runtime-gids GID,...]"
fs := flag.NewFlagSet("console", flag.ContinueOnError)
profile := fs.String("profile", "default", "profile to serve")
cfgFlag := fs.String("config", "", "policy file (default: ~/.config/lockhttp/config.toml)")
var hub console.HubOptions
hub.Register(fs)
if !parse(e, fs, "console", usage, args) {
return exitUsage
}
// Refused before the terminal or the policy is touched, never ignored.
if hub.Enabled() {
return usageFail(e, "console", usage, "a policy-only console takes no hub flags (-hub, -hub-key-file, -instance, ...): its gate asks lockhub")
}
if _, err := console.ParseGIDs(hub.RuntimeGIDs); err != nil {
return usageFail(e, "console", usage, "--runtime-gids is not a comma-separated list of gids")
}
if !e.tty {
fmt.Fprintln(e.stderr, "lockhttp console: must run in a terminal: it asks the human about policy changes")
return exitUsage
Expand All @@ -67,7 +78,7 @@ func runConsole(e env, args []string) int {
}
err = runFn(ctx, p, be, console.Options{
Profile: *profile, IO: term, TTY: os.Stdin,
Sanitizer: httpconsole.Sanitizer(), PolicyOnly: true,
Sanitizer: httpconsole.Sanitizer(), PolicyOnly: true, Hub: hub,
})
if err != nil {
fmt.Fprintln(e.stderr, "lockhttp console:", err)
Expand Down
97 changes: 89 additions & 8 deletions cmd/lockhttp/loxup_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,22 @@ package main

import (
"context"
"errors"
"io"
"os"
"path/filepath"
"strconv"
"strings"
"sync"
"testing"
"time"

"github.com/DavidGodefroid/lockkit/console"
"github.com/DavidGodefroid/lockkit/ipc"
"github.com/DavidGodefroid/lockkit/kit"
"github.com/DavidGodefroid/lockkit/sysconf"

"github.com/DavidGodefroid/lockhttp/internal/gate"
)

// loxUpConsoleArgv is the command lockhub's `lox run` gives a lockhttp
Expand All @@ -23,22 +28,32 @@ import (
// cmd := []string{"console"}
// if prof := l.Profile; prof != "" || l.Type == "lockfile" { ...; cmd = append(cmd, "--profile", prof) }
// if len(l.AllowedUIDs) > 0 { cmd = append(cmd, "--allowed-uids", ...) }
// if g := p.RuntimeGIDs[name]; g != "" { cmd = append(cmd, "--runtime-gids", g) }
// if !k.Gate { cmd = append(cmd, "--hub", ..., "--instance", name); ... }
//
// lockhttp is a Gate kind (its gate asks the hub; the console only serves
// the policy) and lockhub refuses allowed_uids on it: the console gets
// "console" and, when the lock names a profile, "--profile P". No hub
// flag. Keep this in step with lockhub: if it changes, this test says
// "console", "--profile P" when the lock names a profile, and
// "--runtime-gids G" once family.RuntimeGIDsSince names lockhttp's release
// (lockhub#212). No other hub flag. Keep this in step with lockhub: if it changes, this test says
// whether lockhttp's console still starts under lox run.
//
// This is a copy: it does not detect a change in lockhub's compose.go.
// That side is guarded by lockhub's internal/family/contract_test.go,
// which asserts the argv lox run gives the lockhttp console service.
func loxUpConsoleArgv(profile string) []string {
return loxUpConsoleArgvGIDs(profile, "")
}

// loxUpConsoleArgvGIDs is loxUpConsoleArgv with the host's runtime gids.
func loxUpConsoleArgvGIDs(profile, gids string) []string {
cmd := []string{"console"}
if profile != "" {
cmd = append(cmd, "--profile", profile)
}
if gids != "" {
cmd = append(cmd, "--runtime-gids", gids)
}
return cmd
}

Expand All @@ -65,9 +80,10 @@ func (a *answerer) text() string {
return strings.Join(a.lines, "\n")
}

// lockhttp console, started with the argv lox run writes for it, starts
// (lockkit's policy-only console: no hub) and listens; the console Run
// gets is policy-only, with no hub option.
// lockhttp console, started with the argv lox run writes for it, with or
// without --runtime-gids, starts (lockkit's policy-only console: no hub)
// and listens; the console Run gets is policy-only, with no hub option but
// the runtime gids.
func TestConsoleStartsAsLoxUpRunsIt(t *testing.T) {
rt, err := os.MkdirTemp("/tmp", "lhrt")
if err != nil {
Expand All @@ -79,8 +95,9 @@ func TestConsoleStartsAsLoxUpRunsIt(t *testing.T) {
if err := os.WriteFile(cfg, []byte("[profiles.default]\nhold = \"5s\"\n\n[profiles.egress]\nhold = \"5s\"\n"), 0o600); err != nil {
t.Fatal(err)
}
for _, profile := range []string{"", "egress"} {
argv := loxUpConsoleArgv(profile)
for _, c := range []struct{ profile, gids string }{{"", ""}, {"egress", ""}, {"", "999,4242"}, {"egress", "999"}} {
profile := c.profile
argv := loxUpConsoleArgvGIDs(profile, c.gids)
term := &answerer{}
var got console.Options
e := env{tty: true, userConfig: cfg, consoleRun: func(ctx context.Context, p kit.Product, b console.Backend, o console.Options) error {
Expand All @@ -102,7 +119,7 @@ func TestConsoleStartsAsLoxUpRunsIt(t *testing.T) {
if code != exitOK || !strings.Contains(term.text(), "Listening on") {
t.Fatalf("%v: exit %d %s\n%s", argv, code, errs, term.text())
}
if !got.PolicyOnly || got.Hub.Enabled() || got.OnHub != nil {
if !got.PolicyOnly || got.Hub.Enabled() || got.OnHub != nil || got.Hub.RuntimeGIDs != c.gids {
t.Fatalf("%v: options %+v", argv, got)
}
want := profile
Expand Down Expand Up @@ -170,3 +187,67 @@ func TestConsoleRefusesHubFlags(t *testing.T) {
t.Fatalf("exit %d %s", code, errs)
}
}

// An invalid --runtime-gids is a usage error, refused before a console runs:
// never ignored (lockhub#212).
func TestConsoleRefusesInvalidRuntimeGIDs(t *testing.T) {
e := env{tty: true, consoleRun: func(context.Context, kit.Product, console.Backend, console.Options) error {
t.Fatal("the console ran")
return nil
}}
for _, g := range []string{"docker", "999,", ",999", "999,,4242", "-1", "999;4242", "4294967296"} {
code, _, errs := runEnv(t, e, loxUpConsoleArgvGIDs("", g)...)
if code != exitUsage || !strings.Contains(errs, "--runtime-gids") {
t.Fatalf("%q: exit %d %s", g, code, errs)
}
}
}

// A socket peer holding one of the --runtime-gids is unconfined
// (runtime_group): a profile without unconfined = true refuses it with
// CodeUnconfined, whatever the peer reports (lockkit#133).
func TestConsoleRuntimeGroupPeerRefused(t *testing.T) {
rt, err := os.MkdirTemp("/tmp", "lhrt")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.RemoveAll(rt) })
t.Setenv("LOCKHTTP_RUNTIME_DIR", rt)
cfg := filepath.Join(t.TempDir(), "config.toml")
if err := os.WriteFile(cfg, []byte("[profiles.default]\nhold = \"5s\"\n"), 0o600); err != nil {
t.Fatal(err)
}
term := &answerer{}
var callErr error
e := env{tty: true, userConfig: cfg, consoleRun: func(ctx context.Context, p kit.Product, b console.Backend, o console.Options) error {
ctx, cancel := context.WithCancel(ctx)
defer cancel()
o.IO, o.TTY, o.StateDir, o.Quantum = term, nil, t.TempDir(), -1
o.Harden = func() error { return nil }
o.Isolation = &console.IsolationEnv{
AllowSameUser: true,
LoadSys: func() (*sysconf.Config, error) { return nil, nil },
Display: func() sysconf.Display { return sysconf.Display{} },
UID: os.Getuid,
}
o.Ready = func(string) {
go func() {
defer cancel()
_, callErr = (&gate.LockkitConsole{Profile: "default"}).Policy(ctx)
}()
}
return console.Run(ctx, p, b, o)
}}
// The test's own gid: this process is the socket's peer.
code, _, errs := runEnv(t, e, loxUpConsoleArgvGIDs("", "4242,"+strconv.Itoa(os.Getgid()))...)
if code != exitOK {
t.Fatalf("exit %d %s\n%s", code, errs, term.text())
}
var rpc *ipc.RPCError
if !errors.As(callErr, &rpc) || rpc.Code != ipc.CodeUnconfined || !strings.Contains(rpc.Message, "runtime_group") {
t.Fatalf("runtime group peer: %v\n%s", callErr, term.text())
}
if !strings.Contains(term.text(), "refused an unconfined agent") || !strings.Contains(term.text(), "runtime_group") {
t.Fatalf("the console did not show the refusal:\n%s", term.text())
}
}
11 changes: 10 additions & 1 deletion docs/lea.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ against. Contract version: **1** (the `version` field of every file below).
lockhttp signer (uid 10004 "signer") ◀─ leaf certificates ─ gate (socket volume)
│ volume <project>_<instance>-run: /run/lockhttp/user-<profile>.sock
console container (lox run's service lock-<instance>)
lockhttp console --profile <profile> (uid 10021 "lockhttp")
lockhttp console --profile <profile> [--runtime-gids <gid,...>] (uid 10021 "lockhttp")
·
the gate ──▶ lockhub (lox run's network <project>_lockhub; only <prefix>-proxy joins it)
```
Expand All @@ -56,6 +56,15 @@ against. Contract version: **1** (the `version` field of every file below).

lea never starts the console and never mounts the console's home.

`lox run` gives the console `--runtime-gids`, the gids owning the host's
container runtime sockets (lockhub#212), as it does the other locks'
consoles: a client of the console's socket holding one of them is
unconfined (`runtime_group`) and refused with `CodeUnconfined` unless the
profile sets `unconfined = true` (non-production). The gate, uid 10003 in
the image, holds none. lockhttp takes the flag from v0.12.0; an invalid
list stops the console (usage error), never ignored. See
[usage.md](usage.md#lockhttp-console).

## 2. The gate container

lea runs the gate as a sidecar of `<prefix>-proxy` when `LEA_LOCKHTTP=1`.
Expand Down
11 changes: 7 additions & 4 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ console.
## `lockhttp console`

```
lockhttp console [--profile P] [--config FILE]
lockhttp console [--profile P] [--config FILE] [--runtime-gids GID,...]
```

The policy console: lockkit's console, serving `policy.get` to the gate.
Expand All @@ -145,14 +145,17 @@ console account. Under `lox run` it runs in its own compose service, with
the policy copied from `<workspace>/.lockhttp/` (`lox attach <instance>`
attaches its terminal); the launcher runs it in the container
`lockhttp-console`, the only one that mounts `lockhttp-home`. It is
lockkit's policy-only console: it takes no hub flags (`lox run` passes
none to it, only to the gate) and approves no request; one that reached
it would be refused. The gate, not the console, needs the hub flags.
lockkit's policy-only console: of lockkit's hub flags it takes
`--runtime-gids` only (`lox run` passes the others to the gate) and
approves no request; one that reached it would be refused. `--hub`,
`--hub-key-file`, `--instance` and the other hub flags are a usage error
(exit 3). The gate, not the console, needs the hub flags.

| Flag | Default | Meaning |
|---|---|---|
| `--profile P` | `default` | Profile to serve. Its socket is `user-P.sock` in the socket directory. |
| `--config FILE` | `~/.config/lockhttp/config.toml` | The policy file. |
| `--runtime-gids GID,...` | none | The gids owning the host's container runtime sockets (written by `lox run`, lockhub#212). A client of the socket holding one is unconfined (`runtime_group`): refused with `CodeUnconfined` unless the profile sets `unconfined = true` (never on a production profile). The console adds those of its own machine. A value that is not a comma-separated list of gids is a usage error (exit 3), never ignored. |

At the first start of a profile you review its whole policy (`Apply these
changes? [y/N]`); at a later start, a loosening made since the last
Expand Down
13 changes: 8 additions & 5 deletions test/docker/e2e.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

The console runs in a pseudo-terminal this script answers (y to every
prompt). The console is lockkit's policy-only console: it starts without
hub flags, as `lox run` runs it (`console`, or `console --profile P`), and
refuses them. The gate is hub-attached only: without its hub flags the
hub flags, as `lox run` runs it (`console`, or `console --profile P`, with
or without `--runtime-gids G`), and refuses them. The gate is hub-attached only: without its hub flags the
launcher's gate refuses to start ("launched by `lox run` only"). A request
through a gate that asks a hub is tested end to end by lockhub's e2e,
which runs the lockhttp lock under `lox run`. Needs docker. Uses the
Expand Down Expand Up @@ -175,9 +175,9 @@ def main():

# The console starts without hub flags, as lox run runs it (lockhub
# internal/family/compose.go gives a gate kind's console `console`,
# plus `--profile P` when the lock names one): it approves its first
# policy, listens, and asks no hub.
for args in ([], ["--profile", "default"]):
# plus `--profile P` when the lock names one, and `--runtime-gids G`,
# lockhub#212): it approves its first policy, listens, and asks no hub.
for args in ([], ["--profile", "default"], ["--runtime-gids", "999,4242"], ["--profile", "default", "--runtime-gids", "999"]):
console = Console(*args)
check(console.wait_for("Listening on"), f"the console listens without hub flags ({' '.join(['console', *args])})", console.text())
check(console.wait_for("Policy only"), "the console is policy-only", console.text())
Expand Down Expand Up @@ -216,6 +216,9 @@ def main():
# The hub flags lox run gives the other locks' consoles are refused.
r = launcher("console", "--hub", "http://lockhub:8443", "--hub-plain-http", "--hub-key-file", "/run/lockfamily/hub.pub", "--instance", "web", check_=False)
check(r.returncode != 0 and "-hub" in r.stderr, "the console takes no hub flags", r.stdout + r.stderr)
# An invalid --runtime-gids is refused, never ignored.
r = launcher("console", "--runtime-gids", "docker", check_=False)
check(r.returncode == 3 and "--runtime-gids" in r.stderr, "the console refuses an invalid --runtime-gids", f"exit {r.returncode}\n{r.stdout}{r.stderr}")

# The gate does not start without the hub: lox run gives its flags.
r = launcher("gate", check_=False)
Expand Down
Loading
Loading