Skip to content

HTTPS Inspection Flow

SafeMode inspects encrypted traffic using a local mitmproxy-based TLS interception flow.

Why HTTPS Interception Is Required

Most browser traffic is HTTPS. Without a trusted local certificate authority (CA), SafeMode cannot inspect payloads for:

  • phishing URLs
  • exposed secrets
  • suspicious JavaScript patterns

Core Components

  • CertificateManager handles installation checks and cert setup interactions.
  • QtMonitorManager starts mitmproxy in a separate process.
  • URLMonitorAddon hooks into request/response lifecycle.

Startup-to-Inspection Sequence

  1. App starts and checks certificate readiness.
  2. User enables monitor.
  3. Mitmproxy process starts and loads filters.
  4. READY signal is emitted when listen port is live.
  5. App enables OS system proxy.
  6. Browser traffic flows through mitmproxy.
  7. Request/response hooks apply blocking and analysis.

Request Hook Behavior

In URLMonitorAddon.request(flow):

  • Parses URL and request method.
  • Skips protected infrastructure paths (/cdn-cgi/) for stability.
  • Applies default + user whitelist checks.
  • Detects request type (document/script/xhr/media/etc).
  • Calls filter manager (check_url).
  • If blocked, returns synthetic 403 response immediately (document page or resource-specific empty payload).

Response Hook Behavior

In URLMonitorAddon.response(flow):

  • Skips non-GET responses for heavy analysis.
  • Focuses on HTML/JS content types for deeper logic.
  • Calculates TLSH for supported payloads.
  • Scans content for secret patterns.
  • Runs suspicious JS heuristics and optional neutralization.
  • Sends normalized event to queue for UI.

Certificate and Trust Boundaries

Trusting SafeMode CA grants local visibility over HTTPS payloads.

Security properties of this design:

  • Inspection happens locally.
  • No mandatory cloud forwarding in this architecture.
  • Explicit user-controlled enable/disable path.

Known limits:

  • Certificate pinning apps may fail or bypass proxy behavior.
  • Non-system-proxy-aware traffic may not be inspected.

CA Artifact Inventory (~/.mitmproxy)

Typical generated files:

  • mitmproxy-ca-cert.cer
  • mitmproxy-ca-cert.pem
  • mitmproxy-ca-cert.p12
  • mitmproxy-ca.pem
  • mitmproxy-ca.p12

Use this quick check:

ls -la ~/.mitmproxy

This confirms certificate material exists before debugging trust-store issues.

mitm.it Behavior Clarification

Bootstrap URL for certificate onboarding is:

  • http://mitm.it (HTTP)

If you see:

If you can see this, traffic is not going through mitmproxy.

that indicates routing/proxy state issue, not necessarily certificate corruption.

Next checks:

  1. monitor process running
  2. listener present on configured port
  3. system proxy actually enabled

Safety Behavior on Failure

If proxy enable fails after READY, monitor is stopped.

This avoids a misleading partial state where UI appears active but traffic is not actually routed.