Best Practices

Bleep Individual is a single desktop app that runs a local proxy, detection engine, and UI on one machine. These recommendations help you get the most out of it.

1. Initial setup

Certificate

Bleep generates a local CA certificate on first launch. The CA must be trusted by your operating system for HTTPS inspection to work. Bleep handles this automatically on most systems, but verify by visiting any AI service in Chrome and confirming you see a green lock icon.

• Firefox uses its own certificate store — import the CA manually via Settings → Privacy & Security → Certificates
• Java applications use a separate keystore — import with keytool -importcert if needed
• Corporate environments may block CA trust changes — check with IT first

Port selection

Defaults: proxy on 8080, PAC server on 18080. Check for conflicts before first launch:

• Other proxies (Fiddler, Charles, corporate proxy) often use 8080
• The setup wizard lets you change ports during first launch — adjust there if you have conflicts
• Changing ports after launch requires restarting the app

Verify proxy

After launching, confirm the proxy and PAC server are running:

# Test proxy connectivity
curl -x http://localhost:8080 https://httpbin.org/ip

# Test PAC endpoint
curl http://localhost:18080/proxy.pac

Both should return without errors. If not, check the port is not in use and the app is running.

2. Rollout strategy

Bleep uses a mode-as-cap model. The mode sets a ceiling on what actions policies can take — Warning mode caps everything at Warn, Enforcing mode uses the full policy action.

1. Start in Warning mode (the default). All violations are logged and you receive desktop notifications, but no traffic is blocked or redacted.
2. Run for a few days and review violations in the app UI. Look for false positives — patterns matching non-sensitive data.
3. Tune patterns. Disable or tighten any pattern that generates false positives. Add custom patterns for org-specific secrets.
4. Switch to Enforcing when confident. Policies now take full effect — for example, a "Block Critical" policy will block matching traffic, and a "Redact High" policy will redact in-flight.

3. Pattern management

Built-in patterns

Bleep ships with detection patterns for common secrets. All are severity HIGH by default:

Custom patterns

Add patterns for your organization's secrets in the YAML config or through the app UI. Each pattern needs a name, regex, severity, and optional tags for policy matching.

custom_patterns:
  - name: "Internal DB Password"
    regex: "db_pass_[A-Za-z0-9]{16,}"
    severity: CRITICAL
    tags: ["database", "internal"]

Tuning false positives

• Tighten the regex to be more specific (e.g. require a prefix or exact length)
• Use the blocklist to flag specific exact values (e.g. a known internal secret) by pasting them directly — they’re matched by literal substring
• Disable patterns you don't need — fewer active patterns means fewer false positives and better performance

4. Monitoring

• Check violations regularly in the app UI. Filter by action type (Block, Redact, Warn, Log) to focus on what matters.
• Violation previews are redacted — the actual sensitive data is never stored, only the pattern name and match location.
• Image scanning detections (OCR) appear as normal violations with the same severity and action handling.
• Desktop notifications are enabled by default and fire on every violation. Disable in app settings if they become noisy.

5. Performance

Image scanning

Bleep uses embedded ML models for OCR — no external API calls, everything runs locally. Disable with image_scanning: false in config if not needed.

General

• Only traffic to monitored AI domains is inspected — all other traffic passes through as a transparent tunnel
• Toggle response_inspection off if you only need to scan outbound requests
• Toggle entropy_detection off if you don't need high-entropy string detection

6. Keeping current

• The domain list updates automatically on each launch. Updates use merge-based sync — your custom domain additions and removals are preserved.
• App updates are manual. Check the downloads page for new versions.

7. License

• Your license is validated via heartbeat every hour. If the app cannot reach the license server, a 7-day offline grace period allows continued operation using a cached license.
• After 7 days without verification, the proxy stops. Restore connectivity to resume.
• Licenses are instance-bound. If you reinstall on a different machine, contact support to rebind.