Telltale guides

Use Telltale

Start with a small scan using --dry-run to avoid writing telemetry or scanner state. Then learn what Telltale can see, how to interpret a finding, and which evidence belongs in your investigation.

Start here

Telltale reads stored agent activity. It does not sit between the agent and its tools. Use the overview first if you are deciding where it fits in your workflow.

How Telltale works

Follow the path from a session store to a detection and an event file.

Install and configure

Choose a release or source build, verify with synthetic data, then scope your first scan.

Check visibility before drawing conclusions

A supported parser is not proof that every version of an agent works. OpenClaw’s current default SQLite store is not acquired; current Qwen formats also have known gaps. A quiet result from an unreadable or unsupported store is not a clean bill of health.

Agent compatibility

Exact source identities, tested formats, live-validation limits, and known gaps.

Find session stores

Platform paths, project roots, and discovery configuration.

Understand evidence gaps

Which prompts, results, timestamps, and identifiers each source can report.

Handle evidence safely

Redaction, hashing, local context, and the limits of those protections.

Investigate and tune findings

A match is a reason to review evidence, not proof of compromise. Confirm the surrounding task, the source’s visibility, and the rule’s false-positive guidance before deciding what happened.

Understand detections

Rules, cumulative risk scores, and deterministic review guidance.

Tune detection policy

Select rules and categories without confusing configuration with enforcement.

Investigation playbooks

Practical pivots for injection, credential access, egress, and scanner health.

Browse detection content

Find the exact core and community rule definitions behind a finding.

Work with the output

Read and forward telemetry

Local JSONL, event families, forwarding, rotation, and delivery limits.

Understand inventory

Installed tooling, configured MCP servers, and observed activity are different evidence.

Inspect configured MCP servers

Static inventory and the limits of runtime attribution.

Use the event schema

Choose the right contract for your shipper or event consumer.

Advanced operations and development

Detailed recovery procedures, Rust APIs, rule-authoring requirements, and release engineering stay in the Telltale repository. Follow these links when you need that level of detail, rather than reading them as a getting-started guide.