TraceLens is a local-first tool. By design:

• No data leaves your machine — all evidence, cases, and reports stay in ~/.local/share/tracelens/ (or your configured TRACELENS_DATA_DIR).
• No network connections — the core tool never phones home, uploads telemetry, or contacts external services.
• No root required — captures work with your user's existing permissions. Some system data (e.g., full dmesg) benefits from group membership (systemd-journal, adm) but root is never mandatory.
• Optional AI is opt-in — the AI provider is disabled by default. If enabled, API keys are read from environment variables only, never stored in case data or reports.

TraceLens reads system logs and state that your user already has access to:

• journalctl output (filtered by time/unit)
• dmesg kernel ring buffer
• systemctl unit status
• Process listings (ps)
• Memory and disk usage (/proc/meminfo, df)
• Boot session history
• Package manager logs

This data may contain sensitive information — hostnames, IP addresses, usernames, service names, and application-specific log content.

TraceLens includes a configurable redaction engine (tracelens.utils.redaction) that removes:

• IPv4 and IPv6 addresses
• Email addresses
• Common secret patterns (API keys, tokens, passwords in URLs)
• Custom regex patterns (user-defined via TRACELENS_REDACT_PATTERNS)

Redaction is best-effort. Logs can contain arbitrary text and no pattern-based system catches everything. Review reports before sharing externally.

• Case data is stored as JSON files under TRACELENS_DATA_DIR with standard filesystem permissions.
• TraceLens does not encrypt case files. If your system's data directory is on an unencrypted filesystem, anyone with access to that directory can read captured evidence.
• For sensitive systems, use full-disk encryption (LUKS) and restrict TRACELENS_DATA_DIR permissions.

• The dashboard runs on localhost:8765 by default.
• It binds to 127.0.0.1 only — not accessible from other machines on the network.
• No authentication is required because it's local-only.
• Do not expose the dashboard port to the network unless you add a reverse proxy with authentication.

• The system-level service (tracelens.service) runs as the user specified in the unit file, not as root.
• The user-level service (tracelens-user.service) runs in your user session.
• Service credentials (if AI is enabled) must be passed via environment variables in the unit file — protect the unit file's permissions accordingly.

If you discover a security vulnerability in TraceLens, please report it responsibly:

1. Do NOT open a public GitHub issue.
2. Email: diago@pm.me (or use GitHub Security Advisories)
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Impact assessment
   • Suggested fix (if any)

• Acknowledgment: within 48 hours
• Triage & assessment: within 7 days
• Fix or mitigation: within 30 days for critical issues

• Path traversal or arbitrary file read/write via CLI arguments or case data
• Command injection through collector subprocess calls
• Information disclosure beyond what the user's permissions should allow
• Dashboard SSRF or XSS (if exposed to a network)
• Redaction bypass for default patterns

• Reading system logs that your user already has access to (that's the tool's purpose)
• Data visible in case files that the user captured intentionally
• Lack of encryption on stored case files (documented limitation)
• AI API keys visible in environment variables (OS-level concern)

1. Keep permissions tight — chmod 700 ~/.local/share/tracelens/
2. Use redaction — enable before generating reports you'll share
3. Review before sharing — check reports for sensitive data before posting
4. Use disk encryption — LUKS/dm-crypt for systems with sensitive logs
5. Don't run as root — TraceLens doesn't need it, and running as root captures more data than intended
6. Rotate AI keys — if using the AI provider, rotate API keys regularly
7. Pin dependencies — use uv lock to pin exact dependency versions