guard

Documentation

Overview

Package guard provides a pluggable prompt-injection detector for odek.

It exposes a Guard interface with two built-in implementations:

• local: a zero-dependency rule-based guard backed by danger.ScanInjection.
• piguard: a client for the go-prompt-injection-guard sidecar (HTTP or Unix socket).

The package is designed to be used as a defense-in-depth layer: the fast, local scan is always available, and the piguard sidecar provides a semantic second opinion when configured.

Index

• Constants
• func IsEnabled(cfg *ScanConfig, scope string) bool
• func ScanContent(ctx context.Context, content string, g Guard, cfg *Config) error
• func ScanContentWithScope(ctx context.Context, content string, g Guard, cfg *Config, scope string) error
• type Config
  • func DefaultConfig() *Config
• type Guard
  • func New(cfg *Config) (Guard, error)
  • func NewLocalGuard() Guard
• type Result
• type ScanConfig
  • func DefaultScanConfig() *ScanConfig

Constants

const (
	ProviderLocal   = "local"
	ProviderPiguard = "piguard"
)

Provider constants.

Functions

func IsEnabled

func IsEnabled(cfg *ScanConfig, scope string) bool

IsEnabled reports whether a scan scope is enabled in cfg. It returns true if the scope is nil or explicitly true, and false only when explicitly false. This makes "not set" mean "enabled by default" for the core surfaces, while preserving the ability to opt out.

func ScanContent

func ScanContent(ctx context.Context, content string, g Guard, cfg *Config) error

ScanContent checks content for prompt-injection threats.

It always runs the fast, local rule-based scan first. If g is non-nil and the configured provider is not "local", it also runs a semantic second opinion via g. When the second opinion fails and FallbackToLocal is true, the content is accepted based on the local scan and a warning is logged.

This function is the single source of truth for injection scanning across memory, system prompt sources, MCP descriptions, and any other guarded input.

func ScanContentWithScope

func ScanContentWithScope(ctx context.Context, content string, g Guard, cfg *Config, scope string) error

ScanContentWithScope runs ScanContent only when the scope is enabled in cfg. If the scope is disabled, only the local rule-based scan is run. This lets operators opt out of the semantic second opinion for specific surfaces without losing the fast local defense.

Types

type Config

type Config struct {
	Provider        string      `json:"provider,omitempty"`          // "local" or "piguard"
	URL             string      `json:"url,omitempty"`               // e.g. http://127.0.0.1:8080/detect
	LongURL         string      `json:"long_url,omitempty"`          // e.g. http://127.0.0.1:8080/long
	BatchURL        string      `json:"batch_url,omitempty"`         // e.g. http://127.0.0.1:8080/raw
	SocketPath      string      `json:"socket_path,omitempty"`       // /tmp/piguard.sock (unix mode)
	Threshold       float64     `json:"threshold,omitempty"`         // default 0.9
	TimeoutSeconds  int         `json:"timeout_seconds,omitempty"`   // default 5
	FallbackToLocal *bool       `json:"fallback_to_local,omitempty"` // default true
	MaxTextLength   int         `json:"max_text_length,omitempty"`   // default 0 = unlimited
	Scan            *ScanConfig `json:"scan,omitempty"`              // per-subsystem toggles
}

Config controls the injection guard.

SECURITY: this config is operator-controlled. A malicious project must not be able to disable the local scan or redirect memory/system-prompt content to an attacker-controlled endpoint. Therefore the entire guard section must be rejected from project-level ./odek.json.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a config that uses the local rule-based scan.

type Guard

type Guard interface {
	Detect(ctx context.Context, text string) (Result, error)
	DetectBatch(ctx context.Context, texts []string) ([]Result, error)
	DetectLong(ctx context.Context, text string) (Result, error)
	Close() error
}

Guard is the pluggable prompt-injection detector.

func New

func New(cfg *Config) (Guard, error)

New creates a Guard from cfg. If cfg is nil, it returns a local guard. If the provider is unknown, it logs a warning and falls back to local. If the provider is piguard but initialization fails, it falls back to local when FallbackToLocal is true; otherwise it returns an error.

func NewLocalGuard

func NewLocalGuard() Guard

NewLocalGuard creates a guard backed by danger.ScanInjection.

type Result

type Result struct {
	Label    string
	Score    float64
	Injected bool
	Latency  time.Duration
}

Result is the outcome of a guard check.

type ScanConfig

type ScanConfig struct {
	Memory          *bool `json:"memory,omitempty"`           // default true
	SystemPrompt    *bool `json:"system_prompt,omitempty"`    // default true
	MCPDescriptions *bool `json:"mcp_descriptions,omitempty"` // default true
	Skills          *bool `json:"skills,omitempty"`           // default true
	ToolOutputs     *bool `json:"tool_outputs,omitempty"`     // default false
	Telegram        *bool `json:"telegram,omitempty"`         // default false
}

ScanConfig toggles which subsystems use the guard.

func DefaultScanConfig

func DefaultScanConfig() *ScanConfig

DefaultScanConfig enables memory, system_prompt, mcp_descriptions, and skills by default.