security

Documentation

Index

• Variables
• type ApprovalQueue
  • func NewApprovalQueue(storePath string) (*ApprovalQueue, error)
  • func (q *ApprovalQueue) Approve(id, approver string, whitelistTTL time.Duration) (*ApprovalRecord, error)
  • func (q *ApprovalQueue) Deny(id, approver, reason string) (*ApprovalRecord, error)
  • func (q *ApprovalQueue) IsWhitelisted(sessionID string) bool
  • func (q *ApprovalQueue) ListPending() []*ApprovalRecord
  • func (q *ApprovalQueue) Request(sessionID, command string, paths []string) (*ApprovalRecord, error)
  • func (q *ApprovalQueue) Wait(ctx context.Context, id string) (*ApprovalRecord, error)
• type ApprovalRecord
• type ApprovalState
• type PathResolver
  • func NewPathResolver() *PathResolver
  • func (r *PathResolver) Resolve(path string) (string, error)
• type PermissionAction
• type PermissionAudit
• type PermissionDecision
• type PermissionMatcher
  • func NewPermissionMatcher(cfg *config.PermissionsConfig) (*PermissionMatcher, error)
  • func (m *PermissionMatcher) Match(toolName string, params map[string]any) PermissionDecision
• type Sandbox
  • func NewDisabledSandbox() *Sandbox
  • func NewSandbox(workDir string) *Sandbox
  • func (s *Sandbox) Allow(path string)
  • func (s *Sandbox) AllowShellMetachars(allow bool)
  • func (s *Sandbox) CheckToolPermission(toolName string, params map[string]any) (PermissionDecision, error)
  • func (s *Sandbox) LoadPermissions(projectRoot string) error
  • func (s *Sandbox) PermissionAudits() []PermissionAudit
  • func (s *Sandbox) ValidateCommand(cmd string) error
  • func (s *Sandbox) ValidatePath(path string) error
• type Validator
  • func NewValidator() *Validator
  • func (v *Validator) AllowShellMetachars(allow bool)
  • func (v *Validator) Validate(input string) error

Variables

var (
	// ErrEmptyCommand indicates the caller passed nothing to validate.
	ErrEmptyCommand = errors.New("security: empty command")
)

var (
	// ErrPathNotAllowed is returned when a path escapes the configured sandbox roots.
	ErrPathNotAllowed = errors.New("security: path not in sandbox allowlist")
)

Types

type ApprovalQueue

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

ApprovalQueue persists approvals and session-level whitelists.

func NewApprovalQueue

func NewApprovalQueue(storePath string) (*ApprovalQueue, error)

NewApprovalQueue restores queue state from disk or creates a fresh one.

func (*ApprovalQueue) Approve

func (q *ApprovalQueue) Approve(id, approver string, whitelistTTL time.Duration) (*ApprovalRecord, error)

Approve marks a pending record as approved and optionally whitelists the session.

func (*ApprovalQueue) Deny

func (q *ApprovalQueue) Deny(id, approver, reason string) (*ApprovalRecord, error)

Deny rejects a pending record.

func (*ApprovalQueue) IsWhitelisted

func (q *ApprovalQueue) IsWhitelisted(sessionID string) bool

IsWhitelisted reports whether the session currently bypasses manual review.

func (*ApprovalQueue) ListPending

func (q *ApprovalQueue) ListPending() []*ApprovalRecord

ListPending returns outstanding approvals for review.

func (*ApprovalQueue) Request

func (q *ApprovalQueue) Request(sessionID, command string, paths []string) (*ApprovalRecord, error)

Request enqueues a command for approval. Whitelisted sessions auto-pass.

func (*ApprovalQueue) Wait

func (q *ApprovalQueue) Wait(ctx context.Context, id string) (*ApprovalRecord, error)

Wait blocks until the approval is resolved or the context is cancelled.

type ApprovalRecord

type ApprovalRecord struct {
	ID           string        `json:"id"`
	SessionID    string        `json:"session_id"`
	Command      string        `json:"command"`
	Paths        []string      `json:"paths"`
	State        ApprovalState `json:"state"`
	RequestedAt  time.Time     `json:"requested_at"`
	ApprovedAt   *time.Time    `json:"approved_at,omitempty"`
	Approver     string        `json:"approver,omitempty"`
	Reason       string        `json:"reason,omitempty"`
	ExpiresAt    *time.Time    `json:"expires_at,omitempty"`
	AutoApproved bool          `json:"auto_approved"`
}

ApprovalRecord captures one approval decision.

type ApprovalState

type ApprovalState string

ApprovalState is the human approval lifecycle.

const (
	ApprovalPending  ApprovalState = "pending"
	ApprovalApproved ApprovalState = "approved"
	ApprovalDenied   ApprovalState = "denied"
)

type PathResolver

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

PathResolver is the third low-level guard: it refuses symlink escapes.

func NewPathResolver

func NewPathResolver() *PathResolver

NewPathResolver creates a resolver that forbids excessive nesting and symlinks.

func (*PathResolver) Resolve

func (r *PathResolver) Resolve(path string) (string, error)

Resolve canonicalises a path and rejects symlinks along the way.

type PermissionAction

type PermissionAction string

PermissionAction represents the enforcement outcome for a tool invocation.

const (
	PermissionUnknown PermissionAction = "unknown"
	PermissionAllow   PermissionAction = "allow"
	PermissionAsk     PermissionAction = "ask"
	PermissionDeny    PermissionAction = "deny"
)

type PermissionAudit

type PermissionAudit struct {
	Tool      string
	Target    string
	Rule      string
	Action    PermissionAction
	Timestamp time.Time
}

PermissionAudit records executed decisions for later inspection.

type PermissionDecision

type PermissionDecision struct {
	Action PermissionAction
	Rule   string
	Tool   string
	Target string
}

PermissionDecision captures the matched rule and derived target string.

type PermissionMatcher

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

PermissionMatcher evaluates tool calls against allow/ask/deny rules.

func NewPermissionMatcher

func NewPermissionMatcher(cfg *config.PermissionsConfig) (*PermissionMatcher, error)

NewPermissionMatcher builds a matcher from the provided permissions config. A nil config yields a nil matcher and no error.

func (*PermissionMatcher) Match

func (m *PermissionMatcher) Match(toolName string, params map[string]any) PermissionDecision

Match resolves the decision for a tool invocation. Priority: deny > ask > allow.

type Sandbox

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

Sandbox is the first defensive layer: filesystem boundaries and command checks.

func NewDisabledSandbox

func NewDisabledSandbox() *Sandbox

NewDisabledSandbox creates a sandbox that skips path validation but still enforces command safety. Disabling sandbox means "allow access to full filesystem", not "allow dangerous commands".

func NewSandbox

func NewSandbox(workDir string) *Sandbox

NewSandbox creates a sandbox rooted at workDir.

func (*Sandbox) Allow

func (s *Sandbox) Allow(path string)

Allow registers additional absolute prefixes that commands may touch.

func (*Sandbox) AllowShellMetachars

func (s *Sandbox) AllowShellMetachars(allow bool)

AllowShellMetachars enables shell pipes and metacharacters (CLI mode).

func (*Sandbox) CheckToolPermission

func (s *Sandbox) CheckToolPermission(toolName string, params map[string]any) (PermissionDecision, error)

CheckToolPermission evaluates tool invocation against configured allow/ask/deny rules. Denials and prompts are returned to the caller; missing or empty rules default to allow to preserve backward compatibility.

func (*Sandbox) LoadPermissions

func (s *Sandbox) LoadPermissions(projectRoot string) error

LoadPermissions parses permissions rules from the layered .claude/settings*.json files rooted at projectRoot. Missing files are tolerated. When called multiple times the latest rules replace any previously loaded matcher.

func (*Sandbox) PermissionAudits

func (s *Sandbox) PermissionAudits() []PermissionAudit

PermissionAudits returns a snapshot of audited permission decisions.

func (*Sandbox) ValidateCommand

func (s *Sandbox) ValidateCommand(cmd string) error

ValidateCommand is the second defense line, preventing obviously dangerous commands. Note: Command validation (rm -rf, etc.) is ALWAYS enforced, even when sandbox is disabled. Only path validation respects the disabled flag.

func (*Sandbox) ValidatePath

func (s *Sandbox) ValidatePath(path string) error

ValidatePath ensures the path resolves within the sandbox allow list.

type Validator

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

Validator represents the second defensive ring: it blocks obviously dangerous intent.

func NewValidator

func NewValidator() *Validator

NewValidator initialises the validator with conservative defaults.

func (*Validator) AllowShellMetachars

func (v *Validator) AllowShellMetachars(allow bool)

AllowShellMetachars enables pipe and other shell features (CLI mode).

func (*Validator) Validate

func (v *Validator) Validate(input string) error

Validate checks the provided command string.