Telltale
Install Telltale
Start with the upstream Telltale repository, verify the scanner against synthetic fixtures, then move to bounded read-only checks against real session stores only when you understand the privacy boundary.
Source material checked for this page
This page summarizes install and validation guidance from the Telltale repository. It does not vendor Telltale code and it does not replace the upstream install guide.
Artifact Paths
Install guide
/home/christian/github/adr/docs/install.md Source for release archive, source build, fixture verification, real-store scan, watch, status, service, and SIEM setup guidance.
Project README
/home/christian/github/adr/README.md Source for project scope, quick start, source support status, and repository layout.
Fixture tree
/home/christian/github/adr/tests/fixtures/session_stores Synthetic session stores used for safe local verification examples.
Prerequisites
- Rust and Cargo are required when building from source.
- Local access is required for any real agent session stores you choose to scan.
- A SIEM or log shipper is optional; Telltale can write local JSONL first.
- Use synthetic fixtures for public demos, docs, screenshots, and validation examples.
Build from source
Tagged GitHub releases can publish platform-specific adr binary archives. Source builds remain supported. When building locally, run the commands from the Telltale repository root.
git clone https://github.com/Dark-Roast-Cyber/telltale.git
cd telltale
cargo build --release
The release binary is written to target/release/adr when the build succeeds.
Verify with synthetic fixtures first
Run fixture-backed checks before pointing the scanner at real local session stores. These commands use checked-in synthetic data and avoid writing event output during the scan step.
cargo run -- scan --once --dry-run --root tests/fixtures/session_stores
cargo run -- rules validate --rules config/rules/tool-call-regex.yaml
cargo test
Use --dry-run for fixture checks. The upstream docs reserve --allow-fixtures for intentional synthetic writes in CI or local development.
Move to real stores carefully
A first real-store check should be read-only and bounded. The upstream install guide recommends using the directory that contains supported session-store roots, usually $HOME on a single-user workstation, but the first check should filter by client and cap the number of scanned sources.
cargo run -- scan --once --dry-run --root "$HOME" --client codex --max-sources 5
This example is read-only because it uses --dry-run. Adjust the client only after checking current source support in the Telltale README and source validation matrix.
cargo run -- scan --once --emit-activity --root "$HOME" --log-path logs/adr-events.jsonl
Use this only after reviewing what your environment allows Telltale to capture and where the JSONL event file will be stored.
Useful output paths and commands
After a scan writes JSONL telemetry, keep the event path explicit. Broad log-directory forwarding risks indexing diagnostics, source logs, or unrelated sensitive files.
Artifact Paths
Default local event file
logs/adr-events.jsonl Default append-friendly JSONL path when running from the repository and using the documented log path.
Event schema
/home/christian/github/adr/schemas/event.schema.json Schema for emitted SIEM events, including event_type, severity, risk_score, client, session_id, evidence, triage, and response fields.
Bundled rules
/home/christian/github/adr/config/rules/tool-call-regex.yaml Bundled YAML rules used by default unless scan-time rule files replace the set.
cargo run -- status --log-path logs/adr-events.jsonl
cargo run -- watch --client codex --client opencode --root "$HOME" --log-path logs/adr-events.jsonl
Watch mode accepts repeated --client filters so monitoring can stay scoped to selected supported clients.