From 4b2eaba1ed12db5dcdf46c127e618b923779bdc0 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Fri, 6 Nov 2026 14:10:17 +0000 Subject: [PATCH] cli: check policies offline by default Fixes #3355 --- CHANGELOG.md | 1 + cmd/headscale/cli/check.go | 105 +++++++++++++++++++++- cmd/headscale/cli/check_test.go | 139 +++++++++++++++++++++++++++++ cmd/headscale/cli/policy.go | 77 +++------------- cmd/headscale/cli/root.go | 7 +- cmd/headscale/cli/root_test.go | 5 ++ docs/about/faq.md | 2 +- hscontrol/policy/v2/policy_test.go | 2 +- hscontrol/policy/v2/test.go | 7 +- integration/cli_policy_test.go | 35 ++++---- 10 files changed, 289 insertions(+), 91 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f0345a1e..38872acb0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -178,6 +178,7 @@ is not connected, or refuses is "not found". See [the client docs](https://heads - `--output json` / `--output yaml` now emit the API's shape — camelCase fields, string-encoded IDs, RFC3339 timestamps — instead of the old Protobuf encoding [#3324](https://github.com/juanfont/headscale/pull/3324) - `headscale policy` renames the database-bypass flag from `--bypass-grpc-and-access-database-directly` to `--bypass-server-and-access-database-directly` [#3324](https://github.com/juanfont/headscale/pull/3324) +- `headscale policy check` is now `headscale check policy`. It checks offline by default (syntax, shape, references) and needs no server, database or config. `--database` (was `--bypass-grpc-and-access-database-directly`) and `--server` (was the default) also run `tests` and `sshTests`. [#3355](https://github.com/juanfont/headscale/issues/3355) #### NixOS module diff --git a/cmd/headscale/cli/check.go b/cmd/headscale/cli/check.go index 9bc70daf1..586806d40 100644 --- a/cmd/headscale/cli/check.go +++ b/cmd/headscale/cli/check.go @@ -1,12 +1,113 @@ package cli -import "github.com/spf13/cobra" +import ( + "context" + "fmt" + "net/http" + "os" + + clientv1 "github.com/juanfont/headscale/gen/client/v1" + policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2" + "github.com/spf13/cobra" +) func init() { rootCmd.AddCommand(checkCmd) + + checkPolicyCmd.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format") + checkPolicyCmd.Flags().Bool("database", false, "Open the database directly (no running server required) to resolve users and run tests and sshTests") + checkPolicyCmd.Flags().Bool("server", false, "Ask a running server to check the policy, including tests and sshTests") + checkPolicyCmd.MarkFlagsMutuallyExclusive("database", "server") + mustMarkRequired(checkPolicyCmd, "file") + checkCmd.AddCommand(checkPolicyCmd) } var checkCmd = &cobra.Command{ Use: "check", - Short: "Check configuration or policy without a running server", + Short: "Check configuration or policy files", +} + +var checkPolicyCmd = &cobra.Command{ + Use: "policy", + Short: "Check the Policy file for errors", + Long: ` + Check validates the policy's syntax, shape and references without a server, + database or config. Pass --database to open the database directly, or + --server to ask a running headscale, to also run "tests" and "sshTests" + against the live users and nodes.`, + RunE: func(cmd *cobra.Command, args []string) error { + policyPath, _ := cmd.Flags().GetString("file") + + policyBytes, err := os.ReadFile(policyPath) + if err != nil { + return fmt.Errorf("reading policy file: %w", err) + } + + out := cmd.OutOrStdout() + useDB, _ := cmd.Flags().GetBool("database") + useServer, _ := cmd.Flags().GetBool("server") + + switch { + case useDB: + err = loadConfig() + if err != nil { + return err + } + + d, err := openBypassDB(cmd) + if err != nil { + return err + } + defer d.Close() + + err = validateOfflinePolicy(d, policyBytes) + if err != nil { + return err + } + case useServer: + err = loadConfig() + if err != nil { + return err + } + + policyStr := string(policyBytes) + + err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error { + resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{ + Policy: &policyStr, + }) + if err != nil { + return err + } + + if resp.StatusCode() != http.StatusOK { + return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault) + } + + return nil + }) + if err != nil { + return err + } + default: + var pol *policyv2.Policy + + pol, err = policyv2.ParsePolicy(policyBytes) + if err != nil { + return err + } + + fmt.Fprintln(out, "Policy is valid") + + if pol != nil && (len(pol.Tests) > 0 || len(pol.SSHTests) > 0) { + fmt.Fprintln(out, "tests and sshTests were not run; use --database or --server to run them") + } + + return nil + } + + fmt.Fprintln(out, "Policy is valid") + + return nil + }, } diff --git a/cmd/headscale/cli/check_test.go b/cmd/headscale/cli/check_test.go index 0d61774aa..8b6d5da95 100644 --- a/cmd/headscale/cli/check_test.go +++ b/cmd/headscale/cli/check_test.go @@ -1,8 +1,17 @@ package cli import ( + "bytes" + "fmt" + "os" + "path/filepath" "testing" + "github.com/juanfont/headscale/hscontrol/db" + policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2" + "github.com/juanfont/headscale/hscontrol/types" + "github.com/spf13/cobra" + "github.com/spf13/viper" "github.com/stretchr/testify/require" ) @@ -25,3 +34,133 @@ func TestSkipsInitConfig(t *testing.T) { }) } } + +func newCheckPolicyCmd(t *testing.T, path string, database bool) (*cobra.Command, *bytes.Buffer) { + t.Helper() + + cmd := &cobra.Command{} + cmd.Flags().String("file", path, "") + cmd.Flags().Bool("database", database, "") + cmd.Flags().Bool("server", false, "") + cmd.Flags().Bool("force", true, "") + + var buf bytes.Buffer + + cmd.SetOut(&buf) + + return cmd, &buf +} + +func TestCheckPolicy(t *testing.T) { + const ( + valid = `{"acls":[{"action":"accept","src":["*"],"dst":["*:*"]}]}` + failingTest = `{"acls":[],"tests":[{"src":"alice@","accept":["bob@:22"]}]}` + passingTest = `{"acls":[{"action":"accept","src":["alice@"],"dst":["bob@:22"]}],"tests":[{"src":"alice@","accept":["bob@:22"]}]}` //nolint:gosec // policy fixture + ) + + writePolicy := func(t *testing.T, body string) string { + t.Helper() + + p := filepath.Join(t.TempDir(), "policy.hujson") + require.NoError(t, os.WriteFile(p, []byte(body), 0o600)) + + return p + } + + t.Run("valid", func(t *testing.T) { + cmd, out := newCheckPolicyCmd(t, writePolicy(t, valid), false) + require.NoError(t, checkPolicyCmd.RunE(cmd, nil)) + require.Equal(t, "Policy is valid\n", out.String()) + }) + + t.Run("tests not run offline", func(t *testing.T) { + cmd, out := newCheckPolicyCmd(t, writePolicy(t, failingTest), false) + require.NoError(t, checkPolicyCmd.RunE(cmd, nil)) + require.Contains(t, out.String(), "Policy is valid") + require.Contains(t, out.String(), "tests and sshTests were not run") + }) + + t.Run("undefined group", func(t *testing.T) { + cmd, _ := newCheckPolicyCmd(t, writePolicy(t, `{"acls":[{"action":"accept","src":["group:missing"],"dst":["*:*"]}]}`), false) + require.ErrorIs(t, checkPolicyCmd.RunE(cmd, nil), policyv2.ErrGroupNotDefined) + }) + + t.Run("empty file", func(t *testing.T) { + cmd, out := newCheckPolicyCmd(t, writePolicy(t, ""), false) + require.NoError(t, checkPolicyCmd.RunE(cmd, nil)) + require.Equal(t, "Policy is valid\n", out.String()) + }) + + t.Run("broken config ignored offline", func(t *testing.T) { + bad := filepath.Join(t.TempDir(), "bad.yaml") + require.NoError(t, os.WriteFile(bad, []byte("server_url: ["), 0o600)) + t.Setenv("HEADSCALE_CONFIG", bad) + + cmd, _ := newCheckPolicyCmd(t, writePolicy(t, valid), false) + require.NoError(t, checkPolicyCmd.RunE(cmd, nil)) + }) + + for _, tt := range []struct { + name string + policy string + invalid bool + }{ + {"database passing", passingTest, false}, + {"database failing", failingTest, true}, + } { + t.Run(tt.name, func(t *testing.T) { + viper.Reset() + t.Cleanup(viper.Reset) + + dir := t.TempDir() + configPath := filepath.Join(dir, "config.yaml") + config := fmt.Sprintf(`server_url: https://headscale.example.com +noise: + private_key_path: noise_private.key +prefixes: + v4: 100.64.0.0/10 +database: + type: sqlite3 + sqlite: + path: %q +policy: + mode: database +dns: + magic_dns: false + override_local_dns: false +`, filepath.Join(dir, "headscale.db")) + require.NoError(t, os.WriteFile(configPath, []byte(config), 0o600)) + + old := cfgFile + cfgFile = configPath + + t.Cleanup(func() { cfgFile = old }) + + require.NoError(t, types.LoadConfig(configPath, true)) + + cfg, err := types.LoadServerConfig() + require.NoError(t, err) + + database, err := db.NewHeadscaleDatabase(cfg) + require.NoError(t, err) + + for _, name := range []string{"alice", "bob"} { + user := database.CreateUserForTest(name) + database.CreateRegisteredNodeForTest(user, name+"-node") + } + + require.NoError(t, database.Close()) + viper.Reset() + + cmd, out := newCheckPolicyCmd(t, writePolicy(t, tt.policy), true) + + err = checkPolicyCmd.RunE(cmd, nil) + if tt.invalid { + require.ErrorContains(t, err, "test(s) failed") + } else { + require.NoError(t, err) + require.Equal(t, "Policy is valid\n", out.String()) + } + }) + } +} diff --git a/cmd/headscale/cli/policy.go b/cmd/headscale/cli/policy.go index 6c34b2d7d..aa0fbc313 100644 --- a/cmd/headscale/cli/policy.go +++ b/cmd/headscale/cli/policy.go @@ -20,6 +20,8 @@ const ( var errAborted = errors.New("command aborted by user") +var errPolicyCheckRemoved = errors.New(`"policy check" was removed in 0.30, use "headscale check policy"`) + // bypassDatabase opens the database directly, bypassing the running server. // The caller must close the returned handle. func bypassDatabase() (*db.HSDatabase, error) { @@ -81,11 +83,19 @@ func init() { setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running") mustMarkRequired(setPolicy, "file") policyCmd.AddCommand(setPolicy) + policyCmd.AddCommand(removedPolicyCheckCmd) +} - checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format") - checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no running server required) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.") - mustMarkRequired(checkPolicy, "file") - policyCmd.AddCommand(checkPolicy) +// removedPolicyCheckCmd turns "unknown shorthand flag: 'f'" into a pointer to +// the replacement. +var removedPolicyCheckCmd = &cobra.Command{ + Use: "check", + Hidden: true, + DisableFlagParsing: true, + Args: cobra.ArbitraryArgs, + RunE: func(*cobra.Command, []string) error { + return errPolicyCheckRemoved + }, } var policyCmd = &cobra.Command{ @@ -199,62 +209,3 @@ var setPolicy = &cobra.Command{ return nil }, } - -var checkPolicy = &cobra.Command{ - Use: "check", - Short: "Check the Policy file for errors", - Long: ` - Check validates the policy against the server's live users and nodes, - running any "tests" or "sshTests" block. By default the command calls a - running headscale over its API; pass --` + bypassFlag + ` to - open the database directly when headscale is not running.`, - RunE: func(cmd *cobra.Command, args []string) error { - policyPath, _ := cmd.Flags().GetString("file") - - policyBytes, err := os.ReadFile(policyPath) - if err != nil { - return fmt.Errorf("reading policy file: %w", err) - } - - if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass { - d, err := openBypassDB(cmd) - if err != nil { - return err - } - defer d.Close() - - err = validateOfflinePolicy(d, policyBytes) - if err != nil { - return err - } - - fmt.Println("Policy is valid") - - return nil - } - - policyStr := string(policyBytes) - - err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error { - resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{ - Policy: &policyStr, - }) - if err != nil { - return err - } - - if resp.StatusCode() != http.StatusOK { - return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault) - } - - return nil - }) - if err != nil { - return err - } - - fmt.Println("Policy is valid") - - return nil - }, -} diff --git a/cmd/headscale/cli/root.go b/cmd/headscale/cli/root.go index cfe32fea5..ad2fbbe12 100644 --- a/cmd/headscale/cli/root.go +++ b/cmd/headscale/cli/root.go @@ -40,13 +40,14 @@ func init() { }) } -// skipsInitConfig reports whether args select the check command group, which -// must work without a loadable config. Find runs lazily because init order +// skipsInitConfig reports whether args select the check command group or a +// removed-command stub, which must work without a loadable config. Find runs lazily because init order // across files is not guaranteed to have registered every command. func skipsInitConfig(args []string) bool { cmd, _, err := rootCmd.Find(args) - return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd) + return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd || + cmd == removedPolicyCheckCmd) } func loadConfig() error { diff --git a/cmd/headscale/cli/root_test.go b/cmd/headscale/cli/root_test.go index 9f444ee45..bcc677f4b 100644 --- a/cmd/headscale/cli/root_test.go +++ b/cmd/headscale/cli/root_test.go @@ -416,3 +416,8 @@ dns: }) } } + +func TestRemovedPolicyCheck(t *testing.T) { + require.ErrorIs(t, removedPolicyCheckCmd.RunE(removedPolicyCheckCmd, nil), errPolicyCheckRemoved) + require.True(t, skipsInitConfig([]string{"policy", "check", "-f", "x"})) +} diff --git a/docs/about/faq.md b/docs/about/faq.md index 101112337..1159fb0a4 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -153,7 +153,7 @@ Headscale checks if the policy is valid during startup and refuses to start if i indicates which part of the policy is invalid. Follow these steps to fix your policy: - Dump the policy to a file: `headscale policy get --bypass-server-and-access-database-directly > policy.json` -- Edit and fixup `policy.json`. Use the command `headscale policy check --file policy.json` to validate the policy. +- Edit and fixup `policy.json`. Use the command `headscale check policy --file policy.json` to validate the policy. - Load the modified policy: `headscale policy set --bypass-server-and-access-database-directly --file policy.json` - Start Headscale as usual. diff --git a/hscontrol/policy/v2/policy_test.go b/hscontrol/policy/v2/policy_test.go index 4a2d38393..5ee05fdca 100644 --- a/hscontrol/policy/v2/policy_test.go +++ b/hscontrol/policy/v2/policy_test.go @@ -3176,7 +3176,7 @@ func TestSetPolicy_DuplicateUsername(t *testing.T) { require.NotNil(t, filter, "filter must remain populated after rejected SetPolicy") } -// Empty users → syntax-only check, used by `headscale policy check`. +// Empty users → policy manager skips user-reference validation (syntax-only). func TestValidateUserReferences_EmptyUsersTolerant(t *testing.T) { polB := []byte(`{ "groups": {"group:admins": ["yala@"]}, diff --git a/hscontrol/policy/v2/test.go b/hscontrol/policy/v2/test.go index dde9b208a..9928cd9a8 100644 --- a/hscontrol/policy/v2/test.go +++ b/hscontrol/policy/v2/test.go @@ -17,9 +17,10 @@ import ( // Tailscale's policy file `tests` block validates a policy against operator // assertions: from a given src, named dst:port pairs must be accepted, and -// (optionally) other dst:port pairs must be denied. They run at user-write -// boundaries — `headscale policy set`, file-mode reload after a change, -// `headscale policy check` — and reject the write if any assertion fails. +// (optionally) other dst:port pairs must be denied. `headscale policy set` +// and file-mode reload after a change reject the write if any assertion +// fails; `headscale check policy --database` and `--server` run the +// assertions and report failures without applying the policy. // Boot-time reload of an already-stored policy does not run them, so a // stale referenced entity (e.g. a deleted user) cannot lock the server out. // diff --git a/integration/cli_policy_test.go b/integration/cli_policy_test.go index 0c826c4c2..9d0f18204 100644 --- a/integration/cli_policy_test.go +++ b/integration/cli_policy_test.go @@ -15,15 +15,15 @@ import ( "tailscale.com/tailcfg" ) -// TestPolicyCheckCommand exercises `headscale policy check` across the +// TestPolicyCheckCommand exercises `headscale check policy` across the // matrix that nblock asked about on PR #3229: // // - policyMode: server runs with policy_mode=file vs policy_mode=database. // `check` reads from `--file`, so the server-side mode should not // change the outcome; running both proves that. // - fixture: ACL only, ACL with passing tests, ACL with failing tests. -// - bypass: no-bypass talks to the server over gRPC; bypass opens the -// database directly. +// - checkMode: offline parses only; database opens the database directly; +// server asks the running server. Only the last two run tests. // // Each policy mode shares one scenario across its sequential checks because // policy_mode is fixed at boot. The two users + two nodes give the tests @@ -82,29 +82,24 @@ func TestPolicyCheckCommand(t *testing.T) { type row struct { name string fixture fixture - bypass bool + checkMode string wantErr string wantStdout string } modes := []types.PolicyMode{types.PolicyModeFile, types.PolicyModeDB} - bypasses := []bool{false, true} - rows := make([]row, 0, len(fixtures)*len(bypasses)) + checkModes := []string{"offline", "database", "server"} + rows := make([]row, 0, len(fixtures)*len(checkModes)) for _, f := range fixtures { - for _, bypass := range bypasses { - suffix := "no-bypass" - if bypass { - suffix = "bypass" - } - + for _, checkMode := range checkModes { r := row{ - name: f.name + "-" + suffix, + name: f.name + "-" + checkMode, fixture: f, - bypass: bypass, + checkMode: checkMode, wantStdout: "Policy is valid", } - if f.name == "acl-plus-failing-tests" { + if f.name == "acl-plus-failing-tests" && checkMode != "offline" { r.wantErr = "test(s) failed" r.wantStdout = "" } @@ -175,12 +170,16 @@ func TestPolicyCheckCommand(t *testing.T) { }, integrationutil.StatusReadyTimeout, integrationutil.FastPoll, "policy check must not alter the live policy") }) - cmd := []string{"headscale", "policy", "check", "-f", policyFilePath} //nolint:goconst // CLI invocation - if tt.bypass { + cmd := []string{"headscale", "check", "policy", "-f", policyFilePath} //nolint:goconst // CLI invocation + + switch tt.checkMode { + case "database": // --force suppresses the "is the server running?" // confirmation prompt so the command can run // non-interactively under the test harness. - cmd = append(cmd, "--bypass-server-and-access-database-directly", "--force") + cmd = append(cmd, "--database", "--force") + case "server": + cmd = append(cmd, "--server") } stdout, err := headscale.Execute(cmd)