!!! warning "Legacy Documentation" This page has been superseded by the new documentation structure. See Security Model for the current version.

This document describes the security model, assumptions, and limitations of bugsafe.

bugsafe is designed to create safe-to-share crash bundles by automatically redacting sensitive information from command output. The goal is to enable developers to share debugging information without exposing secrets.

1. Prevent secret leakage - Remove API keys, tokens, passwords, and other sensitive data
2. Preserve debugging utility - Keep enough information to diagnose issues
3. Deterministic correlation - Same secret → same token for traceability
4. Non-reversible - Cannot recover original secrets from tokens

Input Text
    │
    ▼
┌─────────────────┐
│ Pattern Matching│ ← 25+ regex patterns
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Tokenization   │ ← Deterministic, salted
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Path Anonymizer │ ← Replace sensitive paths
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Verification   │ ← Check for remaining secrets
└────────┬────────┘
         │
         ▼
   Redacted Output

• Each redaction session uses a cryptographically random salt
• Only the SHA-256 hash of the salt is stored in the bundle
• The salt itself is never persisted
• Same salt = same tokens (for correlation within a bundle)

• Command arguments passed directly (no shell interpretation)
• Bundle paths validated for traversal attacks
• ZIP entries checked for path traversal (../)
• Maximum file sizes enforced

• All text output passes through redaction engine
• Environment variables filtered through blocklist
• File paths anonymized to remove usernames

• Regex patterns have configurable timeout (default: 100ms)
• Prevents catastrophic backtracking DoS
• Timed-out patterns logged as warnings

bugsafe may miss secrets in these cases:

1. Custom formats - Proprietary token formats not in pattern list
2. Obfuscated secrets - Base64-encoded or encrypted secrets
3. Context-dependent - Secrets only identifiable by context
4. New patterns - Recently introduced token formats

Mitigation: Always review bundles before sharing. Use bugsafe inspect to check redaction summary.

bugsafe may incorrectly redact:

1. UUID-like IDs - Disabled by default
2. Email-like strings - Configurable
3. IP-like numbers - Configurable
4. Long alphanumeric strings - May match generic patterns

Mitigation: Use --no-redact for trusted environments or adjust pattern configuration.

Before sharing a bundle, verify:

• Run bugsafe inspect <bundle> to review redaction summary
• Check that expected secret categories were detected
• Review redacted output for any remaining sensitive data
• Consider audience before sharing (internal vs public)

If you discover a secret was not redacted:

1. Delete the shared bundle immediately
2. Rotate the exposed credential
3. Report the pattern gap (see Contributing)
4. Update your bugsafe version

Please report security vulnerabilities via:

1. GitHub Security Advisories (preferred)
2. Email to maintainers (for critical issues)

Do NOT open public issues for security vulnerabilities.

• bugsafe processes data locally; no external services
• No telemetry or data collection
• Bundles are self-contained files you control
• Salt hashes cannot be used to recover secrets