From 13e6f1930159e039f98e6ffac182bd6aa030fb7e Mon Sep 17 00:00:00 2001 From: Ilker Manap Date: Sun, 4 Oct 2026 12:34:47 +0200 Subject: [PATCH] Attach guard policies to scopes: store, admin API and ctl guard; run the gate when server.yaml defines policies Co-Authored-By: Claude Opus 5.5 (1M context) --- internal/cli/ctl.go | 1 + internal/cli/guard.go | 84 +++++++++++ internal/cli/server.go | 19 +++ internal/config/config.go | 10 ++ internal/control/adminapi/api.go | 3 + internal/control/adminapi/guard.go | 142 ++++++++++++++++++ internal/control/adminapi/guard_test.go | 59 ++++++++ internal/guard/gate.go | 4 + internal/store/copy.go | 1 + internal/store/guard.go | 39 +++++ internal/store/guard_test.go | 27 ++++ .../postgres/0019_guard_attachments.sql | 12 ++ .../sqlite/0019_guard_attachments.sql | 11 ++ 13 files changed, 412 insertions(+) create mode 100644 internal/cli/guard.go create mode 100644 internal/control/adminapi/guard.go create mode 100644 internal/control/adminapi/guard_test.go create mode 100644 internal/store/guard.go create mode 100644 internal/store/guard_test.go create mode 100644 internal/store/migrations/postgres/0019_guard_attachments.sql create mode 100644 internal/store/migrations/sqlite/0019_guard_attachments.sql diff --git a/internal/cli/ctl.go b/internal/cli/ctl.go index b54ab3c..83fbee4 100644 --- a/internal/cli/ctl.go +++ b/internal/cli/ctl.go @@ -160,6 +160,7 @@ func newCtlCmd() *cobra.Command { newWeightsCmd(client, &asJSON), newCapacityCmd(client, &asJSON), newQuotaCmd(client, &asJSON), + newGuardCmd(client, &asJSON), newUsageCmd(client, &asJSON), newCertCmd(), ) diff --git a/internal/cli/guard.go b/internal/cli/guard.go new file mode 100644 index 0000000..a68af36 --- /dev/null +++ b/internal/cli/guard.go @@ -0,0 +1,84 @@ +package cli + +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/spf13/cobra" + + "gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi" +) + +func newGuardCmd(client func() *ctlClient, asJSON *bool) *cobra.Command { + c := &cobra.Command{ + Use: "guard", + Short: "Guardrail policies: which apply where", + Long: "Policies are defined in server.yaml under guard.policies — what requests and\n" + + "answers are checked for (personal data, secrets, prompt injection, patterns,\n" + + "tools) and what is done: flag, redact or block. guard.default applies to\n" + + "every request; attach others to an organization, team, project, user or\n" + + "key, and everything below is judged by them too. Policies narrow: one\n" + + "attached lower can tighten, never loosen, what applies above it.\n\n" + + "Targets are written org:Acme, team:Acme/ml, project:Acme/ml/training (or\n" + + "with IDs), key:KEY-ID or user:USER-ID. An attachment applies at once.", + } + c.AddCommand(&cobra.Command{ + Use: "list", + Short: "The policies, and where each is attached", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + var v adminapi.GuardView + if err := client().get(cmd.Context(), "/api/v1/guard", &v); err != nil { + return err + } + if *asJSON { + return json.NewEncoder(cmd.OutOrStdout()).Encode(v) + } + out := cmd.OutOrStdout() + fmt.Fprintf(out, "Policies: %s\n", strings.Join(v.Policies, ", ")) + def := strings.Join(v.Default, ", ") + if def == "" { + def = "none" + } + fmt.Fprintf(out, "Applied to every request: %s\n", def) + if len(v.Attachments) == 0 { + fmt.Fprintln(out, "Attached nowhere else.") + return nil + } + fmt.Fprintln(out) + w := tab() + fmt.Fprintln(w, "SCOPE\tWHO\tPOLICY") + for _, a := range v.Attachments { + who := a.ScopeID + if a.Name != "" { + who = a.Name + " (" + a.ScopeID + ")" + } + fmt.Fprintf(w, "%s\t%s\t%s\n", a.Scope, who, a.Policy) + } + return w.Flush() + }, + }) + for _, verb := range []struct { + use, short, method, done string + }{ + {"attach", "Apply a policy to a scope and everything below it", "POST", "attached to"}, + {"detach", "Stop applying a policy to a scope", "DELETE", "detached from"}, + } { + c.AddCommand(&cobra.Command{ + Use: verb.use + " TARGET POLICY", + Short: verb.short, + Example: " llmgw ctl guard " + verb.use + " project:Acme/finance/payroll finance", + Args: cobra.ExactArgs(2), + RunE: func(cmd *cobra.Command, args []string) error { + body, _ := json.Marshal(map[string]string{"target": args[0], "policy": args[1]}) + if err := client().do(cmd.Context(), verb.method, "/api/v1/guard/attachments", json.RawMessage(body), nil); err != nil { + return err + } + fmt.Fprintf(cmd.OutOrStdout(), "%s %s %s\n", args[1], verb.done, args[0]) + return nil + }, + }) + } + return c +} diff --git a/internal/cli/server.go b/internal/cli/server.go index 4a7ce32..5f4b1ba 100644 --- a/internal/cli/server.go +++ b/internal/cli/server.go @@ -33,6 +33,7 @@ import ( llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1" "gitea.mynodes.xyz/ilker/llmgw/internal/config" "gitea.mynodes.xyz/ilker/llmgw/internal/control" + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" "gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi" "gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc" "gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog" @@ -117,6 +118,21 @@ func newServerCmd() *cobra.Command { if err != nil { return err } + // Guardrails, when server.yaml defines any. Attachments to + // parts of the tenancy tree live in the store; without one, only + // guard.default applies. + var gate *guard.Gate + if len(cfg.Guard.Policies) > 0 { + var att guard.Attachments + if st := rt.Store(); st != nil { + att = st + } + if gate, err = guard.NewGate(cfg.Guard, att, log); err != nil { + return fmt.Errorf("guard: %w", err) + } + rt.SetGuard(gate) + log.Info("guardrails on", "policies", len(cfg.Guard.Policies), "default", cfg.Guard.Default) + } ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM) defer stop() @@ -242,6 +258,9 @@ func newServerCmd() *cobra.Command { } adminAPI = api api.SetReleases(cfg.Releases) + if st := rt.Store(); st != nil && gate != nil { + api.SetGuard(&adminapi.GuardAdmin{Library: cfg.Guard, Store: st, Invalidate: gate.Invalidate}) + } if st := rt.Store(); st != nil { // Removing a node revokes its certificate. api.SetRevoker(st.RevokeNode) diff --git a/internal/config/config.go b/internal/config/config.go index dc6bb3f..c03c568 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -18,6 +18,7 @@ import ( "github.com/knadh/koanf/v2" "gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog" + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" "gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf" ) @@ -121,6 +122,12 @@ type Server struct { // Empty means /var/backups/llmgw-server. BackupDir string `koanf:"backup_dir"` + // Guard is the library of guardrail policies: what requests and answers + // are checked for, and what is done. Applied to every request through + // guard.default, and to parts of the tenancy tree by attaching them + // (llmgw ctl guard attach). Empty checks nothing. + Guard guard.Config `koanf:"guard"` + // FirewallNetworks are networks, besides those each machine reaches the // cluster on, that llmgw's internal ports answer: a monitoring host on // another subnet, nodes behind a router. Written into every machine's @@ -639,6 +646,9 @@ func (s Server) Validate() error { if _, err := s.FirewallAllow(); err != nil { return err } + if err := s.Guard.Validate(); err != nil { + return err + } if err := s.AgentTLS.Validate(); err != nil { return err } diff --git a/internal/control/adminapi/api.go b/internal/control/adminapi/api.go index 9b04dab..c91b968 100644 --- a/internal/control/adminapi/api.go +++ b/internal/control/adminapi/api.go @@ -48,6 +48,8 @@ type API struct { serve *modelserve.Server // history is the Prometheus the console's charts read from. history History + // guard is the guardrail policies' library and attachments. + guard *GuardAdmin // revoke records a removed node, so its certificate is refused. revoke func(ctx context.Context, nodeID string, at time.Time) error @@ -77,6 +79,7 @@ func (a *API) Register(mux *http.ServeMux) { mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel) mux.HandleFunc("POST /api/v1/models/{name}/resources", a.setResources) a.registerQuotas(mux) + a.registerGuard(mux) mux.HandleFunc("POST /api/v1/models/{name}/adapters", a.setAdapters) mux.HandleFunc("GET /api/v1/models/{name}/target", a.target) mux.HandleFunc("POST /api/v1/models/{name}/class", func(w http.ResponseWriter, r *http.Request) { diff --git a/internal/control/adminapi/guard.go b/internal/control/adminapi/guard.go new file mode 100644 index 0000000..33d76da --- /dev/null +++ b/internal/control/adminapi/guard.go @@ -0,0 +1,142 @@ +package adminapi + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "slices" + "strings" + + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" +) + +// GuardStore is where policy attachments are kept. +type GuardStore interface { + GuardAttachments(ctx context.Context) ([]guard.Attachment, error) + AttachGuard(ctx context.Context, a guard.Attachment, by string) error + DetachGuard(ctx context.Context, a guard.Attachment) (bool, error) +} + +// GuardAdmin is what the guard endpoints need: the library from server.yaml, +// the store, and a way to have the gate read attachments again at once. +type GuardAdmin struct { + Library guard.Config + Store GuardStore + Invalidate func() +} + +// SetGuard enables the guard endpoints. +func (a *API) SetGuard(g *GuardAdmin) { a.guard = g } + +// GuardView is the library and where its policies are attached. +type GuardView struct { + Policies []string `json:"policies"` + Default []string `json:"default"` + Attachments []GuardAttachmentView `json:"attachments"` +} + +// GuardAttachmentView is one attachment, with the name people know its +// scope by. +type GuardAttachmentView struct { + guard.Attachment + Name string `json:"name,omitempty"` +} + +// guardTarget reads where a policy is to be attached. +func (a *API) guardTarget(ctx context.Context, target string) (guard.Attachment, error) { + kind, what, ok := strings.Cut(strings.TrimSpace(target), ":") + what = strings.TrimSpace(what) + if !ok || what == "" { + return guard.Attachment{}, fmt.Errorf("%q is not org:, team:, project:, key: or user: and what", target) + } + switch kind { + case "key", "user": + return guard.Attachment{Scope: kind, ScopeID: what}, nil + case "org", "team", "project": + if a.quotas == nil { + return guard.Attachment{Scope: kind, ScopeID: what}, nil + } + _, id, _, err := a.resolveScope(ctx, target) + if err != nil { + return guard.Attachment{}, err + } + return guard.Attachment{Scope: kind, ScopeID: id}, nil + } + return guard.Attachment{}, fmt.Errorf("%q: attach to org, team, project, key or user", kind) +} + +func (a *API) registerGuard(mux *http.ServeMux) { + mux.HandleFunc("GET /api/v1/guard", func(w http.ResponseWriter, r *http.Request) { + if a.guard == nil { + writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml") + return + } + att, err := a.guard.Store.GuardAttachments(r.Context()) + if err != nil { + writeError(w, http.StatusInternalServerError, err.Error()) + return + } + v := GuardView{Default: a.guard.Library.Default, Attachments: []GuardAttachmentView{}} + var names map[string]string + if a.quotas != nil { + names, _ = a.scopeNames(r.Context()) + } + for _, at := range att { + v.Attachments = append(v.Attachments, GuardAttachmentView{Attachment: at, Name: names[at.Scope+":"+at.ScopeID]}) + } + for name := range a.guard.Library.Policies { + v.Policies = append(v.Policies, name) + } + slices.Sort(v.Policies) + writeJSON(w, http.StatusOK, v) + }) + change := func(attach bool) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + if a.guard == nil { + writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml") + return + } + var at struct { + // Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT + // (or the ID after the colon), key:KEY-ID or user:USER-ID. + Target string `json:"target"` + Policy string `json:"policy"` + } + if err := json.NewDecoder(r.Body).Decode(&at); err != nil { + writeError(w, http.StatusBadRequest, err.Error()) + return + } + att, err := a.guardTarget(r.Context(), at.Target) + if err != nil { + writeError(w, http.StatusBadRequest, err.Error()) + return + } + att.Policy = at.Policy + if _, ok := a.guard.Library.Policies[att.Policy]; !ok && attach { + writeError(w, http.StatusBadRequest, fmt.Sprintf("no policy %q in server.yaml's guard.policies", att.Policy)) + return + } + changed := true + if attach { + err = a.guard.Store.AttachGuard(r.Context(), att, actorOf(r)) + } else { + changed, err = a.guard.Store.DetachGuard(r.Context(), att) + } + if err != nil { + writeError(w, http.StatusInternalServerError, err.Error()) + return + } + if !changed { + writeError(w, http.StatusNotFound, "no such attachment") + return + } + if a.guard.Invalidate != nil { + a.guard.Invalidate() + } + writeJSON(w, http.StatusOK, att) + } + } + mux.HandleFunc("POST /api/v1/guard/attachments", change(true)) + mux.HandleFunc("DELETE /api/v1/guard/attachments", change(false)) +} diff --git a/internal/control/adminapi/guard_test.go b/internal/control/adminapi/guard_test.go new file mode 100644 index 0000000..5f7c18b --- /dev/null +++ b/internal/control/adminapi/guard_test.go @@ -0,0 +1,59 @@ +package adminapi + +import ( + "context" + "slices" + "testing" + + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" +) + +type memGuard struct{ att []guard.Attachment } + +func (m *memGuard) GuardAttachments(context.Context) ([]guard.Attachment, error) { return m.att, nil } +func (m *memGuard) AttachGuard(_ context.Context, a guard.Attachment, _ string) error { + if !slices.Contains(m.att, a) { + m.att = append(m.att, a) + } + return nil +} +func (m *memGuard) DetachGuard(_ context.Context, a guard.Attachment) (bool, error) { + n := len(m.att) + m.att = slices.DeleteFunc(m.att, func(x guard.Attachment) bool { return x == a }) + return len(m.att) < n, nil +} + +func TestGuardPoliciesAreAttachedByTarget(t *testing.T) { + a, _ := setup(t, testModels()) + if code := call(t, a, "GET", "/api/v1/guard", "", nil); code != 501 { + t.Errorf("without policies: %d", code) + } + st := &memGuard{} + invalidated := 0 + a.SetGuard(&GuardAdmin{ + Library: guard.Config{Default: []string{"base"}, Policies: map[string]guard.Policy{"base": {}, "finance": {}}}, + Store: st, Invalidate: func() { invalidated++ }, + }) + if code := call(t, a, "POST", "/api/v1/guard/attachments", `{"target":"key:k1","policy":"finance"}`, nil); code != 200 { + t.Fatalf("attach: %d", code) + } + if invalidated != 1 || len(st.att) != 1 || st.att[0] != (guard.Attachment{Scope: "key", ScopeID: "k1", Policy: "finance"}) { + t.Errorf("stored %v, invalidated %d", st.att, invalidated) + } + for _, bad := range []string{`{"target":"key:k1","policy":"nope"}`, `{"target":"galaxy:x","policy":"finance"}`, `{"target":"key:","policy":"finance"}`} { + if code := call(t, a, "POST", "/api/v1/guard/attachments", bad, nil); code != 400 { + t.Errorf("%s: %d", bad, code) + } + } + var v GuardView + if code := call(t, a, "GET", "/api/v1/guard", "", &v); code != 200 || len(v.Attachments) != 1 || + !slices.Equal(v.Policies, []string{"base", "finance"}) || !slices.Equal(v.Default, []string{"base"}) { + t.Errorf("%d %+v", code, v) + } + if code := call(t, a, "DELETE", "/api/v1/guard/attachments", `{"target":"key:k1","policy":"finance"}`, nil); code != 200 || len(st.att) != 0 { + t.Errorf("detach: %d %v", code, st.att) + } + if code := call(t, a, "DELETE", "/api/v1/guard/attachments", `{"target":"key:k1","policy":"finance"}`, nil); code != 404 { + t.Errorf("detach again: %d", code) + } +} diff --git a/internal/guard/gate.go b/internal/guard/gate.go index c923432..c29adf1 100644 --- a/internal/guard/gate.go +++ b/internal/guard/gate.go @@ -101,6 +101,10 @@ func (g *Gate) reload(ctx context.Context) { g.merged = map[string]Policy{} } +// Invalidate has attachments read again on the next request: one just made +// applies at once rather than within attachmentsTTL. +func (g *Gate) Invalidate() { g.reload(context.Background()) } + // Policy is the policy in force for a request, and the names it was made // from. func (g *Gate) Policy(s Subject) (Policy, string) { diff --git a/internal/store/copy.go b/internal/store/copy.go index a2d9716..af46262 100644 --- a/internal/store/copy.go +++ b/internal/store/copy.go @@ -54,6 +54,7 @@ var copyOrder = []string{ "control_planes", // Or a removed node's certificate would work again in the new store. "revoked_nodes", + "guard_attachments", } // notCopied are tables deliberately left behind. diff --git a/internal/store/guard.go b/internal/store/guard.go new file mode 100644 index 0000000..342aaa4 --- /dev/null +++ b/internal/store/guard.go @@ -0,0 +1,39 @@ +package store + +import ( + "context" + "database/sql" + "time" + + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" +) + +// GuardAttachments lists which policy is attached where. +func (s *DB) GuardAttachments(ctx context.Context) ([]guard.Attachment, error) { + return queryAll(ctx, s.db, `SELECT scope, scope_id, policy FROM guard_attachments ORDER BY scope, scope_id, policy`, nil, + func(rows *sql.Rows) (guard.Attachment, error) { + var a guard.Attachment + err := rows.Scan(&a.Scope, &a.ScopeID, &a.Policy) + return a, err + }) +} + +// AttachGuard attaches a policy to a scope; attaching it again changes +// nothing. +func (s *DB) AttachGuard(ctx context.Context, a guard.Attachment, by string) error { + _, err := s.db.ExecContext(ctx, `INSERT INTO guard_attachments (scope, scope_id, policy, added_at, added_by) + VALUES (?, ?, ?, ?, ?) ON CONFLICT (scope, scope_id, policy) DO NOTHING`, + a.Scope, a.ScopeID, a.Policy, millis(time.Now()), by) + return err +} + +// DetachGuard removes one attachment, reporting whether it was there. +func (s *DB) DetachGuard(ctx context.Context, a guard.Attachment) (bool, error) { + res, err := s.db.ExecContext(ctx, `DELETE FROM guard_attachments WHERE scope = ? AND scope_id = ? AND policy = ?`, + a.Scope, a.ScopeID, a.Policy) + if err != nil { + return false, err + } + n, _ := res.RowsAffected() + return n > 0, nil +} diff --git a/internal/store/guard_test.go b/internal/store/guard_test.go new file mode 100644 index 0000000..e0ded47 --- /dev/null +++ b/internal/store/guard_test.go @@ -0,0 +1,27 @@ +package store + +import ( + "testing" + + "gitea.mynodes.xyz/ilker/llmgw/internal/guard" +) + +func TestAGuardPolicyIsAttachedOnceAndDetached(t *testing.T) { + db := capacityStore(t) + ctx := t.Context() + a := guard.Attachment{Scope: "project", ScopeID: "p1", Policy: "finance"} + for range 2 { + if err := db.AttachGuard(ctx, a, "ilker"); err != nil { + t.Fatal(err) + } + } + if got, err := db.GuardAttachments(ctx); err != nil || len(got) != 1 || got[0] != a { + t.Fatalf("%v %v", got, err) + } + if ok, err := db.DetachGuard(ctx, a); !ok || err != nil { + t.Errorf("detach: %v %v", ok, err) + } + if ok, _ := db.DetachGuard(ctx, a); ok { + t.Error("detached twice") + } +} diff --git a/internal/store/migrations/postgres/0019_guard_attachments.sql b/internal/store/migrations/postgres/0019_guard_attachments.sql new file mode 100644 index 0000000..daac548 --- /dev/null +++ b/internal/store/migrations/postgres/0019_guard_attachments.sql @@ -0,0 +1,12 @@ +-- Ported from the SQLite migration of the same number. +-- Which guard policies apply where: a policy from server.yaml's library, +-- attached to an organization, team, project, user or key. Everything below +-- an attachment is judged by it too. +CREATE TABLE guard_attachments ( + scope TEXT NOT NULL, + scope_id TEXT NOT NULL, + policy TEXT NOT NULL, + added_at BIGINT NOT NULL, + added_by TEXT NOT NULL DEFAULT '', + PRIMARY KEY (scope, scope_id, policy) +); diff --git a/internal/store/migrations/sqlite/0019_guard_attachments.sql b/internal/store/migrations/sqlite/0019_guard_attachments.sql new file mode 100644 index 0000000..5d35380 --- /dev/null +++ b/internal/store/migrations/sqlite/0019_guard_attachments.sql @@ -0,0 +1,11 @@ +-- Which guard policies apply where: a policy from server.yaml's library, +-- attached to an organization, team, project, user or key. Everything below +-- an attachment is judged by it too. +CREATE TABLE guard_attachments ( + scope TEXT NOT NULL, + scope_id TEXT NOT NULL, + policy TEXT NOT NULL, + added_at INTEGER NOT NULL, + added_by TEXT NOT NULL DEFAULT '', + PRIMARY KEY (scope, scope_id, policy) +);