Documentation
¶
Overview ¶
Package policy evaluates immutable, side-effect-free automation rules for semantic agent events. It deliberately does not encode or deliver a decision: callers must fall back to a human whenever an adapter cannot represent the proposed action or a delivery fails.
Package policy evaluates immutable, side-effect-free automation rules for semantic agent events. It deliberately does not encode or deliver a decision: callers must fall back to a human whenever an adapter cannot represent the proposed action or a delivery fails.
Index ¶
- Constants
- func ContainsSensitivePathReference(text string) bool
- func ExtractPaths(text string) []string
- func IsPathInsideWorkspace(candidatePath string, workspaceRoot string) bool
- func IsReadOnlyCommand(command string) bool
- func IsSensitivePath(path string) bool
- type Action
- type Config
- type Engine
- type Evaluation
- type GuardrailsConfig
- type Match
- type Profile
- type Rule
- type Tracker
Constants ¶
const ( ReasonSensitivePath = "sensitive_path_blocked" ReasonOutsideWorkspace = "outside_workspace_blocked" )
const ( ReasonDefault = "default_action" ReasonRule = "rule_match" ReasonInvalidEvent = "invalid_event" ReasonNonActionable = "non_actionable" ReasonSensitive = "sensitive_event" ReasonRisk = "risk_not_low" ReasonDryRun = "dry_run" ReasonNoEngine = "engine_unavailable" ReasonConsecutiveLimit = "consecutive_auto_limit" ReasonRateLimit = "rate_limit_exceeded" ReasonDestructive = "destructive_command_blocked" ReasonExfiltration = "exfiltration_attempt_blocked" ReasonGuardrailBlocked = "guardrail_pattern_blocked" )
Static evaluation reasons are safe to expose in logs. They never contain event text, regex matches, metadata, or other terminal output.
Variables ¶
This section is empty.
Functions ¶
func ContainsSensitivePathReference ¶ added in v0.3.0
ContainsSensitivePathReference returns true if the raw text contains explicit references to known sensitive filenames or paths.
func ExtractPaths ¶ added in v0.3.0
ExtractPaths extracts candidate file or directory paths from a shell command line or text.
func IsPathInsideWorkspace ¶ added in v0.3.0
IsPathInsideWorkspace determines whether candidatePath resides within workspaceRoot. Returns false if candidatePath attempts to escape workspaceRoot (via ../ or outside absolute paths).
func IsReadOnlyCommand ¶ added in v0.3.0
IsReadOnlyCommand determines if a shell command line is guaranteed to be a read-only query or test execution that does not modify the filesystem or execute arbitrary code.
func IsSensitivePath ¶ added in v0.3.0
IsSensitivePath returns true if the specified file or directory path matches known sensitive security credentials, private keys, environment secrets, or critical system files.
Types ¶
type Config ¶
type Config struct {
DefaultAction Action
DryRun bool
MaxConsecutiveAutoDecisions int
RateLimitPerMinute int
Guardrails GuardrailsConfig
Rules []Rule
}
Config describes the ordered rules evaluated by an Engine.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig preserves Relayer's human-in-the-loop behavior.
func ProfileConfig ¶ added in v0.3.0
ProfileConfig generates the base policy configuration for the chosen profile. The caller may override or append individual settings afterwards.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is immutable after construction and safe for concurrent evaluation.
func New ¶
New validates and defensively copies a policy configuration. Regexes are compiled once so Evaluate remains deterministic and allocation-light.
type Evaluation ¶
type Evaluation struct {
Action Action
ProposedAction Action
RuleName string
Reason string
EventID string
Automatic bool
DryRun bool
}
Evaluation separates the configured proposal from the effective action. Sensitive events and dry-run configurations retain ProposedAction for a safe audit record while forcing ActionAsk and disabling automation.
type GuardrailsConfig ¶
type GuardrailsConfig struct {
BlockDestructive bool
BlockExfiltration bool
BlockSensitivePaths bool
BlockOutsideWorkspace bool
WorkspaceRoot string
BlockedPatterns []string
}
GuardrailsConfig defines safety boundaries that prevent autonomous execution of high-risk actions even when a policy rule would otherwise allow them.
type Match ¶
type Match struct {
EventTypes []adapters.EventType
TextRegex string
AgentIDs []string
RiskLevels []adapters.RiskLevel
Sensitive *bool
CommandRegex string
PathRegex string
ReadOnly *bool
}
Match combines fields with AND semantics. Values inside each list use OR semantics. TextRegex is evaluated against Summary + "\n" + Match but that text is never retained by Engine or copied into Evaluation.
type Profile ¶ added in v0.3.0
type Profile string
Profile identifies a predefined security and automation stance.
func ParseProfile ¶ added in v0.3.0
ParseProfile parses a profile name string into a validated Profile constant. It accepts common aliases (e.g. dev-friendly, developer).
type Rule ¶
Rule applies Action when every populated Match field accepts an event. Rules are evaluated in order and the first match wins.
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker manages session-level execution history for policy guardrails, including consecutive automatic decisions and sliding-window rate limits. It is thread-safe and safe for concurrent calls across different sessions.
func NewTrackerWithClock ¶
NewTrackerWithClock creates a Tracker with a custom clock function, primarily for deterministic unit testing.
func (*Tracker) CheckLimits ¶
CheckLimits checks whether an automatic decision is allowed for the given sessionID against the configured MaxConsecutiveAutoDecisions and RateLimitPerMinute. If a limit is exceeded, it returns (ActionAsk, reason, false). If limits are respected, it returns (ActionAllow, "", true).
func (*Tracker) Consecutive ¶
Consecutive returns the current consecutive automatic decision count for the session.
func (*Tracker) RecordAutoDecision ¶
RecordAutoDecision registers that an automatic decision was delivered for the session. It increments the consecutive counter and appends the current timestamp to the history window.
func (*Tracker) RecordHumanDecision ¶
RecordHumanDecision registers that an operator intervened for the session. It resets the consecutive counter to 0. Rate limiting timestamps remain intact.
Source Files