CI / test (push) Successful in 8m49s
With restore: true on a guardrail policy's input, what redact rewrote as placeholders comes back in the answer: the model reads "[EMAIL_1]", the client reads the address it sent. A streamed placeholder split across events is held until it is whole, and what is held is sent at the end. The swap runs before the output filter, so the output rules judge the answer as the client reads it and a placeholder they make of a value the model invented is never taken for the request's own. The map lives in the Verdict for the request only; nothing stores, logs or traces it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
293 lines
9.9 KiB
Go
293 lines
9.9 KiB
Go
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 {
|
|
// Enabled turns every policy on or off at once: false checks nothing,
|
|
// whatever is defined or attached. Unset is on.
|
|
Enabled *bool `koanf:"enabled"`
|
|
Default []string `koanf:"default"`
|
|
Policies map[string]Policy `koanf:"policies"`
|
|
}
|
|
|
|
// On is whether the guardrails check anything.
|
|
func (c Config) On() bool { return c.Enabled == nil || *c.Enabled }
|
|
|
|
// 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"`
|
|
// RequireCapabilities refuses a request offering tools, or sending
|
|
// images, to a model whose catalog entry does not say it takes them.
|
|
RequireCapabilities bool `koanf:"require_capabilities"`
|
|
// ValidateStructured checks an answer against the JSON schema the
|
|
// request asked for in response_format: one that does not fit is
|
|
// stopped — or, streamed a sentence at a time, flagged, having been
|
|
// sent already.
|
|
ValidateStructured bool `koanf:"validate_structured"`
|
|
// Judge has a judge model on the cluster read the text too.
|
|
Judge *JudgePolicy `koanf:"judge"`
|
|
// 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"`
|
|
// Restore, on input, puts what redact rewrote as placeholders back into
|
|
// the answer: the model reads "[EMAIL_1]", the client reads its own
|
|
// address. Only the values that request sent, only into its answer.
|
|
Restore bool `koanf:"restore"`
|
|
}
|
|
|
|
// 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)
|
|
}
|
|
if p.Judge != nil {
|
|
if err := p.Judge.validate(); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
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 {
|
|
// Unwritten is enforce, not the weakest: a policy that says nothing
|
|
// of its mode, merged with one in shadow, must still act.
|
|
mode := p.Mode
|
|
if mode == "" {
|
|
mode = "enforce"
|
|
}
|
|
out.Mode = stricterOf(out.Mode, 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.RequireCapabilities = out.RequireCapabilities || p.RequireCapabilities
|
|
out.ValidateStructured = out.ValidateStructured || p.ValidateStructured
|
|
out.Judge = mergeJudge(out.Judge, p.Judge)
|
|
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
|
|
}
|
|
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)
|
|
// Any policy may ask: what is put back is the caller's own, to the
|
|
// caller, and never reaches the model either way.
|
|
dst.Restore = dst.Restore || r.Restore
|
|
}
|
|
|
|
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" }
|