Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
211 lines (166 loc) · 5.25 KB

CONTRIBUTING.md

File metadata and controls

211 lines (166 loc) · 5.25 KB

Contributing to Transproxy

Thank you for your interest in contributing to this transparent proxy project! This guide will help you get started.

🎯 Project Overview

Transproxy is a macOS transparent TCP proxy that handles both proxy-aware and proxy-unaware iOS apps by:

  • Intercepting pfctl-redirected traffic
  • Extracting destinations from HTTP Host headers and TLS SNI
  • Forwarding through Privoxy for content filtering
  • Supporting dual-proxy architecture for mixed app behaviors

🚀 Getting Started

Prerequisites

  • macOS (required for pfctl support)
  • Python 3.7+
  • Privoxy or similar HTTP proxy
  • Admin access for pfctl rules

Development Setup

  1. Clone the repository:

    git clone https://github.com/jerry7991/transproxy.git
cd transproxy

  2. Install Privoxy:

    brew install privoxy
brew services start privoxy

  3. Test the proxy:

    python3 src/transparent_tcp_proxy.py --help

📋 How to Contribute

Reporting Issues

  • Use the GitHub issue tracker
  • Include detailed logs with --verbose flag
  • Provide network configuration details
  • Mention iOS version and affected apps

Suggesting Features

  • Check existing issues first
  • Describe the use case clearly
  • Consider security and performance implications
  • Provide implementation ideas if possible

Code Contributions

Areas We Need Help With

  1. Protocol Support

    • FTP transparent proxying
    • SMTP/IMAP support
    • Custom protocol handlers

  2. Platform Compatibility

    • Linux iptables integration
    • FreeBSD pf support
    • Windows netsh/WinDivert

  3. Performance Optimization

    • Async I/O with asyncio
    • Connection pooling
    • Memory usage optimization

  4. Security Enhancements

    • Certificate validation
    • Rate limiting
    • Access control lists

  5. Monitoring & Debugging

    • Metrics collection
    • Web dashboard
    • Real-time traffic analysis

Development Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Test your changes thoroughly
  4. Document new features
  5. Submit a pull request

Code Style

  • Follow PEP 8 for Python code
  • Use meaningful variable names
  • Add docstrings for functions
  • Include inline comments for complex logic
  • Keep functions focused and small

Testing Guidelines

# Test basic functionality
python3 src/transparent_tcp_proxy.py --improved-tls

# Test with different protocols
curl -v http://httpbin.org/ip
curl -v https://httpbin.org/ip

# Test pfctl rules
sudo pfctl -s nat
sudo pfctl -s state | grep 192.168.2

🔧 Project Structure

transproxy/
├── src/
│   ├── transparent_tcp_proxy.py    # Main proxy implementation
│   └── a.py                        # Legacy/development code
├── config/
│   ├── pf/                         # pfctl configuration examples
│   ├── pac/                        # PAC file examples
│   └── mobileconfig/               # iOS configuration profiles
├── docs/
│   ├── TRANSPARENT_PROXY_GUIDE.md  # Comprehensive technical guide
│   └── README.md                   # Quick start guide
└── pf-no-loops.conf               # Production pfctl rules

🐛 Debugging Guidelines

Common Issues

  1. PAC File Loops: Check pfctl exemption rules
  2. TLS Without SNI: Chrome proxy-aware behavior
  3. Connection Refused: Privoxy not running
  4. No Internet: pfctl rules too broad

Debug Commands

# Check pfctl status
sudo pfctl -s info
sudo pfctl -s nat
sudo pfctl -s state

# Monitor connections
sudo lsof -i :8001
sudo lsof -i :48080

# Network analysis
sudo tcpdump -i bridge100 host 192.168.2.4

📖 Documentation

Required for New Features

  • Update TRANSPARENT_PROXY_GUIDE.md for technical details
  • Add configuration examples
  • Include troubleshooting steps
  • Update README.md if needed

Documentation Style

  • Use clear, concise language
  • Include code examples
  • Add network diagrams where helpful
  • Explain the "why" not just the "how"

🧪 Testing Scenarios

Core Functionality

  • HTTP transparent proxying
  • HTTPS with SNI extraction
  • Proxy-aware app exemption
  • PAC file handling
  • Error handling and logging

Edge Cases

  • Large TLS handshakes
  • Missing SNI extensions
  • Malformed HTTP requests
  • Connection timeouts
  • High concurrent load

Integration Tests

  • iOS Safari browsing
  • Netflix streaming
  • App Store downloads
  • Background app updates
  • System service connections

🔐 Security Considerations

  • Never log sensitive data (passwords, tokens)
  • Validate all input data
  • Handle TLS properly (no MITM unless explicit)
  • Respect user privacy
  • Follow secure coding practices

📜 License

This project is open source. By contributing, you agree that your contributions will be licensed under the same license as the project.

🤝 Community

  • Be respectful and inclusive
  • Help others learn and contribute
  • Share knowledge and experiences
  • Focus on constructive feedback

❓ Questions?

  • Open an issue for technical questions
  • Check the Technical Guide first
  • Review existing issues and discussions

Thank you for contributing! 🎉