Guard policies: a library in server.yaml, merged so nothing below loosens what is above
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
e3ef5b18c1
commit
ccdc07fe0c
2 files changed
+322
No files matched your search
@@ -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" }
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user