mitm/TROUBLESHOOTING.md

MITM Proxy Troubleshooting Guide

ERR_TUNNEL_CONNECTION_FAILED Error

This error typically occurs when the browser cannot establish a secure tunnel through the proxy. Here are the most common causes and solutions:

1. Certificate Issues

Problem: The CA certificate is not properly installed or trusted by the browser.

Solutions:

• Run the program as Administrator to ensure certificate installation

• Manually verify certificate installation:

  certlm.msc
  

  Check if "Charles Proxy CA" appears in "Trusted Root Certification Authorities"

• If certificate installation fails, try:

  certutil -addstore -f "Root" CA.crt
  

2. Proxy Configuration Issues

Problem: System proxy is not properly configured or there are conflicting proxy settings.

Solutions:

• Verify proxy settings in Windows:

  • Go to Settings > Network & Internet > Proxy
  • Ensure "Use a proxy server" is enabled
  • Check that proxy address is 127.0.0.1:8080

• Clear existing proxy settings:

  netsh winhttp reset proxy
  

3. Firewall/Antivirus Blocking

Problem: Security software is blocking the proxy connections.

Solutions:

• Temporarily disable Windows Firewall
• Add exception for the proxy program in antivirus software
• Add exception for port 8080

4. TLS Handshake Issues

Problem: The proxy cannot properly negotiate TLS connections.

Solutions:

• The updated code now includes:
  • Better TLS handshake handling
  • Fallback to transparent proxy mode
  • Improved error logging
  • Connection timeouts

5. Testing and Debugging

Use the built-in test mode to verify connectivity:

# Run with test flag
go run . -test

This will:

• Start the proxy server
• Test HTTP and HTTPS connections
• Show detailed error messages
• Help identify the specific issue

6. Common Error Messages and Solutions

"TLS handshake failed":

• Certificate not trusted by browser
• Try accessing a simple HTTP site first
• Check certificate installation

"Failed to connect to target server":

• Network connectivity issue
• DNS resolution problems
• Target server blocking connections

"Write error" or "Read error":

• Connection interrupted
• Network timeout
• Proxy overloaded

HTTP Redirects (302/301) Issues:

• ✅ FIXED: Proxy is now completely transparent
• All redirects are passed through exactly as-is
• Browser handles redirects automatically
• No interference with redirect chains

7. Manual Testing Steps

1. Test without proxy:

   curl https://httpbin.org/ip
   

2. Test with proxy:

   curl --proxy 127.0.0.1:8080 https://httpbin.org/ip
   

3. Test certificate:

   curl --proxy 127.0.0.1:8080 --insecure https://httpbin.org/ip
   

8. Browser-Specific Issues

Chrome:

• Clear SSL state: Settings > Privacy and security > Security > Manage certificates > Clear SSL state
• Disable certificate transparency checks temporarily

Firefox:

• Import certificate manually: Settings > Privacy & Security > Certificates > Import
• Disable OCSP checking temporarily

Edge:

• Same as Chrome (uses Windows certificate store)

9. Advanced Debugging

Enable verbose logging by modifying the code to show more details:

• Connection attempts
• TLS handshake details
• Certificate validation steps
• Network I/O operations

10. Alternative Solutions

If the proxy still doesn't work:

1. Use transparent mode only: Modify code to skip TLS termination
2. Use different certificate: Generate new certificates with proper SAN fields
3. Use different port: Change from 8080 to 8081 or 3128
4. Bypass problematic domains: Add exceptions for specific sites

Getting Help

If none of these solutions work:

1. Run with -test flag and save the output
2. Check Windows Event Viewer for errors
3. Use Process Monitor to see file/registry access issues
4. Provide the exact error message and browser version