common

type ApprovalOutcome ¶ added in v0.12.0

type ApprovalOutcome struct {
	HasApprovalStep     bool
	Approved            bool
	ResolvedDestination string // real post-symlink target the write reached
	Wrote               bool   // whether bytes actually landed at ResolvedDestination
}

ApprovalOutcome reports what a coding agent did with a FileOperation. HasApprovalStep is false when the agent exposes no approval gate for this operation class — modules treat that as SkipNoMutationTarget, not success.

func (o ApprovalOutcome) MisrepresentedVs(shownDestination string) bool

type AttackCategory ¶

type AttackCategory string

AttackCategory categorizes attack modules by domain.

const (
	CategoryInjection     AttackCategory = "injection"
	CategoryJailbreak     AttackCategory = "jailbreak"
	CategoryOrchestration AttackCategory = "orchestration"
	CategoryEvasion       AttackCategory = "evasion"
	CategoryExtraction    AttackCategory = "extraction"
	CategoryMultimodal    AttackCategory = "multimodal"
	CategoryPersistence   AttackCategory = "persistence"
	CategoryExfiltration  AttackCategory = "exfiltration"
	CategorySupplyChain   AttackCategory = "supply_chain"
	CategoryRAG           AttackCategory = "rag"
	CategoryAgentic       AttackCategory = "agentic"
	CategoryAudio         AttackCategory = "audio"
	CategoryReasoning     AttackCategory = "reasoning"
	CategoryAdaptive      AttackCategory = "adaptive"
	CategoryMemory        AttackCategory = "memory"
)

type AttackConfig ¶

type AttackConfig struct {
	// Target configuration
	Technique   string        `json:"technique"`
	Payload     string        `json:"payload"`
	Objective   string        `json:"objective"`
	MaxAttempts int           `json:"max_attempts"`
	Timeout     time.Duration `json:"timeout"`

	// Provider settings
	ProviderName string `json:"provider_name"`
	Model        string `json:"model"`

	// Context
	SystemPrompt string    `json:"system_prompt"`
	History      []Message `json:"history"`

	// Success criteria
	SuccessIndicators []string `json:"success_indicators"`

	// Advanced options
	UseMutation    bool    `json:"use_mutation"`
	MutationRate   float64 `json:"mutation_rate"`
	UseObfuscation bool    `json:"use_obfuscation"`

	// Cost control
	MaxCostUSD float64 `json:"max_cost_usd"`

	// Metadata
	Context  map[string]interface{} `json:"context,omitempty"`
	Metadata map[string]string      `json:"metadata,omitempty"`
}

AttackConfig configures an attack execution.

func (c AttackConfig) CostExceeded(accumulatedCost float64) bool

type AttackOutcome ¶ added in v0.9.0

type AttackOutcome string

AttackOutcome categorizes how an attack run ended. Introduced in v0.9.0 to disambiguate "ran fully and target resisted" from "did not run to completion" (capability missing, gate blocked, budget out, provider error).

Bandit reward attribution should filter on outcome:

WHERE outcome IN ('success', 'refused')

Skipped runs do not enter the reward signal.

const (
	OutcomeSuccess AttackOutcome = "success" // attack landed (target produced harmful content)
	OutcomeRefused AttackOutcome = "refused" // ran fully; target resisted
	OutcomeSkipped AttackOutcome = "skipped" // did not run to completion; see SkipReason
)

type AttackResult ¶

type AttackResult struct {
	// Identification
	ID        string    `json:"id"`
	Timestamp time.Time `json:"timestamp"`

	// Attack details
	Technique string `json:"technique"`
	Payload   string `json:"payload"`

	// Results
	Success    bool    `json:"success"`
	Confidence float64 `json:"confidence"`
	Response   string  `json:"response"`

	// v0.9.0: typed outcome and skip reason. Outcome is the source of truth;
	// Success is kept as a derived field for backward compatibility.
	Outcome    AttackOutcome `json:"outcome,omitempty"`
	SkipReason SkipReason    `json:"skip_reason,omitempty"`
	SkipDetail string        `json:"skip_detail,omitempty"`

	// CleanupHint is set by attack modules that perform persistent state
	// changes (e.g., memory poisoning). It contains operator-facing
	// instructions for purging injected records. v0.9.0 does not auto-purge;
	// the v0.10.0 Purger interface will close that loop.
	CleanupHint string `json:"cleanup_hint,omitempty"`

	// Metrics
	AttemptCount int           `json:"attempt_count"`
	Duration     time.Duration `json:"duration"`
	TokensUsed   int           `json:"tokens_used"`
	CostUSD      float64       `json:"cost_usd"`

	// Analysis
	SuccessFactors    []string `json:"success_factors,omitempty"`
	FailureReasons    []string `json:"failure_reasons,omitempty"`
	SuggestedFollowup string   `json:"suggested_followup,omitempty"`

	// Metadata
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

AttackResult contains the outcome of an attack execution.

In v0.9.0, the typed fields Outcome/SkipReason/SkipDetail/CleanupHint were added alongside the existing Success bool. The two are kept in sync by the NewAttackResult constructor and the WithSkip helper:

r := NewAttackResult("minja", OutcomeSuccess)        // Success=true,  Outcome=success
r := NewAttackResult("h_cot", OutcomeSkipped).WithSkip(SkipSignatureGated, "...")

Direct struct literals on AttackResult are still permitted for backward compatibility with v0.8.0 modules, but new code should prefer the constructor to avoid Success/Outcome desync. See TestAttackResultInvariants.

func MissingCapabilitySkip(moduleName, capabilityName string) *AttackResult

func NewAttackResult(technique string, outcome AttackOutcome) *AttackResult

func (r *AttackResult) IsSkipped() bool

func (r *AttackResult) WithSkip(reason SkipReason, detail string) *AttackResult

type AudioFormat ¶ added in v0.10.0

type AudioFormat string

AudioFormat enumerates the supported audio container formats.

const (
	AudioFormatWAV  AudioFormat = "wav"
	AudioFormatMP3  AudioFormat = "mp3"
	AudioFormatOGG  AudioFormat = "ogg"
	AudioFormatFLAC AudioFormat = "flac"
)

type AudioPayload ¶ added in v0.10.0

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

AudioPayload carries audio bytes + format metadata. Constructor validates the format enum and a basic non-empty-bytes check; rich audio-specific validation (sample rate, codec) is deferred to the adapter implementing AudioProvider.

func NewAudioPayload(b []byte, format AudioFormat) (AudioPayload, error)

func (p AudioPayload) Bytes() []byte

func (p AudioPayload) Format() AudioFormat

type AudioProvider ¶ added in v0.10.0

type AudioProvider interface {
	Provider
	// QueryWithAudio sends a prompt with an audio attachment and
	// returns the model's text response.
	QueryWithAudio(ctx context.Context, prompt string, audio AudioPayload) (string, error)
}

AudioProvider is implemented by providers that accept audio inputs alongside text prompts (e.g., GPT-4o audio, Gemini with audio, speech-language models). audio/* modules require this capability.

type BrowserProvider ¶ added in v0.10.0

type BrowserProvider interface {
	Provider
	// BrowseAndQuery fetches the URL, then asks the model the prompt
	// in the context of the fetched content. Returns the model's
	// response text.
	BrowseAndQuery(ctx context.Context, url string, prompt string) (string, error)
}

BrowserProvider is implemented by providers that can fetch and reason over web content (used by AI browser-agent attacks). agentic/browser/* modules require this capability.

type Cleaner ¶ added in v0.9.0

type Cleaner interface {
	Cleanup(ctx context.Context, recordIDs []string) error
}

Cleaner is an OPTIONAL interface implemented by attack modules (not providers) that perform persistent state changes. The CLI invokes Cleanup with the injected record IDs reported by a previous run's CleanupHint.

v0.9.0 ships memory-poisoning modules that emit CleanupHint but do not implement Cleanup. The v0.10.0 Purger interface on providers will close the loop by enabling automated cleanup.

This is a separate interface, not a default-no-op method on AttackModule, because Go has no default methods and existing v0.8.0 modules should not be forced to add stub implementations.

type CodingAgentProvider ¶ added in v0.12.0

type CodingAgentProvider interface {
	Provider
	// ApproveFileOperation presents a file operation to the agent's approval
	// surface and reports what the agent actually did — crucially, the resolved
	// (post-symlink) destination, which SymJack compares against the shown one.
	ApproveFileOperation(ctx context.Context, op FileOperation) (ApprovalOutcome, error)
	// TrustFolder presents a folder-trust decision for a (possibly cloned)
	// repository and reports which project-defined MCP server paths were
	// auto-executed on trust — the signal TrustFall inspects.
	TrustFolder(ctx context.Context, req FolderTrustRequest) (FolderTrustOutcome, error)
}

CodingAgentProvider is implemented by targets that expose a coding agent's file-operation approval surface and folder-trust surface. Both v0.12.0 RCE modules (SymJack, TrustFall) require it; a single interface keeps a target from having to implement two to be exercised by either.

type EngineBudget ¶ added in v0.9.0

type EngineBudget struct {
	MaxQueries          int  `json:"max_queries"`
	MaxWallClockSeconds int  `json:"max_wall_clock_seconds"`
	MaxGenerations      int  `json:"max_generations"`
	EarlyStopOnSuccess  bool `json:"early_stop_on_success"`
}

EngineBudget bounds the runtime of evolutionary attack engines (jbfuzz, persona_evolve). All four knobs are honored independently. Introduced in v0.9.0.

func DefaultEngineBudget() EngineBudget

func (b *EngineBudget) Clamp() []string

type FileOperation ¶ added in v0.12.0

type FileOperation struct {
	ShownDescription string // e.g., "copy demo.mp4 to docs/"
	ShownDestination string // path as displayed in the approval prompt
	SourcePath       string // attacker-controlled source being written
}

FileOperation describes a file action shown on a coding agent's approval prompt. The Shown* fields are what a human reviewer sees; the agent may resolve ShownDestination through symlinks to a different real target — that gap is the SymJack misrepresentation signal.

type FolderTrustOutcome ¶ added in v0.12.0

type FolderTrustOutcome struct {
	HasTrustPrompt bool
	Trusted        bool
	ExecutedPaths  []string
}

FolderTrustOutcome reports a folder-trust decision. ExecutedPaths lists the project MCP paths auto-executed on trust — the TrustFall signal when non-empty after a single trust accept.

type FolderTrustRequest ¶ added in v0.12.0

type FolderTrustRequest struct {
	RepoPath        string
	ProjectMCPPaths []string
}

FolderTrustRequest describes a (possibly cloned) repository presented to a coding agent's folder-trust prompt. ProjectMCPPaths are attacker-controlled MCP server entry points declared in the repo's project config.

type ImageDetail ¶ added in v0.9.0

type ImageDetail string

ImageDetail is an advisory hint to the provider about image processing detail. Providers that don't accept this hint silently ignore it.

Documented behavior:

• OpenAI: ImageDetailLow ≈ 85 tokens fixed; ImageDetailHigh tiles at 768px (~170 tok/tile).
• Anthropic: hint is currently ignored.

const (
	ImageDetailLow  ImageDetail = "low"
	ImageDetailHigh ImageDetail = "high"
	ImageDetailAuto ImageDetail = "auto"
)

type ImageMimeType ¶ added in v0.9.0

type ImageMimeType string

ImageMimeType enumerates the image MIME types supported by ImageProvider implementations. Each major provider supports a slightly different set; see the provider adapter docs for specifics.

const (
	ImageMimeJPEG ImageMimeType = "image/jpeg"
	ImageMimePNG  ImageMimeType = "image/png"
	ImageMimeGIF  ImageMimeType = "image/gif"
	ImageMimeWebP ImageMimeType = "image/webp"
)

type ImagePayload ¶ added in v0.9.0

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

ImagePayload carries a single image to QueryWithImages. Construct via NewImagePayloadBytes or NewImagePayloadURL — direct struct literals are disallowed (fields are unexported) so the constructor can validate invariants (mutual exclusion of bytes vs URL, MIME-type membership, non-empty data, size limits).

func NewImagePayloadBytes(b []byte, mt ImageMimeType, d ImageDetail) (ImagePayload, error)

func NewImagePayloadURL(url string, mt ImageMimeType, d ImageDetail) (ImagePayload, error)

func (p ImagePayload) Bytes() []byte

func (p ImagePayload) Detail() ImageDetail

func (p ImagePayload) IsURL() bool

func (p ImagePayload) MimeType() ImageMimeType

func (p ImagePayload) URL() string

type ImageProvider ¶ added in v0.9.0

type ImageProvider interface {
	Provider
	// QueryWithImages sends a prompt with one or more images. The response is
	// returned as text; structured response fields (token counts, finish reason)
	// are not surfaced through this minimal interface — modules needing them
	// should type-assert against the underlying core.Provider.
	QueryWithImages(ctx context.Context, prompt string, images []ImagePayload, options map[string]interface{}) (string, error)
}

ImageProvider is implemented by providers that accept image inputs alongside text prompts (e.g., GPT-4o, Claude 4.x with vision, Gemini multimodal).

Used by SIVA (split-image jailbreak) and VSH (virtual scenario hypnosis) attack modules in v0.9.0.

type Logger ¶

type Logger interface {
	Debug(msg string, keysAndValues ...interface{})
	Info(msg string, keysAndValues ...interface{})
	Warn(msg string, keysAndValues ...interface{})
	Error(msg string, keysAndValues ...interface{})
}

Logger defines the structured logging interface used by attack modules.

type MCPProvider ¶ added in v0.10.0

type MCPProvider interface {
	Provider
	// InvokeTool calls a named MCP tool with the given arguments.
	// Returns the tool's text response, or an error if the call
	// failed at the protocol/transport layer.
	InvokeTool(ctx context.Context, toolName string, args map[string]interface{}) (string, error)
}

MCPProvider is implemented by providers that can invoke Model Context Protocol tools natively. Used by attacks targeting MCP infrastructure (mcp/* and tool_use/* modules).

type MemoryProbe ¶ added in v0.9.0

type MemoryProbe interface {
	Provider
	ProbeMemory(ctx context.Context) (retains bool, err error)
}

MemoryProbe is implemented by providers that can report whether the target retains state across calls (e.g., a memory-augmented agent endpoint).

Memory-poisoning modules call ProbeMemory before injection to fail fast on stateless targets. The error contract is strict:

(true, nil)   → target retains memory; proceed with injection.
(false, nil)  → target is stateless; emit OutcomeSkipped + SkipMemoryNotRetained.
(_, err)      → probe failed; emit OutcomeSkipped + SkipProviderError.
                A failed probe is NOT the same as known-no-memory.

type Message ¶

type Message struct {
	Role      string                 `json:"role"`
	Content   string                 `json:"content"`
	Timestamp time.Time              `json:"timestamp,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
}

Message represents a conversation message exchanged with an LLM.

type NopLogger ¶

type NopLogger struct{}

NopLogger is a Logger that discards all output. Useful for testing.

func (l *NopLogger) Debug(_ string, _ ...interface{})

func (l *NopLogger) Error(_ string, _ ...interface{})

func (l *NopLogger) Info(_ string, _ ...interface{})

func (l *NopLogger) Warn(_ string, _ ...interface{})

type Provider ¶

type Provider interface {
	// Query sends messages to the LLM and returns the response text.
	Query(ctx context.Context, messages []Message, options map[string]interface{}) (string, error)
	// GetName returns the provider name (e.g., "openai", "anthropic").
	GetName() string
	// GetModel returns the model identifier (e.g., "gpt-4", "claude-3").
	GetModel() string
	// GetTokenCount returns the approximate token count for the given text.
	GetTokenCount(text string) int
}

Provider is the interface for LLM providers used by attack modules. This is a simplified facade over the full core.Provider interface, providing only the methods that attack modules need.

type Purger ¶ added in v0.12.0

type Purger interface {
	Provider
	Purge(ctx context.Context, recordIDs []string) error
}

Purger is implemented by providers that own a memory store the operator can purge programmatically. After a memory-poisoning run emits a CleanupHint with injected record IDs (also recorded in result.Metadata["injected_record_ids"]), the CLI (`llmrecon attack purge`) calls Purge to roll back the injection — the automated successor to v0.9.0's manual-cleanup CleanupHint workflow.

Modules type-assert against Purger to report whether a target supports automated cleanup; the CLI type-asserts to perform it. Purge SHOULD be idempotent: purging an already-absent ID is not an error.

type ReasoningProvider ¶ added in v0.9.0

type ReasoningProvider interface {
	Provider
	// QueryWithReasoning sends a chat request and returns the final response
	// plus the model's reasoning trace. Providers that do not return a
	// trace for the given request (e.g., model class doesn't reason, or
	// request didn't trigger reasoning) return an empty trace; callers
	// distinguish via len(trace.Steps) == 0.
	QueryWithReasoning(ctx context.Context, messages []Message, options map[string]interface{}) (response string, trace ReasoningTrace, err error)
}

ReasoningProvider is implemented by providers that expose the model's reasoning trace alongside the final response (e.g., DeepSeek-R1, Gemini 2.5 "Deep Think", o3, Claude 4.x extended thinking).

Used by the H-CoT (chain-of-thought hijacking) attack module in v0.9.0.

The interface is intentionally minimal — the heavier core.ReasoningProvider exposes structured reasoning steps, token counts, and timing for use inside provider adapters. Attack modules only need the per-step text and a "is this trace cryptographically signed (and therefore unmodifiable)?" boolean to gate the mutation path.

type ReasoningTrace ¶ added in v0.9.0

type ReasoningTrace struct {
	// Steps is the ordered list of reasoning-step text. Empty when the
	// provider returned no trace for this query.
	Steps []string
	// Signed reports whether the trace is cryptographically signed and
	// therefore not safely modifiable on round-trip.
	Signed bool
}

ReasoningTrace is the minimal reasoning-trace shape consumed by attack modules. The Signed field reports whether the provider returned a cryptographically-signed trace whose text cannot be modified on round-trip (Anthropic's thinking-block signature). Modules detecting Signed=true emit OutcomeSkipped + SkipSignatureGated rather than attempting mutation that would be silently discarded.

type SessionProvider ¶ added in v0.9.0

type SessionProvider interface {
	Provider
	// SessionID returns a stable identifier for the current session.
	// Empty string indicates no session abstraction (single-shot calls).
	SessionID() string
	// NewSession returns a sibling provider bound to a fresh session. The
	// returned provider may also implement MemoryProbe and ImageProvider; the
	// caller should re-assert as needed.
	NewSession(ctx context.Context) (Provider, error)
}

SessionProvider is implemented by providers that expose session lifecycle controls. Memory-poisoning modules use NewSession to verify that injected records persist across fresh sessions.

type SimpleLogger ¶

type SimpleLogger struct{}

SimpleLogger provides a basic fmt-based Logger implementation.

func (l *SimpleLogger) Debug(msg string, keysAndValues ...interface{})

func (l *SimpleLogger) Error(msg string, keysAndValues ...interface{})

func (l *SimpleLogger) Info(msg string, keysAndValues ...interface{})

func (l *SimpleLogger) Warn(msg string, keysAndValues ...interface{})

type SkipReason ¶ added in v0.9.0

type SkipReason string

SkipReason enumerates the reasons an attack run can end with Outcome=OutcomeSkipped. Introduced in v0.9.0.

const (
	SkipMissingCapability   SkipReason = "missing_capability"
	SkipGateBlocked         SkipReason = "gate_blocked"
	SkipBudgetExceeded      SkipReason = "budget_exceeded"
	SkipProviderError       SkipReason = "provider_error"
	SkipPreconditionFailed  SkipReason = "precondition_failed"
	SkipModelRefusedImage   SkipReason = "model_declined_image_input"
	SkipReasoningTraceEmpty SkipReason = "reasoning_trace_empty"
	SkipSignatureGated      SkipReason = "anthropic_signature_blocks_mutation"
	SkipNoMutationTarget    SkipReason = "no_safety_step_to_hijack"
	SkipMemoryNotRetained   SkipReason = "provider_reports_no_memory_retention"
)

type TechniqueInfo ¶

type TechniqueInfo struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Description string  `json:"description"`
	Category    string  `json:"category"`
	Risk        string  `json:"risk"`
	SuccessRate float64 `json:"success_rate"`
	Examples    []string
	// OWASP mappings
	OWASPLLMCategories     []string `json:"owasp_llm_categories,omitempty"`
	OWASPAgenticCategories []string `json:"owasp_agentic_categories,omitempty"`
}

TechniqueInfo provides metadata about an attack technique.