agentic

package
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 15, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package agentic provides security analysis for AI coding assistants. It detects critical threats (config writes, invisible unicode) and performs Rule of Two analysis to detect potential security violations where an action combines more than two of: [A] untrustworthy inputs, [B] sensitive access, [C] state changes or external communication.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatBlockMessage 

func FormatBlockMessage(result *AnalysisResult) string

FormatBlockMessage creates a formatted error message for blocked operations.

func GenerateCursorDisabledOutput 

func GenerateCursorDisabledOutput() ([]byte, int, string)

GenerateCursorDisabledOutput creates output when agentic checks are disabled.

func GenerateCursorOutput 

func GenerateCursorOutput(result *AnalysisResult) ([]byte, int, string)

GenerateCursorOutput converts analysis results to Cursor output format. Returns (jsonOutput, exitCode, stderrMessage).

func GenerateCursorThreatOutput 

func GenerateCursorThreatOutput(threat *CriticalThreat) ([]byte, int, string)

GenerateCursorThreatOutput converts critical threat to Cursor output format. Returns (jsonOutput, exitCode, stderrMessage).

func IsDebug 

func IsDebug() bool

IsDebug returns true if debug mode is enabled via environment.

func IsDisabled 

func IsDisabled() bool

IsDisabled returns true if agentic mode is disabled via environment.

Types

type AgentType 

type AgentType string

AgentType represents the type of AI coding assistant. 

const (
	// AgentUnknown indicates the agent type could not be determined.
	AgentUnknown AgentType = "unknown"
	// AgentClaudeCode indicates Claude Code (Anthropic's CLI).
	AgentClaudeCode AgentType = "claude_code"
	// AgentCursor indicates Cursor IDE.
	AgentCursor AgentType = "cursor"
)

func DetectAgent 

func DetectAgent() AgentType

DetectAgent returns the agent type based on environment variables. Priority: CURSOR_AGENT=1 > CLAUDECODE=1 > unknown

func DetectAgentFromInput 

func DetectAgentFromInput(raw []byte) AgentType

DetectAgentFromInput attempts to determine the agent type from the JSON input structure. This is used as a fallback when environment variable detection fails.

type AgenticMode 

type AgenticMode string

AgenticMode controls behavior when Rule of Two is violated. 

const (
	// ModeBlock blocks the action with exit code 2.
	ModeBlock AgenticMode = "block"
	// ModeAsk prompts user for confirmation instead of blocking.
	ModeAsk AgenticMode = "ask"
)

func GetAgenticMode 

func GetAgenticMode() AgenticMode

GetAgenticMode returns the configured agentic mode from environment.

type AnalysisResult 

type AnalysisResult struct {
	ToolName    string
	CapabilityA CapabilityResult // Untrustworthy inputs
	CapabilityB CapabilityResult // Sensitive access
	CapabilityC CapabilityResult // State change/external comms
	SignalHits  []string         // Which dashlights signals also triggered
}

AnalysisResult captures the complete Rule of Two analysis for a tool call.

func (*AnalysisResult) AllReasons 

func (r *AnalysisResult) AllReasons() []string

AllReasons collects all detection reasons across capabilities.

func (*AnalysisResult) CapabilityCount 

func (r *AnalysisResult) CapabilityCount() int

CapabilityCount returns how many capabilities were detected.

func (*AnalysisResult) CapabilityString 

func (r *AnalysisResult) CapabilityString() string

CapabilityString returns a string like "A+B" or "A+B+C" for detected capabilities.

func (*AnalysisResult) ViolatesRuleOfTwo 

func (r *AnalysisResult) ViolatesRuleOfTwo() bool

ViolatesRuleOfTwo returns true if all three capabilities are detected.

type Analyzer 

type Analyzer struct {
	// RunSignals controls whether to run dashlights signals for enhanced detection.
	RunSignals bool
	// SignalTimeout is the timeout for running signals (default 5ms).
	SignalTimeout time.Duration
}

Analyzer performs Rule of Two analysis on tool calls.

func NewAnalyzer 

func NewAnalyzer() *Analyzer

NewAnalyzer creates an Analyzer with default settings.

func (*Analyzer) Analyze 

func (a *Analyzer) Analyze(input *HookInput) *AnalysisResult

Analyze performs Rule of Two analysis on a hook input.

type BashInput 

type BashInput struct {
	Command     string `json:"command"`
	Description string `json:"description,omitempty"`
	Timeout     int    `json:"timeout,omitempty"`
}

BashInput represents the tool_input for Bash tool calls.

func ParseBashInput 

func ParseBashInput(input map[string]interface{}) BashInput

ParseBashInput extracts BashInput from generic tool_input map.

type Capability 

type Capability int

Capability represents one of the three Rule of Two capabilities. 

const (
	// CapabilityA represents processing untrustworthy inputs.
	CapabilityA Capability = iota
	// CapabilityB represents access to sensitive systems or data.
	CapabilityB
	// CapabilityC represents state changes or external communication.
	CapabilityC
)

func (Capability) String 

func (c Capability) String() string

String returns a human-readable name for the capability.

type CapabilityResult 

type CapabilityResult struct {
	Detected bool
	Reasons  []string
}

CapabilityResult holds the detection result for a single capability.

func DetectCapabilityA 

func DetectCapabilityA(toolName string, input map[string]interface{}, cwd string) CapabilityResult

DetectCapabilityA checks for untrustworthy input processing.

func DetectCapabilityB 

func DetectCapabilityB(toolName string, input map[string]interface{}) CapabilityResult

DetectCapabilityB checks for access to sensitive systems or data.

func DetectCapabilityC 

func DetectCapabilityC(toolName string, input map[string]interface{}) CapabilityResult

DetectCapabilityC checks for state changes or external communication.

type CriticalThreat 

type CriticalThreat struct {
	Type    string // "agent_config_write", "invisible_unicode"
	Details string
	// AllowAskMode indicates whether DASHLIGHTS_AGENTIC_MODE=ask should prompt
	// instead of blocking. Agent config writes always block (false).
	AllowAskMode bool
}

CriticalThreat represents a security threat that bypasses Rule of Two scoring. These are threats that warrant immediate blocking regardless of capability count.

func DetectCriticalThreat 

func DetectCriticalThreat(input *HookInput) *CriticalThreat

DetectCriticalThreat checks for threats that bypass Rule of Two scoring. Returns nil if no critical threat is detected.

type CursorOutput 

type CursorOutput struct {
	Permission   string `json:"permission"`              // "allow", "deny", "ask"
	UserMessage  string `json:"user_message,omitempty"`  // Shown in client
	AgentMessage string `json:"agent_message,omitempty"` // Sent to agent
}

CursorOutput represents the output format expected by Cursor hooks.

type CursorShellInput 

type CursorShellInput struct {
	ConversationID string   `json:"conversation_id"`
	GenerationID   string   `json:"generation_id"`
	Model          string   `json:"model"`
	Command        string   `json:"command"`
	Cwd            string   `json:"cwd"`
	HookEventName  string   `json:"hook_event_name"`
	CursorVersion  string   `json:"cursor_version"`
	WorkspaceRoots []string `json:"workspace_roots"`
	UserEmail      *string  `json:"user_email"`
}

CursorShellInput represents the input format for Cursor beforeShellExecution hook.

type EditInput 

type EditInput struct {
	FilePath  string `json:"file_path"`
	OldString string `json:"old_string"`
	NewString string `json:"new_string"`
}

EditInput represents the tool_input for Edit tool calls.

func ParseEditInput 

func ParseEditInput(input map[string]interface{}) EditInput

ParseEditInput extracts EditInput from generic tool_input map.

type GlobInput 

type GlobInput struct {
	Pattern string `json:"pattern"`
	Path    string `json:"path,omitempty"`
}

GlobInput represents the tool_input for Glob tool calls.

func ParseGlobInput 

func ParseGlobInput(input map[string]interface{}) GlobInput

ParseGlobInput extracts GlobInput from generic tool_input map.

type GrepInput 

type GrepInput struct {
	Pattern string `json:"pattern"`
	Path    string `json:"path,omitempty"`
	Glob    string `json:"glob,omitempty"`
}

GrepInput represents the tool_input for Grep tool calls.

func ParseGrepInput 

func ParseGrepInput(input map[string]interface{}) GrepInput

ParseGrepInput extracts GrepInput from generic tool_input map.

type HookInput 

type HookInput struct {
	SessionID      string                 `json:"session_id"`
	TranscriptPath string                 `json:"transcript_path,omitempty"`
	Cwd            string                 `json:"cwd"`
	HookEventName  string                 `json:"hook_event_name"`
	ToolName       string                 `json:"tool_name"`
	ToolInput      map[string]interface{} `json:"tool_input"`
	ToolUseID      string                 `json:"tool_use_id,omitempty"`
}

HookInput represents the JSON input from Claude Code PreToolUse hook. This structure matches the JSON schema provided by Claude Code's hook system.

func ParseCursorInput 

func ParseCursorInput(raw []byte) (*HookInput, error)

ParseCursorInput parses Cursor hook input and normalizes it to HookInput.

type HookOutput 

type HookOutput struct {
	HookSpecificOutput *HookSpecificOutput `json:"hookSpecificOutput,omitempty"`
	SystemMessage      string              `json:"systemMessage,omitempty"`
}

HookOutput represents the JSON output for Claude Code PreToolUse hooks.

func GenerateOutput 

func GenerateOutput(result *AnalysisResult) (*HookOutput, int, string)

GenerateOutput creates the appropriate hook output based on analysis results. Returns (output, exitCode, stderrMessage). - exitCode 0: allow (with optional systemMessage warning) - exitCode 2: block (stderrMessage contains error)

func GenerateThreatOutput 

func GenerateThreatOutput(threat *CriticalThreat) (*HookOutput, int, string)

GenerateThreatOutput creates the appropriate hook output for a critical threat. Returns (output, exitCode, stderrMessage).

type HookSpecificOutput 

type HookSpecificOutput struct {
	HookEventName            string `json:"hookEventName"`
	PermissionDecision       string `json:"permissionDecision"`
	PermissionDecisionReason string `json:"permissionDecisionReason"`
}

HookSpecificOutput contains PreToolUse-specific response fields.

type InvisibleCharInfo 

type InvisibleCharInfo struct {
	Rune     rune
	Name     string
	Position int
	Context  string // surrounding characters for display
	Field    string // which input field contained this character
}

InvisibleCharInfo describes a detected invisible Unicode character.

type ReadInput 

type ReadInput struct {
	FilePath string `json:"file_path"`
	Offset   int    `json:"offset,omitempty"`
	Limit    int    `json:"limit,omitempty"`
}

ReadInput represents the tool_input for Read tool calls.

func ParseReadInput 

func ParseReadInput(input map[string]interface{}) ReadInput

ParseReadInput extracts ReadInput from generic tool_input map.

type WebFetchInput 

type WebFetchInput struct {
	URL    string `json:"url"`
	Prompt string `json:"prompt"`
}

WebFetchInput represents the tool_input for WebFetch tool calls.

func ParseWebFetchInput 

func ParseWebFetchInput(input map[string]interface{}) WebFetchInput

ParseWebFetchInput extracts WebFetchInput from generic tool_input map.

type WebSearchInput 

type WebSearchInput struct {
	Query string `json:"query"`
}

WebSearchInput represents the tool_input for WebSearch tool calls.

func ParseWebSearchInput 

func ParseWebSearchInput(input map[string]interface{}) WebSearchInput

ParseWebSearchInput extracts WebSearchInput from generic tool_input map.

type WriteInput 

type WriteInput struct {
	FilePath string `json:"file_path"`
	Content  string `json:"content"`
}

WriteInput represents the tool_input for Write tool calls.

func ParseWriteInput 

func ParseWriteInput(input map[string]interface{}) WriteInput

ParseWriteInput extracts WriteInput from generic tool_input map.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.