Skip to content

README.md

Latest commit

 

History

History
202 lines (144 loc) · 6.72 KB

README.md

File metadata and controls

202 lines (144 loc) · 6.72 KB
Raw

LocalPortManager 🔌

Python 3.8+ License: MIT Zero Dependencies CI Coverage PyPI Code style: black

A lightweight, zero-dependency local reverse proxy for managing multiple services on dynamic ports. Perfect for development environments, penetration testing frameworks, and microservice development.

✨ Features

  • 🚀 Zero External Dependencies - Uses only Python standard library (3.8+)
  • 🔄 Dynamic Port Allocation - Automatically finds available ports (4000-4999)
  • 📝 Service Registry - Persistent JSON-based service mappings
  • 🌐 HTTP Reverse Proxy - Route requests by hostname
  • 🔒 Thread-Safe - Concurrent request handling
  • ⚡ Lightweight - Single file, minimal overhead

📋 Requirements

  • Python 3.8 or higher
  • *.localhost DNS resolution (default on most systems including Kali Linux)

🚀 Quick Start

1. Start the Proxy Server

python localportmanager.py proxy

The proxy starts on http://127.0.0.1:1355 by default.

2. Register a Service

# Register a simple HTTP server
python localportmanager.py register myapp "python -m http.server {port}"

# Register a custom application
python localportmanager.py register api "uvicorn main:app --port {port}"

3. Access Your Service

Once registered, access your service through the proxy:

http://myapp.localhost:1355

📖 Usage

Commands

Command Description
proxy Start the reverse proxy server
register <name> <command> Register a new service
unregister <name> Remove a service from registry
list List all registered services
status Show proxy status and services

Options

# Start proxy on custom port
python localportmanager.py --port 8080 proxy

# Use custom state file
python localportmanager.py --state-file /path/to/registry.json proxy

# Auto-start service without prompting
python localportmanager.py register myapp "cmd" --yes

🔧 Examples

Web Development

# Register multiple frontend applications
python localportmanager.py register frontend-react "npm run dev -- --port {port}"
python localportmanager.py register frontend-vue "npm run serve -- --port {port}"
python localportmanager.py register api "python -m uvicorn api:app --port {port}"

Access via:

  • http://frontend-react.localhost:1355
  • http://frontend-vue.localhost:1355
  • http://api.localhost:1355

Penetration Testing (Zen-AI-Pentest)

# Register various listeners
python localportmanager.py register listener-01 "nc -lvp {port}"
python localportmanager.py register payload-server "python -m http.server {port}"
python localportmanager.py register api-server "python api.py {port}"

Docker Integration

# Register Docker container ports
python localportmanager.py register grafana "docker run -p {port}:3000 grafana/grafana"

🏗️ Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Client        │────▶│  LocalPortManager │────▶│  Backend Service │
│                 │     │  Proxy (127.0.0.1:1355)  │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                              │                           │
                              ▼                           ▼
                        ┌─────────────┐             ┌─────────────┐
                        │   Registry  │             │  Dynamic    │
                        │  (JSON)     │             │  Port (4000+)│
                        └─────────────┘             └─────────────┘

🔌 Service Routing

LocalPortManager routes requests based on the Host header:

Host Header Routes To
myapp.localhost:1355 Service "myapp"
myapp Service "myapp"
127.0.0.1:1355/myapp/... Service "myapp" (path-based fallback)

📁 Project Structure

.
├── localportmanager.py    # Main application (single file)
├── README.md              # This file
├── LICENSE                # MIT License
└── examples/              # Usage examples

🛠️ Development

Running Tests

# Test the module
python -c "import localportmanager; print('OK')"

# Test with verbose output
python localportmanager.py --version

Code Structure

  • PortRegistry - Manages service/port mappings
  • ReverseProxyHandler - HTTP request handler
  • LocalPortManager - Main application class

⚠️ Security Notes

  • Proxy only binds to 127.0.0.1 (localhost)
  • No authentication by design (local development tool)
  • State file stored in /tmp by default (cleared on reboot)
  • For production use, consider adding authentication layer

🤝 Integration with Zen-AI-Pentest

LocalPortManager is designed to work seamlessly with Zen-AI-Pentest:

# Inside Zen-AI-Pentest agent
from localportmanager import LocalPortManager

lpm = LocalPortManager(proxy_port=1355)
port = lpm.register_service("exploit-listener", "nc -lvp {port}")
print(f"Listener accessible at: http://exploit-listener.localhost:1355")

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Inspired by the need for simple service management in penetration testing
  • Built for the Zen-AI-Pentest framework
  • Zero-dependency philosophy for maximum portability

📞 Support

Made with ❤️ for the cybersecurity community