bugsafe

Safe-to-share crash bundles for humans and LLMs

---

bugsafe captures Python crashes and creates redacted, shareable bug reports. It automatically removes API keys, tokens, passwords, and other secrets while preserving the information needed to debug issues.

Features

• Automatic secret redaction — 25+ patterns for API keys, tokens, passwords, connection strings
• Correlation preservation — Same secret → same token throughout the bundle
• Path anonymization — Removes usernames and sensitive paths
• Rich environment capture — Python version, packages, git info, environment variables
• Multiple output formats — Markdown for humans, JSON for tools, LLM-optimized context
• Zero configuration — Works out of the box with sensible defaults

Quick Start

Installation

pip install bugsafe

Capture a Crash

bugsafe run -- python my_script.py

Render for Sharing

# Markdown for humans
bugsafe render crash.bugbundle

# Optimized for LLMs
bugsafe render crash.bugbundle --llm

Example Output

# Bug Report: my_script.py

## Error
ValueError: Invalid API response

## Traceback
File "<PROJECT>/my_script.py", line 25, in main
    result = api.fetch(url, headers={"Authorization": <API_KEY_1>})

## Redaction Summary
- API_KEY: 2 redacted
- EMAIL: 1 redacted

Notice how secrets are replaced with tokens like <API_KEY_1> while preserving correlation.

Documentation

📚 Full Documentation

Section	Description
Getting Started	Installation and first bundle
CLI Reference	Complete command reference
API Reference	Programmatic usage
Redaction Patterns	What gets redacted
Security Model	How bugsafe protects secrets
Configuration	Config file options

What Gets Redacted

bugsafe automatically detects and redacts:

Category	Examples
API Keys	AWS (AKIA...), Google Cloud, Azure
Tokens	GitHub (ghp_...), GitLab, Slack, Discord
Credentials	Passwords, Basic Auth, Bearer tokens
Connection Strings	PostgreSQL, MySQL, MongoDB, Redis URLs
Private Keys	RSA, DSA, EC, OpenSSH keys
Paths	Home directories, usernames, temp files

See Redaction Patterns for the complete list.

Security

bugsafe is designed to make crash reports safe to share, but:

• Always review bundles before sharing publicly
• Custom secrets may not be detected — add custom patterns if needed
• Binary data is not processed — only text output is redacted

See Security Model for details.

Contributing

Contributions are welcome! See Contributing Guide for development setup.

git clone https://github.com/matbmeijer/bugsafe.git
cd bugsafe
uv sync
uv run pytest

License

MIT License. See LICENSE for details.