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) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-04 12:34:47 +02:00
1 parent b4bdd250af
commit 13e6f19301
13 files changed
+412

No files matched your search

+1
View File
@@ -160,6 +160,7 @@ func newCtlCmd() *cobra.Command {
newWeightsCmd(client, &asJSON),
newCapacityCmd(client, &asJSON),
newQuotaCmd(client, &asJSON),
newGuardCmd(client, &asJSON),
newUsageCmd(client, &asJSON),
newCertCmd(),
)
+84
View File
@@ -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
}
+19
View File
@@ -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)
+10
View File
@@ -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
}
+3
View File
@@ -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) {
+142
View File
@@ -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))
}
+59
View File
@@ -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)
}
}
+4
View File
@@ -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) {
+1
View File
@@ -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.
+39
View File
@@ -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
}
+27
View File
@@ -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")
}
}
@@ -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)
);
@@ -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)
);