risk_analysis

type AccountIdentityConfig ¶

type AccountIdentityConfig struct {
	// ApprovedEmailDomains is the corporate email domain allowlist. When
	// non-empty, sessions whose AI-account email domain is not in the list
	// produce an identity.unapproved_domain finding. Empty means the domain
	// rule is inert.
	ApprovedEmailDomains []string `json:"approved_email_domains,omitempty"`
}

AccountIdentityConfig holds account_identity-scanner options.

type AnalyzeBatch ¶

type AnalyzeBatch struct {
	// contains filtered or unexported fields
}

AnalyzeBatch scans a batch of messages against one risk policy and replaces that policy's stored results for the fetched message IDs.

func NewAnalyzeBatch(
	logger *slog.Logger,
	tracerProvider trace.TracerProvider,
	meterProvider metric.MeterProvider,
	db *pgxpool.Pool,
	piiScanner PIIScanner,
	promptInjectionScanner *promptinjection.Scanner,
	shadowMCPClient *shadowmcp.Client,
	mcpMatchLookup MCPMatchLookup,
	judge promptpolicy.Evaluator,
	flags feature.Provider,
	presidioPub gcp.Publisher[*riskv1.PresidioAnalysis],
	gitleaksPub gcp.Publisher[*riskv1.GitleaksAnalysis],
	promptInjectionPub gcp.Publisher[*riskv1.PromptInjectionAnalysis],
	promptPolicyPub gcp.Publisher[*riskv1.PromptPolicyAnalysis],
	customRulesPub gcp.Publisher[*riskv1.CustomRulesAnalysis],
	customRuleScanner *customruleanalyzer.Scanner,
	celEng *celenv.Engine,
	builtinPresets *presetlib.Library,
) (*AnalyzeBatch, error)

func (a *AnalyzeBatch) Do(ctx context.Context, args AnalyzeBatchArgs) (_ *AnalyzeBatchResult, err error)

type AnalyzeBatchArgs ¶

type AnalyzeBatchArgs struct {
	ProjectID        uuid.UUID
	OrganizationID   string
	RiskPolicyID     uuid.UUID
	PolicyVersion    int64
	MessageIDs       []uuid.UUID
	Sources          []string
	MessageTypes     []string
	PresidioEntities []string
	// PresidioScoreThreshold is the per-policy minimum recognizer confidence
	// (0.0-1.0). Do derives it from the refetched policy's analyzer_config, so it
	// is not a caller input; zero means unset and the scanner applies
	// DefaultPresidioScoreThreshold.
	PresidioScoreThreshold float64
	CustomRuleIds          []string
	// ApprovedEmailDomains is the account_identity corporate domain allowlist.
	// Like PresidioScoreThreshold, Do derives it from the refetched policy's
	// analyzer_config, so it is not a caller input.
	ApprovedEmailDomains []string
	// BuiltinPresetsEnabled toggles scan-time suppression of built-in catalog
	// false positives. Do derives it from the refetched policy's analyzer_config
	// (defaulting ON), so it is not a caller input.
	BuiltinPresetsEnabled bool
	// DetectionScopes are the policy's specified per-category detection scopes,
	// each replacing its registry recommendation. Do derives it from the
	// refetched policy's analyzer_config, so it is not a caller input.
	DetectionScopes []DetectionScopeConfig
}

type AnalyzeBatchResult ¶

type AnalyzeBatchResult struct {
	Processed int
	Findings  int
}

type AnalyzerConfig ¶

type AnalyzerConfig struct {
	Presidio        *PresidioConfig        `json:"presidio,omitempty"`
	BuiltinPresets  *BuiltinPresetsConfig  `json:"builtin_presets,omitempty"`
	AccountIdentity *AccountIdentityConfig `json:"account_identity,omitempty"`
	DetectionScopes []DetectionScopeConfig `json:"detection_scopes,omitempty"`
}

AnalyzerConfig is the opaque per-analyzer scanner configuration persisted on risk_policies.analyzer_config (JSONB), namespaced by analyzer. New per-scanner options live here rather than as a dedicated column each.

func ParseAnalyzerConfig(b []byte) AnalyzerConfig

type BuiltinPresetsConfig ¶

type BuiltinPresetsConfig struct {
	// Enabled toggles scan-time suppression of catalog false positives. Absent
	// means "unset" — callers default to ON (see BuiltinPresetsEnabledFromConfig).
	Enabled *bool `json:"enabled,omitempty"`
}

BuiltinPresetsConfig holds options for the built-in false-positive preset catalog applied at scan-time across all detection sources.

type CategoryScope ¶

type CategoryScope struct {
	// contains filtered or unexported fields
}

CategoryScope is the single-message composition used by realtime enforcement: policy-specified detection scopes merged over registry recommendations, specified winning per category.

func NewCategoryScope(policy CompiledScope, rec RecommendedSet, specified map[categories.Category]CompiledScope, enabled bool) CategoryScope

func (s CategoryScope) FilterFindings(view MessageView, findings []scanners.Finding) []scanners.Finding

func (s CategoryScope) InScope(view MessageView, cat categories.Category) bool

func (s CategoryScope) SourceInScope(view MessageView, source string) bool

type CategoryScopeMasks ¶

type CategoryScopeMasks struct {
	// contains filtered or unexported fields
}

CategoryScopeMasks contains per-message policy and category scope exclusions.

func (m CategoryScopeMasks) AdmitsAny(i int, cats []categories.Category) bool

func (m CategoryScopeMasks) InScope(i int, cat categories.Category) bool

func (m CategoryScopeMasks) RecommendedPrefilteredCount(cats []categories.Category) int

func (m CategoryScopeMasks) Subset(messages []batchMessage, contents []string, cats []categories.Category) ([]batchMessage, []string, []int)

type CategoryScopes ¶

type CategoryScopes struct {
	// contains filtered or unexported fields
}

CategoryScopes is the per-batch composition of per-category detection scopes: policy-specified scopes merged over registry recommendations, with the specified scope winning per category. The legacy policy scope still intersects while `scope_include`/`scope_exempt` remain on policy rows. Nil-safe zero value = policy scope only.

func NewCategoryScopes(policy CompiledScope, rec RecommendedSet, specified map[categories.Category]CompiledScope, enabled bool, metrics *riskMetrics) CategoryScopes

func (s CategoryScopes) Masks(_ context.Context, messages []batchMessage) CategoryScopeMasks

type CompiledCELRule ¶

type CompiledCELRule struct {
	// contains filtered or unexported fields
}

CompiledCELRule is a custom rule whose detection predicate is compiled once.

func CompileCELRules(eng *celenv.Engine, rules []customrules.Rule) ([]CompiledCELRule, error)

type CompiledScope ¶

type CompiledScope struct {
	// contains filtered or unexported fields
}

CompiledScope is a policy's compiled scope predicates.

func CompileScope(eng *celenv.Engine, includeCEL, exemptCEL string) (CompiledScope, error)

func (s CompiledScope) Active() bool

func (s CompiledScope) Exempts(view MessageView) bool

func (s CompiledScope) InScope(view MessageView) (bool, error)

func (s CompiledScope) Includes(view MessageView) bool

type DetectionScopeConfig ¶

type DetectionScopeConfig struct {
	Category     string `json:"category"`
	ScopeInclude string `json:"scope_include,omitempty"`
	ScopeExempt  string `json:"scope_exempt,omitempty"`
}

DetectionScopeConfig specifies one category's detection scope. A specified category replaces its registry recommendation; both fields empty means the category scans every message surface.

func DetectionScopesFromConfig(b []byte) []DetectionScopeConfig

type DisabledRuleSet ¶

type DisabledRuleSet struct {
	// contains filtered or unexported fields
}

DisabledRuleSet is a lookup set of canonical rule_ids the policy author has unchecked within otherwise-enabled categories. The scanner pipeline calls FilterFindings after each scanner returns to drop matching findings before they reach the dedup/write path. Empty set is a no-op.

func NewDisabledRuleSet(disabled []string) DisabledRuleSet

func (d DisabledRuleSet) Contains(ruleID string) bool

func (d DisabledRuleSet) Empty() bool

func (d DisabledRuleSet) FilterFindings(in []scanners.Finding) []scanners.Finding

type EvalMessage ¶

type EvalMessage struct {
	ID        uuid.UUID
	Role      string
	Content   string
	ToolCalls []byte
}

EvalMessage is a recorded chat message fed to the guardrail-eval replay. It is deliberately row-agnostic (built from primitive columns) so callers outside this package can drive the replay without importing the risk repo row type.

type ExclusionSet ¶

type ExclusionSet struct {
	// contains filtered or unexported fields
}

ExclusionSet evaluates risk exclusions against findings. It mirrors DisabledRuleSet: the scanner pipeline calls FilterFindings to drop findings an exclusion suppresses before they reach the write path (going-forward suppression). The same matching logic is mirrored in SQL by the retroactive reconcile sweep so existing findings are flagged consistently.

An exclusion's rule_id_filter / source_filter narrow which findings it applies to; an empty filter means "any". match_type selects the comparison:

exact       finding.Match == value
regex       value (RE2) matches finding.Match
rule_id     finding.RuleID == value
source      finding.Source == value
entity_type finding.RuleID == "pii." + lower(value)

func NewExclusionSet(exclusions []repo.RiskExclusion) ExclusionSet

func (s ExclusionSet) Empty() bool

func (s ExclusionSet) Excluded(f scanners.Finding) bool

func (s ExclusionSet) ExcludedBy(f scanners.Finding) (uuid.UUID, bool)

func (s ExclusionSet) FilterFindings(in []scanners.Finding) []scanners.Finding

type FetchUnanalyzed ¶

type FetchUnanalyzed struct {
	// contains filtered or unexported fields
}

FetchUnanalyzed retrieves all active policies for a project and the batch of chat message IDs that have not yet been marked as analyzed (risk_analyzed_at IS NULL) within the configured lookback window.

func NewFetchUnanalyzed(logger *slog.Logger, tracerProvider trace.TracerProvider, db *pgxpool.Pool) *FetchUnanalyzed

func (a *FetchUnanalyzed) Do(ctx context.Context, args FetchUnanalyzedArgs) (_ *FetchUnanalyzedResult, err error)

type FetchUnanalyzedArgs ¶

type FetchUnanalyzedArgs struct {
	ProjectID    uuid.UUID
	IDLowerBound uuid.UUID // UUIDv7 lower bound derived from lookback window
	BatchLimit   int32
}

type FetchUnanalyzedResult ¶

type FetchUnanalyzedResult struct {
	MessageIDs []uuid.UUID
	Policies   []PolicyForAnalysis
}

type FindingSpan ¶

type FindingSpan struct {
	Match string `json:"match"`
	// Field is the author-facing message field the span matched.
	Field string `json:"field,omitempty"`
	// Path is the gjson sub-path within Field for `.get(...)` matches.
	Path     string `json:"path,omitempty"`
	StartPos int    `json:"start_pos"`
	EndPos   int    `json:"end_pos"`
}

FindingSpan is one matched span attributed to a finding.

type MCPMatchLookup ¶

type MCPMatchLookup interface {
	LookupMCPMatchesByToolCallID(ctx context.Context, projectID uuid.UUID, toolCallIDs []string) (map[string]string, error)
}

MCPMatchLookup resolves stored tool-call IDs to MCP match strings. It is the risk_analysis-facing name for shadowmcpscan.MatchLookup, kept here because it is part of the NewAnalyzeBatch constructor signature.

type MarkMessagesAnalyzed ¶

type MarkMessagesAnalyzed struct {
	// contains filtered or unexported fields
}

MarkMessagesAnalyzed sets risk_analyzed_at on a batch of chat messages after all active policies have completed analysis (fan-in step).

func NewMarkMessagesAnalyzed(logger *slog.Logger, tracerProvider trace.TracerProvider, db *pgxpool.Pool) *MarkMessagesAnalyzed

func (a *MarkMessagesAnalyzed) Do(ctx context.Context, args MarkMessagesAnalyzedArgs) (err error)

type MarkMessagesAnalyzedArgs ¶

type MarkMessagesAnalyzedArgs struct {
	ProjectID  uuid.UUID
	MessageIDs []uuid.UUID
}

type MessageVerdict ¶

type MessageVerdict struct {
	Index     int
	Type      message.Type
	ToolName  string
	LatencyMs int64
	promptpolicy.Verdict
}

MessageVerdict is the judge's verdict for one in-scope EvalMessage. Index points back into the input slice so callers can attach message metadata.

func EvalPromptGuardrail(
	ctx context.Context,
	logger *slog.Logger,
	judge promptpolicy.Evaluator,
	eng *celenv.Engine,
	orgID, projectID, prompt string,
	cfg promptpolicy.Config,
	messages []EvalMessage,
	messageTypes []string,
	includeCEL, exemptCEL string,
) ([]MessageVerdict, error)

type MessageView ¶

type MessageView struct {
	Content string
	Type    message.Type
	Tools   []ToolView
}

MessageView is the structured input the CEL engine evaluates against.

type PIIScanner ¶

type PIIScanner interface {
	// AnalyzeBatch sends multiple texts to the PII analyzer and returns
	// findings for each. The outer slice is indexed by input position.
	// When entities is non-empty, only those entity types are detected.
	//
	// scoreThreshold is the minimum recognizer confidence a match must clear
	// to be returned. A value <=0 or >1 is treated as unset and the default
	// (DefaultPresidioScoreThreshold) is applied.
	//
	// Permanent per-message failures surface as a single Finding with
	// DeadLetterReason populated rather than as an error; the returned
	// error is non-nil only on outer-ctx cancellation.
	AnalyzeBatch(ctx context.Context, texts []string, entities []string, scoreThreshold float64, onProgress func()) ([][]scanners.Finding, error)
}

PIIScanner detects personally identifiable information in text.

type PolicyForAnalysis ¶

type PolicyForAnalysis struct {
	ID               uuid.UUID
	OrganizationID   string
	Version          int64
	Sources          []string
	MessageTypes     []string
	PresidioEntities []string
	CustomRuleIds    []string
}

PolicyForAnalysis carries the policy metadata the coordinator needs to construct AnalyzeBatchArgs for each active policy.

type PresidioClient ¶

type PresidioClient struct {
	// contains filtered or unexported fields
}

PresidioClient is the production PIIScanner implementation, calling the Presidio Analyzer HTTP API.

AnalyzeBatch fans the input texts out to per-text goroutines and retries each one up to retryMaxAttempts times. Total in-flight HTTP request bytes are bounded by a process-shared byte-budget semaphore, and while blocked on the semaphore the client calls onProgress on a fixed cadence so the Temporal activity heartbeat stays alive.

Presidio is a trusted cluster-internal service, so the client uses an unsafe guardian policy with an empty blocklist. The default policy blocks RFC 1918 private ranges (10.0.0.0/8) which Kubernetes ClusterIPs fall into.

func NewPresidioClient(baseURL string, tracerProvider trace.TracerProvider, meterProvider metric.MeterProvider, logger *slog.Logger) *PresidioClient

func (p *PresidioClient) AnalyzeBatch(ctx context.Context, texts []string, entities []string, scoreThreshold float64, onProgress func()) (_ [][]scanners.Finding, err error)

type PresidioConfig ¶

type PresidioConfig struct {
	// ScoreThreshold is the minimum recognizer confidence (0.0-1.0) a match must
	// clear. Absent means "unset" — the scanner applies DefaultPresidioScoreThreshold.
	ScoreThreshold *float64 `json:"score_threshold,omitempty"`
}

PresidioConfig holds presidio-scanner options.

type RecommendedSet ¶

type RecommendedSet struct {
	// contains filtered or unexported fields
}

RecommendedSet holds the registry's scopes compiled once against the shared celenv engine. Built in the AnalyzeBatch constructor; a bad registry entry fails fast at worker boot.

func CompileRecommended(eng *celenv.Engine) (RecommendedSet, error)

type StubPIIScanner ¶

type StubPIIScanner struct{}

StubPIIScanner is a no-op implementation for environments without Presidio.

func (s *StubPIIScanner) AnalyzeBatch(_ context.Context, texts []string, _ []string, _ float64, _ func()) ([][]scanners.Finding, error)

type ToolView ¶

type ToolView struct {
	Name      string
	Server    string
	Function  string
	Arguments string
}

ToolView is one tool invocation surfaced from a message's recorded tool calls.

func NewToolView(name, arguments string) ToolView