agenticdetonator

type Canary ¶

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

Canary runs bounded LLM-in-loop detonations against untrusted input, observes the tickled tool calls and markdown URLs, and returns a Detonation record. Each detonation uses a fresh WildcardExecutor so trajectories don't bleed across detonations.

Safe for concurrent Detonate calls: the struct holds only the invoker (already concurrent-safe per processor/agentic-model contract) and the config (read-only after NewCanary). All per-detonation state — executor, messages, raw text buffer — is stack-local to each Detonate call.

func NewCanary(invoker ModelInvoker, cfg CanaryConfig) (*Canary, error)

func (c *Canary) Detonate(ctx context.Context, input string) (*Detonation, error)

type CanaryConfig ¶

type CanaryConfig struct {
	// Model is the model.Registry endpoint name to invoke.
	// Captured into the Detonation record's source provenance so
	// operators know which canary produced which labels.
	Model string

	// MaxTurns bounds the outer canary loop. Most injection
	// detonations resolve in 1–3 turns; 6 is the practical upper
	// bound at which an honest agent has either taken the bait or
	// declined.
	MaxTurns int

	// MaxToolCalls caps the total wildcard tool invocations across
	// all turns. A canary chained into a tool-recursive loop
	// (rare but adversarially possible) is bounded here.
	MaxToolCalls int

	// MaxTokens is the per-turn output budget passed to the model.
	// Defaults to 1024 — enough for tool args + a short rationale,
	// short enough that runaway thinking costs are bounded per turn.
	MaxTokens int

	// Timeout is the deadline for the ENTIRE detonation
	// (all turns combined). Defaults to 60s.
	Timeout time.Duration

	// SystemPrompt is the canary persona instruction. Defaults to a
	// minimal OSINT-analyst persona that licenses tool use; operators
	// can override to detonate domain-specific threats (code-review
	// agents, customer-support agents, etc.). The default is
	// intentionally permissive — the goal is to elicit attacks, not
	// to resist them.
	SystemPrompt string
}

CanaryConfig bounds one detonation's cost. Defaults are conservative — operators tune for their LLM cost/latency tolerance.

Per ADR-043 line 182, every detonation runs under a "max-turns + max-tool-calls + max-tokens cap" with the canary timeout governed by the ADR-024 layered-timeout convention. We don't pull the system-wide layered-timeout helper here because the detonator is offline batch work, not a serving path — Timeout-on-config is the right primitive, the layered helper is for request-path timeout composition.

func DefaultCanaryConfig() CanaryConfig

type Detonation ¶

type Detonation struct {
	// Input is the untrusted text the canary was asked to process.
	// Becomes the corpus record's Text field.
	Input string

	// CanaryModel records which model.Registry endpoint ran the
	// canary. Persisted into the corpus record's source provenance
	// so operators can audit which model produced which labels.
	CanaryModel string

	// StartedAt is the canary's invocation wallclock. Latency and
	// trace correlation derive from this.
	StartedAt time.Time

	// Duration is the canary's wall time end-to-end. Recorded so
	// the Phase 3 cost accounting can audit per-detonation budget
	// compliance.
	Duration time.Duration

	// Turns is the number of canary LLM turns consumed before the
	// detonation terminated (success or cost-cap hit).
	Turns int

	// ToolCalls is the executor's trajectory in observation order.
	ToolCalls []RecordedCall

	// URLs is the markdown-URL scanner output. Populated by the
	// Phase 3b canary aggregator (it accumulates each turn's raw
	// text and scans the concatenation); Phase 3a treats this as
	// pre-aggregated input.
	URLs []ScannedURL
}

Detonation aggregates the observable outputs of one canary run over one input. The fields are populated incrementally by the canary loop (Phase 3b); Phase 3a treats it as a pure data structure that converts cleanly into an injectioncorpus.Record for round-trip into the Phase 2 classifier corpus.

Why this lives in 3a: the Record-conversion contract IS the detonator's product. Getting the shape right before the canary loop is written keeps 3b focused on the loop control flow and not on figuring out how to package its findings.

func (d *Detonation) AllSignals() []string

func (d *Detonation) ID() string

func (d *Detonation) PrimarySignal() string

func (d *Detonation) ToRecord() injectioncorpus.Record

type ModelInvoker ¶

type ModelInvoker interface {
	ChatCompletion(ctx context.Context, req agentic.AgentRequest) (agentic.AgentResponse, error)
}

ModelInvoker is the minimal contract the canary needs from a model client. processor/agentic-model.Client satisfies it. Carved out so tests can mock without spinning up an LLM, and so future-canary variants can route through different invocation shapes without churning the canary loop.

type RecordedCall ¶

type RecordedCall struct {
	ToolName  string
	Arguments map[string]any
	CallID    string
	At        time.Time
}

RecordedCall captures one observed tool invocation for downstream signal extraction.

type ScannedURL ¶

type ScannedURL struct {
	URL  string
	Form URLForm
}

ScannedURL records one URL the scanner observed along with the markdown form that surfaced it. Provenance lets the Phase 3b canary aggregator weigh image-syntax matches more heavily than bare URLs (image markdown is auto-rendered → auto-fetched).

func ScanMarkdownURLs(text string) []ScannedURL

type URLForm ¶

type URLForm string

URLForm distinguishes how the URL appeared in the canary text. Image-syntax URLs are the primary exfil vector; link-syntax and bare URLs are weaker signals but still recorded so operators can audit the full surface.

const (
	URLFormImage URLForm = "image"
	URLFormLink  URLForm = "link"
	URLFormBare  URLForm = "bare"
)

type WildcardExecutor ¶

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

WildcardExecutor implements agentictools.ToolExecutor for the detonator sandbox. Exposes the attacker-target tool surface from ADR-043 line 184-189 (read_file, execute, bash, fetch, send_email, read_env, db_query, list_users, get_api_key) and a few adjacent shapes the OSINT threat model implicates (send_message, http_request).

Each Execute call:

• Records the (tool, args, timestamp) into an in-memory trajectory for downstream signal extraction.
• Returns a deterministic synthetic ToolResult keyed on sha256(tool_name + canonical_args_json). Same args → same fake result, so canary behavior is reproducible.
• Never touches the filesystem, network, or any external resource. The whole point is to observe what the LLM tries to do, not to do it.

One executor instance per detonation. Cheap to construct (no dependencies) and the trajectory is the natural per-detonation scope. Thread-safe within a single instance.

func NewWildcardExecutor() *WildcardExecutor

func (e *WildcardExecutor) Execute(_ context.Context, call agentic.ToolCall) (agentic.ToolResult, error)

func (e *WildcardExecutor) ListTools() []agentic.ToolDefinition

func (e *WildcardExecutor) Trajectory() []RecordedCall