From ccdc07fe0c03d93fe6f96eb915f051e426cfc3e2 Mon Sep 17 00:00:00 2001 From: Ilker Manap Date: Sun, 4 Oct 2026 12:27:23 +0200 Subject: [PATCH] Guard policies: a library in server.yaml, merged so nothing below loosens what is above Co-Authored-By: Claude Opus 5.5 (1M context) --- internal/guard/policy.go | 258 ++++++++++++++++++++++++++++++++++ internal/guard/policy_test.go | 64 +++++++++ 2 files changed, 322 insertions(+) create mode 100644 internal/guard/policy.go create mode 100644 internal/guard/policy_test.go diff --git a/internal/guard/policy.go b/internal/guard/policy.go new file mode 100644 index 0000000..673981c --- /dev/null +++ b/internal/guard/policy.go @@ -0,0 +1,258 @@ +package guard + +import ( + "fmt" + "regexp" + "slices" + "strings" + + "gitea.mynodes.xyz/ilker/llmgw/internal/guard/detect" +) + +// Config is the gateway's policy library, from server.yaml's guard: section. +// +// guard: +// default: [baseline] +// policies: +// baseline: +// input: {pii: {secret: block, card: redact}, injection: flag} +// output: {pii: {secret: block}} +// finance: +// mode: enforce +// fail: closed +// input: {pii: {iban: redact, tckn: redact}} +// +// Policies are attached to parts of the tenancy tree in the store; Default +// applies to every request. +type Config struct { + Default []string `koanf:"default"` + Policies map[string]Policy `koanf:"policies"` +} + +// Policy is one named set of rules. +type Policy struct { + // Mode: enforce acts, shadow only records what it would have done, off + // does nothing. Empty is enforce. + Mode string `koanf:"mode"` + // Fail: what happens when a policy cannot judge — a judge model down or + // over its latency budget. open serves, closed refuses. Empty is open. + Fail string `koanf:"fail"` + // NoStore keeps nothing of the request: no stored conversation, no + // memory notes, no prefix routing, no fallback outside the cluster. + NoStore bool `koanf:"no_store"` + + Input Rules `koanf:"input"` + Output Rules `koanf:"output"` + Tools Tools `koanf:"tools"` + + // MaxOutputTokens is put in a request that asks for no limit; one + // asking for more is lowered to it. + MaxOutputTokens int `koanf:"max_output_tokens"` + // SystemPrompt is put before every request's messages. + SystemPrompt string `koanf:"system_prompt"` + // DropClientSystem removes the caller's own system and developer + // messages, so only the pinned prompt instructs the model. + DropClientSystem bool `koanf:"drop_client_system"` + // Stream: sentence scans a streamed answer a sentence at a time, + // releasing each once it passes; buffer_all holds the whole answer + // until it is judged. Empty is sentence. + Stream string `koanf:"stream"` +} + +// Rules are what one direction of text is checked for. +type Rules struct { + // PII maps a kind (email, phone, iban, card, tckn, ip, secret) to what is + // done when it is found: flag, redact or block. + PII map[string]string `koanf:"pii"` + // Injection is what is done on signs of prompt injection: flag or block. + Injection string `koanf:"injection"` + // Deny are patterns, matched against the text as a model reads it. + Deny []Pattern `koanf:"deny"` + // MaxChars refuses text longer than this; zero is no limit. + MaxChars int `koanf:"max_chars"` +} + +// Pattern is a named regular expression and what its match does. +type Pattern struct { + Name string `koanf:"name"` + Regex string `koanf:"regex"` + Action string `koanf:"action"` +} + +// Tools are rules for tool definitions and calls. +type Tools struct { + // Allow, when set, are the only tool names a request may offer and a + // model may call. + Allow []string `koanf:"allow"` + // Deny are tool names never offered or called. + Deny []string `koanf:"deny"` + // OnDenied is strip (the tool is removed from the request) or block. + // Empty is strip. + OnDenied string `koanf:"on_denied"` + // MaxCallsPerTurn stops an answer calling more tools than this. + MaxCallsPerTurn int `koanf:"max_calls_per_turn"` + // ValidateArguments checks a call's arguments against the parameters + // schema the request declared for the tool. + ValidateArguments bool `koanf:"validate_arguments"` +} + +var actions = map[string]Action{"flag": Flag, "redact": Redact, "block": Block} + +// Validate checks the library. +func (c Config) Validate() error { + for _, d := range c.Default { + if _, ok := c.Policies[d]; !ok { + return fmt.Errorf("guard.default names %q, which guard.policies does not define", d) + } + } + for name, p := range c.Policies { + if err := p.validate(); err != nil { + return fmt.Errorf("guard.policies.%s: %w", name, err) + } + } + return nil +} + +func (p Policy) validate() error { + switch p.Mode { + case "", "enforce", "shadow", "off": + default: + return fmt.Errorf("mode is %q: enforce, shadow or off", p.Mode) + } + switch p.Fail { + case "", "open", "closed": + default: + return fmt.Errorf("fail is %q: open or closed", p.Fail) + } + switch p.Stream { + case "", "sentence", "buffer_all": + default: + return fmt.Errorf("stream is %q: sentence or buffer_all", p.Stream) + } + switch p.Tools.OnDenied { + case "", "strip", "block": + default: + return fmt.Errorf("tools.on_denied is %q: strip or block", p.Tools.OnDenied) + } + for dir, r := range map[string]Rules{"input": p.Input, "output": p.Output} { + for kind, a := range r.PII { + if !slices.Contains(detect.PIIKinds, kind) { + return fmt.Errorf("%s.pii: %q is not one of %s", dir, kind, strings.Join(detect.PIIKinds, ", ")) + } + if _, ok := actions[a]; !ok { + return fmt.Errorf("%s.pii.%s is %q: flag, redact or block", dir, kind, a) + } + } + switch r.Injection { + case "", "flag", "block": + default: + return fmt.Errorf("%s.injection is %q: flag or block", dir, r.Injection) + } + for i, d := range r.Deny { + if d.Name == "" { + return fmt.Errorf("%s.deny[%d] has no name", dir, i) + } + if _, err := regexp.Compile(d.Regex); err != nil { + return fmt.Errorf("%s.deny.%s: %w", dir, d.Name, err) + } + if _, ok := actions[d.Action]; !ok { + return fmt.Errorf("%s.deny.%s action is %q: flag, redact or block", dir, d.Name, d.Action) + } + } + } + return nil +} + +// Merge combines the policies that apply to one request into the one in +// force, by the rule limits narrow by: nothing below can loosen what is set +// above. The strictest mode and failure, the strictest action for each kind, +// every denied pattern and tool, only the tools every allow list allows, the +// smallest limits; any no_store; the pinned prompts in order. +func Merge(names []string, ps []Policy) Policy { + var out Policy + out.Input.PII, out.Output.PII = map[string]string{}, map[string]string{} + var allowSets [][]string + var prompts []string + for _, p := range ps { + out.Mode = stricterOf(out.Mode, p.Mode, []string{"", "off", "shadow", "enforce"}) + out.Fail = stricterOf(out.Fail, p.Fail, []string{"", "open", "closed"}) + out.Stream = stricterOf(out.Stream, p.Stream, []string{"", "sentence", "buffer_all"}) + out.NoStore = out.NoStore || p.NoStore + out.DropClientSystem = out.DropClientSystem || p.DropClientSystem + out.MaxOutputTokens = minSet(out.MaxOutputTokens, p.MaxOutputTokens) + if p.SystemPrompt != "" { + prompts = append(prompts, p.SystemPrompt) + } + mergeRules(&out.Input, p.Input) + mergeRules(&out.Output, p.Output) + t := p.Tools + if len(t.Allow) > 0 { + allowSets = append(allowSets, t.Allow) + } + out.Tools.Deny = union(out.Tools.Deny, t.Deny) + out.Tools.OnDenied = stricterOf(out.Tools.OnDenied, t.OnDenied, []string{"", "strip", "block"}) + out.Tools.MaxCallsPerTurn = minSet(out.Tools.MaxCallsPerTurn, t.MaxCallsPerTurn) + out.Tools.ValidateArguments = out.Tools.ValidateArguments || t.ValidateArguments + } + if out.Mode == "" && len(ps) > 0 { + out.Mode = "enforce" + } + for i, s := range allowSets { + if i == 0 { + out.Tools.Allow = slices.Clone(s) + continue + } + out.Tools.Allow = slices.DeleteFunc(out.Tools.Allow, func(n string) bool { return !slices.Contains(s, n) }) + if len(out.Tools.Allow) == 0 { + // Allow lists that share nothing allow nothing — said by a + // name no tool has, not by an empty list, which allows all. + out.Tools.Allow = []string{"\x00none"} + } + } + out.SystemPrompt = strings.Join(prompts, "\n\n") + return out +} + +func mergeRules(dst *Rules, r Rules) { + for k, a := range r.PII { + if rank(actions[a]) > rank(actions[dst.PII[k]]) { + dst.PII[k] = a + } + } + dst.Injection = stricterOf(dst.Injection, r.Injection, []string{"", "flag", "block"}) + for _, d := range r.Deny { + if !slices.ContainsFunc(dst.Deny, func(e Pattern) bool { return e.Name == d.Name && e.Regex == d.Regex }) { + dst.Deny = append(dst.Deny, d) + } + } + dst.MaxChars = minSet(dst.MaxChars, r.MaxChars) +} + +func stricterOf(a, b string, order []string) string { + if slices.Index(order, b) > slices.Index(order, a) { + return b + } + return a +} + +func minSet(a, b int) int { + switch { + case a == 0: + return b + case b == 0: + return a + } + return min(a, b) +} + +func union(a, b []string) []string { + for _, s := range b { + if !slices.Contains(a, s) { + a = append(a, s) + } + } + return a +} + +// active reports whether a merged policy does anything. +func (p Policy) active() bool { return p.Mode != "" && p.Mode != "off" } diff --git a/internal/guard/policy_test.go b/internal/guard/policy_test.go new file mode 100644 index 0000000..9c5441d --- /dev/null +++ b/internal/guard/policy_test.go @@ -0,0 +1,64 @@ +package guard + +import ( + "slices" + "testing" +) + +func TestPoliciesNarrowAndNeverLoosen(t *testing.T) { + gateway := Policy{Mode: "enforce", Fail: "open", MaxOutputTokens: 4096, SystemPrompt: "Be careful.", + Input: Rules{PII: map[string]string{"email": "flag", "secret": "block"}, Injection: "flag"}, + Tools: Tools{Allow: []string{"search", "shell", "fetch"}, Deny: []string{"rm"}}} + project := Policy{Mode: "off", Fail: "closed", MaxOutputTokens: 1024, NoStore: true, SystemPrompt: "Answer in Turkish.", + Input: Rules{PII: map[string]string{"email": "redact", "secret": "flag"}, Injection: "block", + Deny: []Pattern{{Name: "codename", Regex: "falcon", Action: "block"}}}, + Tools: Tools{Allow: []string{"search", "fetch"}, OnDenied: "block"}} + got := Merge(nil, []Policy{gateway, project}) + + if got.Mode != "enforce" { + t.Errorf("mode %q: a project cannot switch the gateway's policy off", got.Mode) + } + if got.Fail != "closed" || !got.NoStore || got.MaxOutputTokens != 1024 { + t.Errorf("fail %q no_store %v max %d", got.Fail, got.NoStore, got.MaxOutputTokens) + } + if got.Input.PII["email"] != "redact" || got.Input.PII["secret"] != "block" || got.Input.Injection != "block" { + t.Errorf("input %+v", got.Input) + } + if len(got.Input.Deny) != 1 || !slices.Equal(got.Tools.Allow, []string{"search", "fetch"}) || + !slices.Equal(got.Tools.Deny, []string{"rm"}) || got.Tools.OnDenied != "block" { + t.Errorf("deny %v tools %+v", got.Input.Deny, got.Tools) + } + if got.SystemPrompt != "Be careful.\n\nAnswer in Turkish." { + t.Errorf("prompt %q", got.SystemPrompt) + } + + // Allow lists that share nothing allow nothing. + none := Merge(nil, []Policy{{Tools: Tools{Allow: []string{"a"}}}, {Tools: Tools{Allow: []string{"b"}}}}) + if len(none.Tools.Allow) != 1 || none.Tools.Allow[0] == "a" || none.Tools.Allow[0] == "b" { + t.Errorf("disjoint allow lists: %v", none.Tools.Allow) + } + if Merge(nil, nil).active() || !Merge(nil, []Policy{{}}).active() || Merge(nil, []Policy{{Mode: "off"}}).active() { + t.Error("activeness") + } +} + +func TestALibraryIsCheckedBeforeItIsUsed(t *testing.T) { + bad := []Config{ + {Default: []string{"nope"}}, + {Policies: map[string]Policy{"p": {Mode: "loud"}}}, + {Policies: map[string]Policy{"p": {Input: Rules{PII: map[string]string{"dna": "block"}}}}}, + {Policies: map[string]Policy{"p": {Input: Rules{PII: map[string]string{"email": "shred"}}}}}, + {Policies: map[string]Policy{"p": {Output: Rules{Deny: []Pattern{{Name: "x", Regex: "(", Action: "block"}}}}}}, + {Policies: map[string]Policy{"p": {Tools: Tools{OnDenied: "explode"}}}}, + } + for i, c := range bad { + if c.Validate() == nil { + t.Errorf("case %d accepted: %+v", i, c) + } + } + good := Config{Default: []string{"p"}, Policies: map[string]Policy{"p": {Mode: "shadow", + Input: Rules{PII: map[string]string{"card": "redact"}, Deny: []Pattern{{Name: "x", Regex: "a+", Action: "flag"}}}}}} + if err := good.Validate(); err != nil { + t.Error(err) + } +}