Documentation
¶
Overview ¶
Package plugin defines the Shield plugin system with opt-in lifecycle hooks.
Plugins implement the base Plugin interface and optionally implement one or more lifecycle hook interfaces to receive events they care about. This follows the same pattern used by Weave and Cortex.
Index ¶
- Constants
- type AwarenessDetected
- type BoundaryEnforced
- type InstinctTriggered
- type JudgmentAssessed
- type PIIDetected
- type PIIRedacted
- type Plugin
- type PolicyEvaluated
- type ReflexFired
- type Registry
- func (r *Registry) EmitAwarenessDetected(ctx context.Context, scanID id.ScanID, detectorName string, findingCount int)
- func (r *Registry) EmitBoundaryEnforced(ctx context.Context, scanID id.ScanID, boundaryName string)
- func (r *Registry) EmitInstinctTriggered(ctx context.Context, scanID id.ScanID, instinctName string, score float64)
- func (r *Registry) EmitJudgmentAssessed(ctx context.Context, scanID id.ScanID, assessorName, riskLevel string, ...)
- func (r *Registry) EmitPIIDetected(ctx context.Context, scanID id.ScanID, piiType string, count int)
- func (r *Registry) EmitPIIRedacted(ctx context.Context, scanID id.ScanID, piiType string, count int)
- func (r *Registry) EmitPolicyEvaluated(ctx context.Context, scanID id.ScanID, policyName, decision string)
- func (r *Registry) EmitReflexFired(ctx context.Context, scanID id.ScanID, reflexName, action string)
- func (r *Registry) EmitSafetyProfileResolved(ctx context.Context, scanID id.ScanID, profileName string)
- func (r *Registry) EmitScanBlocked(ctx context.Context, scanID id.ScanID, reason string)
- func (r *Registry) EmitScanCompleted(ctx context.Context, scanID id.ScanID, decision string, findingCount int, ...)
- func (r *Registry) EmitScanFailed(ctx context.Context, scanID id.ScanID, err error)
- func (r *Registry) EmitScanStarted(ctx context.Context, scanID id.ScanID, direction, text string)
- func (r *Registry) EmitShutdown(ctx context.Context)
- func (r *Registry) EmitValueViolated(ctx context.Context, scanID id.ScanID, valueName, severity string)
- func (r *Registry) Register(p Plugin)
- func (r *Registry) SetLogger(l log.Logger)
- func (r *Registry) SetMetrics(m gometrics.Metrics)
- type SafetyProfileResolved
- type ScanBlocked
- type ScanCompleted
- type ScanFailed
- type ScanStarted
- type Shutdown
- type ValueViolated
Constants ¶
const HooksFailedMetric = "shield_plugin_hooks_failed_total"
HooksFailedMetric counts hook calls that returned an error, labelled by hook. A Forge app scrapes it as forge_shield_plugin_hooks_failed_total.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AwarenessDetected ¶
type AwarenessDetected interface {
OnAwarenessDetected(ctx context.Context, scanID id.ScanID, detectorName string, findingCount int) error
}
AwarenessDetected is called when awareness detects something notable.
type BoundaryEnforced ¶
type BoundaryEnforced interface {
OnBoundaryEnforced(ctx context.Context, scanID id.ScanID, boundaryName string) error
}
BoundaryEnforced is called when a boundary prevents an action.
type InstinctTriggered ¶
type InstinctTriggered interface {
OnInstinctTriggered(ctx context.Context, scanID id.ScanID, instinctName string, score float64) error
}
InstinctTriggered is called when a safety instinct fires.
type JudgmentAssessed ¶
type JudgmentAssessed interface {
OnJudgmentAssessed(ctx context.Context, scanID id.ScanID, assessorName string, riskLevel string, confidence float64) error
}
JudgmentAssessed is called when a judgment assessor produces a risk assessment.
type PIIDetected ¶
type PIIDetected interface {
OnPIIDetected(ctx context.Context, scanID id.ScanID, piiType string, count int) error
}
PIIDetected is called when PII is found in content.
type PIIRedacted ¶
type PIIRedacted interface {
OnPIIRedacted(ctx context.Context, scanID id.ScanID, piiType string, count int) error
}
PIIRedacted is called when PII is redacted from content.
type Plugin ¶
type Plugin interface {
Name() string
}
Plugin is the base interface all Shield plugins must implement.
type PolicyEvaluated ¶
type PolicyEvaluated interface {
OnPolicyEvaluated(ctx context.Context, scanID id.ScanID, policyName string, decision string) error
}
PolicyEvaluated is called when a policy is evaluated.
type ReflexFired ¶
type ReflexFired interface {
OnReflexFired(ctx context.Context, scanID id.ScanID, reflexName string, action string) error
}
ReflexFired is called when a safety reflex triggers an action.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered plugins and dispatches lifecycle events. It type-caches plugins at registration time so emit calls iterate only over plugins that implement the relevant hook.
func NewRegistry ¶
NewRegistry creates a new plugin registry.
func (*Registry) EmitAwarenessDetected ¶
func (r *Registry) EmitAwarenessDetected(ctx context.Context, scanID id.ScanID, detectorName string, findingCount int)
EmitAwarenessDetected notifies all plugins that implement AwarenessDetected.
func (*Registry) EmitBoundaryEnforced ¶
EmitBoundaryEnforced notifies all plugins that implement BoundaryEnforced.
func (*Registry) EmitInstinctTriggered ¶
func (r *Registry) EmitInstinctTriggered(ctx context.Context, scanID id.ScanID, instinctName string, score float64)
EmitInstinctTriggered notifies all plugins that implement InstinctTriggered.
func (*Registry) EmitJudgmentAssessed ¶
func (r *Registry) EmitJudgmentAssessed(ctx context.Context, scanID id.ScanID, assessorName, riskLevel string, confidence float64)
EmitJudgmentAssessed notifies all plugins that implement JudgmentAssessed.
func (*Registry) EmitPIIDetected ¶
func (r *Registry) EmitPIIDetected(ctx context.Context, scanID id.ScanID, piiType string, count int)
EmitPIIDetected notifies all plugins that implement PIIDetected.
func (*Registry) EmitPIIRedacted ¶
func (r *Registry) EmitPIIRedacted(ctx context.Context, scanID id.ScanID, piiType string, count int)
EmitPIIRedacted notifies all plugins that implement PIIRedacted.
func (*Registry) EmitPolicyEvaluated ¶
func (r *Registry) EmitPolicyEvaluated(ctx context.Context, scanID id.ScanID, policyName, decision string)
EmitPolicyEvaluated notifies all plugins that implement PolicyEvaluated.
func (*Registry) EmitReflexFired ¶
func (r *Registry) EmitReflexFired(ctx context.Context, scanID id.ScanID, reflexName, action string)
EmitReflexFired notifies all plugins that implement ReflexFired.
func (*Registry) EmitSafetyProfileResolved ¶
func (r *Registry) EmitSafetyProfileResolved(ctx context.Context, scanID id.ScanID, profileName string)
EmitSafetyProfileResolved notifies all plugins that implement SafetyProfileResolved.
func (*Registry) EmitScanBlocked ¶
EmitScanBlocked notifies all plugins that implement ScanBlocked.
func (*Registry) EmitScanCompleted ¶
func (r *Registry) EmitScanCompleted(ctx context.Context, scanID id.ScanID, decision string, findingCount int, elapsed time.Duration)
EmitScanCompleted notifies all plugins that implement ScanCompleted.
func (*Registry) EmitScanFailed ¶
EmitScanFailed notifies all plugins that implement ScanFailed.
func (*Registry) EmitScanStarted ¶
EmitScanStarted notifies all plugins that implement ScanStarted.
func (*Registry) EmitShutdown ¶
EmitShutdown notifies all plugins that implement Shutdown.
func (*Registry) EmitValueViolated ¶
func (r *Registry) EmitValueViolated(ctx context.Context, scanID id.ScanID, valueName, severity string)
EmitValueViolated notifies all plugins that implement ValueViolated.
func (*Registry) SetLogger ¶
SetLogger replaces the logger hook errors are reported on. A nil l is ignored. Call it before the first Emit.
func (*Registry) SetMetrics ¶
SetMetrics counts failed hook calls on m as HooksFailedMetric. In a Forge app pass app.Metrics(); the engine does this for you with engine.WithMetrics. A nil m records nothing. Call it before the first Emit.
type SafetyProfileResolved ¶
type SafetyProfileResolved interface {
OnSafetyProfileResolved(ctx context.Context, scanID id.ScanID, profileName string) error
}
SafetyProfileResolved is called when a safety profile is resolved for a scan.
type ScanBlocked ¶
type ScanBlocked interface {
OnScanBlocked(ctx context.Context, scanID id.ScanID, reason string) error
}
ScanBlocked is called when a scan results in content being blocked.
type ScanCompleted ¶
type ScanCompleted interface {
OnScanCompleted(ctx context.Context, scanID id.ScanID, decision string, findingCount int, elapsed time.Duration) error
}
ScanCompleted is called when a scan finishes successfully.
type ScanFailed ¶
ScanFailed is called when a scan fails with an error.
type ScanStarted ¶
type ScanStarted interface {
OnScanStarted(ctx context.Context, scanID id.ScanID, direction string, text string) error
}
ScanStarted is called when a safety scan begins.
Source Files