Telltale

Detection Model

Telltale detection starts with data-driven rules and normalized agent activity. Each tool call starts at score 0. Rules add points. Context modifiers add or subtract points. Severity is derived from the final score unless triage overrides it.

Risk flow

Default thresholds are configured by environment variables: ADR_RISK_THRESHOLD_LOW, ADR_RISK_THRESHOLD_MEDIUM, ADR_RISK_THRESHOLD_TRIAGE, and ADR_RISK_THRESHOLD_ALERT.

Artifact Paths

0-19

informational

Log notable activity only.

20-49

low

Log detection with matched rule details.

50-69

medium

Log detection and include expanded context fields.

70-89

high

Run Llama Guard and triage model, emit triage result.

90+

critical

Run triage and emit alert-ready event.

Rule categories

Rules are organized into categories that map to common agent risk patterns:

secret_access: .env, auth files, SSH keys, cloud credentials, package tokens.
credential_pattern: API keys, JWTs, private keys, OAuth tokens.
execution: shell, eval, interpreters, encoded payloads.
download: curl, wget, PowerShell web requests, package downloads.
install: npm, pip, cargo, brew, apt, binary installers.
exfiltration: outbound upload, pastebin-like targets, cloud object writes, suspicious webhooks.
persistence: shell profile edits, cron/systemd/launch agents, startup folders.
approval_bypass: context indicating bypassing prompts, hidden execution, or no-confirm behavior.
tool_injection: tool-call-shaped content in model output where no tool was requested or registered.
mcp_prompt_injection: fake or poisoned MCP tool metadata, tool responses, server instructions, or tools/list content that tries to steer the agent.

Custom rules

Telltale loads bundled rules by default from config/rules/tool-call-regex.yaml. You can replace that set at scan time with custom YAML files. The simplest valid custom rule uses targets plus regex:

Custom rule example

YAML

rules:
  - id: example.download.curl
    title: Example curl download
    category: download
    severity: low
    score: 20
    targets: [command, arguments, url]
    regex: '(^|\b)curl\b.*https?://'
    tags: [example, network, download]
    explanation: Example rule that matches curl-based HTTP downloads.
    falsepositives:
      - Setup docs or normal dependency fetches may legitimately use curl.

Custom rules use the same engine and syntax as security detections.

Policy controls

Policy YAML can select active rule categories and rule ids without editing the rule files:

Policy example

YAML

name: strict-workstation
enabled_categories: [secret_access, credential_pattern, exfiltration, mcp_prompt_injection]
disabled_rules: [network.controlled_test_domain.darkroast]

Use telltale rules list, telltale rules validate, and telltale rules test to inspect and preview configured rules.

High-risk combinations

Context rules detect dangerous sequences:

Secret read followed by outbound network call
Download followed by execution
Install followed by shell profile or service modification
Base64/hex decode piped into shell
Model proposes or emits tool call without matching user intent in preceding context
Tool arguments contain credential patterns
MCP metadata or tool output contains prompt-injection language plus a command, URL, sensitive path, or tool-call-shaped object

Response contract

Detection events include a top-level response object that is safe for SIEM indexing and analyst workflows. The fields are deterministic and derived from severity, matched rule IDs, and categories:

recommended_action: one of monitor, review, investigate, or investigate_immediately.
response_playbook: a stable Telltale playbook identifier for the strongest matched rule family.
investigation_summary: a short redaction-safe summary of the matched rules/categories and next investigation step.
escalation: routine_review or security_review_required.