Security Tiers

opentraces applies layered security scanning before traces are staged or pushed. The current pipeline version is SECURITY_VERSION = 0.3.0.

Tip: run opentraces doctor --security to see the exact tiers, versions, and commands active in your current install.

Current User-Facing Tiers

The current 0.3 CLI surfaces these layers:

Tier 1a And 1b

Regex and entropy scanning are always on. They run locally during processing and rewrite sensitive content before traces surface in the inbox.

Tier 1.5: TruffleHog

Enable Tier 1.5 with:

opentraces setup trufflehog
opentraces setup trufflehog --enable
opentraces setup trufflehog --disable

Current behavior:

• TruffleHog is opt-in
• it runs locally with verify_secrets = false
• findings are redacted in place
• findings force human review before upload
• opentraces push --no-trufflehog skips it for one push only

Use opentraces doctor --security to confirm whether the binary is installed and enabled.

Tier 2: LLM Trace Review

Tier 2 sends each staged trace to a third-party LLM for a semantic review on top of the regex, entropy, and TruffleHog tiers. It is opt-in, runs out-of-band, and is stored in the global config under security.llm_review (one config per machine, projects inherit it).

Configure The Reviewer

Run the interactive wizard once:

opentraces setup llm-review

The picker offers these presets out of the box:

Local Ollama models can be pulled inline from the wizard when the ollama binary is on PATH.

Non-Interactive Setup

Skip the picker by passing flags directly, useful in agent setups and CI:

opentraces setup llm-review \
  --api-format openai-compat \
  --base-url http://localhost:11434/v1 \
  --model gemma3n:e4b

opentraces setup llm-review \
  --api-format openai-compat \
  --base-url https://api.groq.com/openai/v1 \
  --model llama-3.3-70b-versatile \
  --api-key-env GROQ_API_KEY

opentraces setup llm-review \
  --api-format anthropic \
  --model claude-haiku-4-5-20251001 \
  --api-key-env ANTHROPIC_API_KEY

Full flag set:

Run Tier 2 On Demand

opentraces llm-review                          # every staged trace
opentraces llm-review --scope staged           # second line of defence before push
opentraces llm-review --scope inbox            # pre-add only
opentraces llm-review --trace 8a3f1c           # one trace (short id ok; repeatable)
opentraces llm-review --limit 5                # cap the batch
opentraces llm-review --force                  # re-review cached verdicts
opentraces llm-review --dry-run                # estimate sessions, chars, tokens, cost
opentraces llm-review --context-file AGENTS.md # project context (README/AGENTS.md up to 10KB)

Per-run overrides match the setup flags so you can try a different backend without touching config:

opentraces llm-review \
  --api-format openai-compat \
  --base-url https://api.groq.com/openai/v1 \
  --api-key-env GROQ_API_KEY \
  --model llama-3.3-70b-versatile

Verdicts are cached into metadata.llm_review on each trace so downstream gates and the TUI can see them. A bad verdict also blocks the trace in state so later push flows skip it.

Gate The Push

opentraces push --llm-review

This fails upload unless every staged trace has a clean Tier 2 verdict. Typical flow before a public dataset push: opentraces llm-review --scope staged followed by opentraces push --llm-review.

Doctor Output

opentraces doctor (and the focused opentraces doctor --security subview) surfaces everything configured for Tier 2:

• state: disabled, on-demand, or unreachable
• backend and model, inferred from the endpoint (for example ollama / gemma3n:e4b, groq / llama-3.3-70b-versatile)
• endpoint URL and api format
• api key env var name and whether it is currently set or unset
• probe status, including model count at the endpoint and whether your configured model is in the list; flagged as not found when the endpoint answers but does not expose the model, not installed when the binary is missing, or not set when a required API key env var is empty
• toggle hints for run, gate push, reconfigure, and disable

Use doctor to confirm the tier is healthy before relying on push --llm-review as an upload gate.

Tier 3: Human Review

Human review is always available through:

opentraces web
opentraces tui
opentraces list --stage inbox
opentraces show <trace-id>
opentraces redact <trace-id>

This is the final check for project-specific context, sensitive business details, and traces that are technically safe but not worth publishing.

Review Policy

Each repo carries a review policy in .opentraces.json:

opentraces setup review-policy --review
opentraces setup review-policy --auto

auto does not push automatically. Upload remains explicit.

What Can Still Block

The user-facing pipeline is designed to redact and route most issues into review, but some failures still stop upload:

• parse errors
• missing required integrations you explicitly enabled
• push --llm-review when staged traces lack a clean Tier 2 verdict

Use opentraces doctor for pipeline failures and opentraces list --stage blocked for traces that still need intervention.