feat(pii): pattern detector tier — bounded restricted-regex secret matching

NER is the wrong tool for high-entropy, highly-regular secrets: the privacy
model has no API-key class, so it fragments a key (tail -> BITCOINADDRESS,
prefix -> VRM) and can leave the secret part exposed. Add a regex tier that
plugs in as another detector model alongside NER and reuses the whole pipeline.

  - core/services/routing/piipattern (leaf; stdlib only): a restricted-regex
    grammar validated against the RE2 AST (no '.', no capture groups, capped
    {n,m}; every pattern must carry a >=3-char fixed literal anchor, which
    admits sk-ant-/ghp_/AKIA shapes but rejects open-ended ones like email or
    bare \w+), compiled to RE2 (linear, no backtracking) with leftmost-longest
    so a hit grabs the whole key. Curated built-in catalogue (Anthropic, OpenAI,
    GitHub, AWS, Google, Slack, Stripe, JWT, PEM private key).
  - config: PIIDetection.{Builtins,Patterns} + IsPatternDetector(); Validate
    rejects bad patterns/unknown builtins at load (no model file required).
  - piidetector.NewPattern: in-process pii.NERDetector (Score 1.0), records a
    pattern_pii BackendTrace when tracing is on. PIINERResolver branches to it
    for pattern models; MITM inherits it. Per-pattern action overrides fold
    into entity_actions.
  - meta registry: pii_detection.builtins -> pii-builtins-select (options from
    the catalogue) and pii_detection.patterns -> pii-pattern-list, for the
    model editor.
  - gallery: ready-made secret-filter pattern model (builtins on, default
    block, zero VRAM). Docs: new Pattern detector tier section.

Pattern hits union with NER hits and flow through the same policy, events
(score 1.0) and DEBUG logs. UI editors + Traces badge follow in a UI commit.

Assisted-by: claude-code:claude-opus-4-8 [Claude Code]

Author: richiejp

core/application/application.go

@@ -270,6 +270,24 @@ func (a *Application) PIINERResolver() pii.NERDetectorResolver {
 		if !ok {
 			return pii.NERConfig{}, false
 		}
+
+		// Pattern detectors match secrets with the restricted-regex tier
+		// in-process (no backend load). Build a pattern matcher instead of the
+		// gRPC token-classifier; on a compile error fail closed with an error
+		// detector so the request is blocked, not silently unscanned.
+		if cfg.IsPatternDetector() {
+			det, err := piidetector.NewPattern(cfg, a.ApplicationConfig())
+			if err != nil {
+				det = pii.NewErrNERDetector(err.Error())
+			}
+			return pii.NERConfigFromRaw(
+				det,
+				0, // patterns are deterministic — no confidence floor
+				cfg.PIIDetectionDefaultAction(),
+				patternEntityActions(cfg),
+			), true
+		}
+
 		det := piidetector.New(a.ModelLoader(), cfg, a.ApplicationConfig())
 		return pii.NERConfigFromRaw(
 			det,
@@ -280,6 +298,26 @@ func (a *Application) PIINERResolver() pii.NERDetectorResolver {
 	}
 }
 
+// patternEntityActions merges a pattern detector's per-pattern Action overrides
+// into its entity_actions map. A pattern reports matches under its Name, so a
+// per-pattern action is just an entity_actions[Name] entry; explicit
+// entity_actions still win if both are set.
+func patternEntityActions(cfg config.ModelConfig) map[string]string {
+	out := cfg.PIIDetectionEntityActions()
+	for _, p := range cfg.PIIDetection.Patterns {
+		if p.Action == "" || p.Name == "" {
+			continue
+		}
+		if out == nil {
+			out = map[string]string{}
+		}
+		if _, exists := out[p.Name]; !exists {
+			out[p.Name] = p.Action
+		}
+	}
+	return out
+}
+
 // ResolvePIIPolicy resolves the effective request-side PII policy for a
 // consuming model, layering the instance-wide default detector
 // (PIIDefaultDetectors, set via POST /api/settings) on top of the per-model

core/config/meta/pattern_meta_test.go

@@ -0,0 +1,41 @@
+package meta_test
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/config/meta"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestMeta(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "config/meta suite")
+}
+
+var _ = Describe("pattern detector field metadata", func() {
+	byPath := func() map[string]meta.FieldMeta {
+		md := meta.BuildForTest(reflect.TypeOf(config.ModelConfig{}), meta.DefaultRegistry())
+		out := make(map[string]meta.FieldMeta, len(md.Fields))
+		for _, f := range md.Fields {
+			out[f.Path] = f
+		}
+		return out
+	}
+
+	It("renders builtins as a select with the catalogue as options", func() {
+		f, ok := byPath()["pii_detection.builtins"]
+		Expect(ok).To(BeTrue(), "pii_detection.builtins field should exist")
+		Expect(f.Component).To(Equal("pii-builtins-select"))
+		Expect(f.Options).NotTo(BeEmpty())
+	})
+
+	It("renders custom patterns with the pattern-list editor", func() {
+		f, ok := byPath()["pii_detection.patterns"]
+		Expect(ok).To(BeTrue(), "pii_detection.patterns field should exist")
+		Expect(f.Component).To(Equal("pii-pattern-list"))
+	})
+})

core/config/meta/registry.go

@@ -1,5 +1,19 @@
 package meta
 
+import "github.com/mudler/LocalAI/core/services/routing/piipattern"
+
+// builtinPatternOptions turns the piipattern built-in catalogue into select
+// options for the editor's built-in-patterns checklist, keeping the catalogue
+// the single source of truth.
+func builtinPatternOptions() []FieldOption {
+	cat := piipattern.BuiltinCatalogue()
+	out := make([]FieldOption, 0, len(cat))
+	for _, b := range cat {
+		out = append(out, FieldOption{Value: b.Name, Label: b.Name + " — " + b.Description})
+	}
+	return out
+}
+
 // DefaultRegistry returns enrichment overrides for the ~30 most commonly used
 // config fields. Fields not listed here still appear with auto-generated
 // labels and type-inferred components.
@@ -423,6 +437,21 @@ func DefaultRegistry() map[string]FieldMetaOverride {
 			Component:   "entity-action-list",
 			Order:       212,
 		},
+		"pii_detection.builtins": {
+			Section:     "pii",
+			Label:       "Built-in Secret Patterns",
+			Description: "Built-in regex patterns for common credentials (API keys, tokens, private keys). Turning any on makes this a pattern detector — it matches high-entropy secrets the NER tier can't, in-process with no model load.",
+			Component:   "pii-builtins-select",
+			Options:     builtinPatternOptions(),
+			Order:       213,
+		},
+		"pii_detection.patterns": {
+			Section:     "pii",
+			Label:       "Custom Secret Patterns",
+			Description: "Operator-defined patterns in a restricted regex subset (e.g. \"sk-prefix-\\w+\"). Each must contain a fixed literal anchor of ≥3 chars; open-ended shapes like emails are rejected (leave those to NER). Matches report under the pattern name as the entity group.",
+			Component:   "pii-pattern-list",
+			Order:       214,
+		},
 
 		// --- Cloud passthrough proxy ---
 		// These only have an effect when Backend is set to

core/config/model_config.go

@@ -10,6 +10,7 @@ import (
 	"text/template"
 
 	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/services/routing/piipattern"
 	"github.com/mudler/LocalAI/pkg/downloader"
 	"github.com/mudler/LocalAI/pkg/functions"
 	"github.com/mudler/LocalAI/pkg/reasoning"
@@ -415,6 +416,27 @@ type PIIDetectionConfig struct {
 	// This is where an operator says which PII to block vs mask vs
 	// allow-log.
 	EntityActions map[string]string `yaml:"entity_actions,omitempty" json:"entity_actions,omitempty"`
+
+	// Builtins names the built-in pattern groups this (pattern) detector
+	// enables, e.g. "anthropic_api_key", "github_token". Pattern detectors
+	// match high-entropy structured secrets the NER tier can't; see
+	// core/services/routing/piipattern.
+	Builtins []string `yaml:"builtins,omitempty" json:"builtins,omitempty"`
+	// Patterns lists operator-defined secret patterns in the restricted-regex
+	// subset (validated at load). Each match is reported under its Name as the
+	// entity group, so EntityActions/DefaultAction apply by Name.
+	Patterns []PIIPattern `yaml:"patterns,omitempty" json:"patterns,omitempty"`
+}
+
+// PIIPattern is one operator-defined pattern on a pattern detector model. Name
+// is the entity group reported for matches (and the EntityActions key). Match
+// is the restricted-regex source. Action optionally overrides DefaultAction for
+// this pattern. MinLen drops matches shorter than N bytes (0 = no floor).
+type PIIPattern struct {
+	Name   string `yaml:"name" json:"name"`
+	Match  string `yaml:"match" json:"match"`
+	Action string `yaml:"action,omitempty" json:"action,omitempty"`
+	MinLen int    `yaml:"min_len,omitempty" json:"min_len,omitempty"`
 }
 
 // PIIIsEnabled returns the resolved PII state for this model. Single
@@ -483,6 +505,15 @@ func (c *ModelConfig) PIIDetectionEntityActions() map[string]string {
 	return out
 }
 
+// IsPatternDetector reports whether this detector model matches secrets with
+// regex patterns (built-in and/or operator-defined) rather than a neural NER
+// model. Such a model runs entirely in-process (no backend / GGUF / VRAM); the
+// PII resolver builds an in-process pattern matcher for it instead of loading a
+// gRPC token-classifier.
+func (c *ModelConfig) IsPatternDetector() bool {
+	return len(c.PIIDetection.Builtins) > 0 || len(c.PIIDetection.Patterns) > 0
+}
+
 // @Description MCP configuration
 type MCPConfig struct {
 	Servers string `yaml:"remote,omitempty" json:"remote,omitempty"`
@@ -1070,6 +1101,26 @@ func (c *ModelConfig) Validate() (bool, error) {
 				"with chat/completion — split into separate model configs")
 	}
 
+	// Pattern detector: validate built-in names and that each operator-defined
+	// pattern is a well-formed, anchored, bounded restricted-regex. Reject at
+	// load so a bad pattern surfaces as a clear config error rather than a
+	// silent no-op (or a fail-closed block) at request time.
+	if c.IsPatternDetector() {
+		for _, name := range c.PIIDetection.Builtins {
+			if _, ok := piipattern.LookupBuiltin(name); !ok {
+				return false, fmt.Errorf("pii_detection: unknown built-in pattern %q", name)
+			}
+		}
+		for _, p := range c.PIIDetection.Patterns {
+			if p.Name == "" {
+				return false, fmt.Errorf("pii_detection: pattern is missing a name")
+			}
+			if err := piipattern.ValidatePattern(p.Match); err != nil {
+				return false, fmt.Errorf("pii_detection: pattern %q: %w", p.Name, err)
+			}
+		}
+	}
+
 	// router.score_normalization is consumed lazily by the score
 	// classifier at first-request time; without load-time validation
 	// a typo wouldn't surface until the first router request panicked

core/config/model_config_test.go

@@ -699,3 +699,37 @@ var _ = Describe("PIIFilterApplies (Middleware admin list scoping)", func() {
 		Expect(withUsecases("whisper", FLAG_TRANSCRIPT).PIIFilterApplies()).To(BeFalse())
 	})
 })
+
+var _ = Describe("pattern detector config", func() {
+	patternCfg := func() *ModelConfig {
+		c := &ModelConfig{Name: "secret-filter", Backend: "pattern"}
+		c.PIIDetection.Builtins = []string{"anthropic_api_key"}
+		c.PIIDetection.Patterns = []PIIPattern{{Name: "INTERNAL", Match: `tok-[A-Za-z0-9]{20,}`}}
+		return c
+	}
+
+	It("IsPatternDetector keys off builtins/patterns", func() {
+		Expect(patternCfg().IsPatternDetector()).To(BeTrue())
+		Expect((&ModelConfig{Name: "ner", Backend: "llama-cpp"}).IsPatternDetector()).To(BeFalse())
+	})
+
+	It("Validate accepts a well-formed pattern detector (no model file needed)", func() {
+		ok, err := patternCfg().Validate()
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ok).To(BeTrue())
+	})
+
+	It("Validate rejects an unknown built-in", func() {
+		c := &ModelConfig{Name: "x", Backend: "pattern"}
+		c.PIIDetection.Builtins = []string{"does_not_exist"}
+		_, err := c.Validate()
+		Expect(err).To(MatchError(ContainSubstring("unknown built-in")))
+	})
+
+	It("Validate rejects an unanchored custom pattern", func() {
+		c := &ModelConfig{Name: "x", Backend: "pattern"}
+		c.PIIDetection.Patterns = []PIIPattern{{Name: "EMAILish", Match: `[\w.]+@[\w.]+\.\w+`}}
+		_, err := c.Validate()
+		Expect(err).To(MatchError(ContainSubstring("pattern \"EMAILish\"")))
+	})
+})

core/services/routing/piidetector/pattern.go

@@ -0,0 +1,80 @@
+package piidetector
+
+import (
+	"context"
+	"time"
+
+	"github.com/mudler/LocalAI/core/backend"
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/routing/pii"
+	"github.com/mudler/LocalAI/core/services/routing/piipattern"
+	"github.com/mudler/LocalAI/core/trace"
+)
+
+// NewPattern builds a pii.NERDetector that matches secrets with the restricted
+// regex tier (built-ins + operator-defined patterns) instead of a neural model.
+// It runs entirely in-process — no backend, GGUF, or VRAM — and the patterns
+// compile once here, so an invalid pattern is reported now (the resolver fails
+// closed) rather than per request. Matches are reported under their group with
+// a deterministic Score of 1.0.
+func NewPattern(modelConfig config.ModelConfig, appConfig *config.ApplicationConfig) (pii.NERDetector, error) {
+	custom := make([]piipattern.Pattern, 0, len(modelConfig.PIIDetection.Patterns))
+	for _, p := range modelConfig.PIIDetection.Patterns {
+		custom = append(custom, piipattern.Pattern{Group: p.Name, Pattern: p.Match, MinLen: p.MinLen})
+	}
+	m, err := piipattern.NewMatcher(modelConfig.PIIDetection.Builtins, custom)
+	if err != nil {
+		return nil, err
+	}
+	return &patternDetector{matcher: m, modelName: modelConfig.Name, appConfig: appConfig}, nil
+}
+
+type patternDetector struct {
+	matcher   *piipattern.Matcher
+	modelName string
+	appConfig *config.ApplicationConfig
+}
+
+// Detect runs the compiled patterns and maps each match onto a pii.NEREntity.
+// When tracing is enabled it records a pattern_pii BackendTrace so the matches
+// (group, byte range, text) show in the Traces UI alongside NER detections.
+func (d *patternDetector) Detect(_ context.Context, text string) ([]pii.NEREntity, error) {
+	var start time.Time
+	if d.appConfig != nil && d.appConfig.EnableTracing {
+		trace.InitBackendTracingIfEnabled(d.appConfig.TracingMaxItems, d.appConfig.TracingMaxBodyBytes)
+		start = time.Now()
+	}
+
+	matches := d.matcher.Find(text)
+	out := make([]pii.NEREntity, 0, len(matches))
+	var traceEnts []backend.TokenEntity
+	for _, mt := range matches {
+		out = append(out, pii.NEREntity{Group: mt.Group, Start: mt.Start, End: mt.End, Score: 1.0, Text: mt.Text})
+		if d.appConfig != nil && d.appConfig.EnableTracing {
+			traceEnts = append(traceEnts, backend.TokenEntity{Group: mt.Group, Start: mt.Start, End: mt.End, Score: 1.0, Text: mt.Text})
+		}
+	}
+
+	if d.appConfig != nil && d.appConfig.EnableTracing {
+		trace.RecordBackendTrace(patternPIITrace(d.modelName, text, traceEnts, start))
+	}
+	return out, nil
+}
+
+// patternPIITrace assembles the Traces-UI row for one pattern-detector run.
+// Split out so the Data assembly is unit-testable without a request.
+func patternPIITrace(modelName, text string, entities []backend.TokenEntity, start time.Time) trace.BackendTrace {
+	return trace.BackendTrace{
+		Timestamp: start,
+		Duration:  time.Since(start),
+		Type:      trace.BackendTracePatternPII,
+		ModelName: modelName,
+		Backend:   "pattern",
+		Summary:   trace.TruncateString(text, 200),
+		Data: map[string]any{
+			"input_chars": len(text),
+			"matches":     len(entities),
+			"entities":    entities,
+		},
+	}
+}

core/services/routing/piidetector/pattern_test.go

@@ -0,0 +1,61 @@
+package piidetector_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/services/routing/pii"
+	"github.com/mudler/LocalAI/core/services/routing/piidetector"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestPiidetector(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "piidetector suite")
+}
+
+func patternModel() config.ModelConfig {
+	c := config.ModelConfig{Name: "secret-filter", Backend: "pattern"}
+	c.PIIDetection.Builtins = []string{"anthropic_api_key"}
+	c.PIIDetection.Patterns = []config.PIIPattern{{Name: "INTERNAL_TOKEN", Match: `tok-[A-Za-z0-9]{8,}`}}
+	return c
+}
+
+var _ = Describe("pattern detector", func() {
+	It("matches built-in and custom secrets as whole-span deterministic hits", func() {
+		det, err := piidetector.NewPattern(patternModel(), &config.ApplicationConfig{})
+		Expect(err).NotTo(HaveOccurred())
+
+		ents, err := det.Detect(context.Background(), "use sk-ant-api03-AAAABBBBCCCCDDDDEEEE and tok-ABCD1234 ok")
+		Expect(err).NotTo(HaveOccurred())
+
+		byGroup := map[string]pii.NEREntity{}
+		for _, e := range ents {
+			byGroup[e.Group] = e
+			Expect(e.Score).To(BeEquivalentTo(float32(1.0)), "pattern matches are deterministic")
+		}
+		Expect(byGroup).To(HaveKey("ANTHROPIC_KEY"))
+		Expect(byGroup["INTERNAL_TOKEN"].Text).To(Equal("tok-ABCD1234"))
+	})
+
+	It("still detects (and exercises the trace path) with tracing enabled", func() {
+		det, err := piidetector.NewPattern(patternModel(), &config.ApplicationConfig{
+			EnableTracing: true, TracingMaxItems: 8,
+		})
+		Expect(err).NotTo(HaveOccurred())
+		ents, err := det.Detect(context.Background(), "sk-ant-api03-AAAABBBBCCCCDDDDEEEE")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ents).To(HaveLen(1))
+		Expect(ents[0].Group).To(Equal("ANTHROPIC_KEY"))
+	})
+
+	It("fails to build on an invalid (unanchored) custom pattern", func() {
+		c := config.ModelConfig{Name: "bad", Backend: "pattern"}
+		c.PIIDetection.Patterns = []config.PIIPattern{{Name: "X", Match: `.*`}}
+		_, err := piidetector.NewPattern(c, &config.ApplicationConfig{})
+		Expect(err).To(HaveOccurred())
+	})
+})