11 KiB
Table of Contents
- Development Background
- Features
- Installation and Usage
- Docker Deployment
- Performance
- Disclaimer
- Change Log
- Development Plan
- Acknowledgments
- Proxy Recommendations
Development Background
During penetration testing, it's often necessary to hide or change IP addresses to bypass security devices. However, tunnel proxies in the market are expensive, typically costing $3-6 per day, which is unaffordable for many. The author noticed that short-term IPs offer high cost-effectiveness, with each IP costing just a few cents, averaging $0.03-0.4 per day.
Therefore, ProxyCat was born! This tool aims to transform short-term IPs (lasting from 1 to 60 minutes) into fixed IPs for other tools to use, creating a proxy pool server that can be used permanently after one deployment.
Features
- Dual Protocol Support: Supports both SOCKS5 and HTTP protocol listening, compatible with more tools.
- Multiple Proxy Protocols: Supports HTTP/HTTPS/SOCKS5 proxy servers to meet various application needs.
- Multiple Switching Modes: Cycles through each proxy in the list sequentially; randomly selects available proxies to distribute traffic load and improve performance. Allows users to customize proxy selection logic for specific needs.
- Function-based Proxy Retrieval: Supports dynamic proxy retrieval through GetIP function for real-time availability.
- Automatic Validity Detection: Automatically detects proxy availability at startup to filter invalid proxies.
- Switch Only During Proxy Forwarding: Changes to new proxy server only when timer reaches zero and new requests arrive.
- Proxy Failure Switching: Automatically switches to new proxy if current proxy fails during traffic forwarding.
- Proxy Pool Authentication: Supports username/password-based authentication and blacklist/whitelist mechanisms.
- Real-time Status Updates: Displays current proxy status and next switch time.
- Configurable File: Easily adjust port, mode, authentication info via config.ini.
- Version Detection: Built-in version checking for automatic updates.
Installation and Usage
Dependencies Installation
The tool is based on Python, recommended version Python 3.8 or above. Install dependencies using:
pip install -r requirements.txt
# Or using Chinese mirror:
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
Running the Tool
Run the following command in the project directory to view help information:
python3 ProxyCat.py -h
Success is indicated by this response:
|\ _,,,---,,_ by honmashironeko
ZZZzz /,`.-'`' -. ;-;;,_
|,4- ) )-,_. ,\ ( `'-'
'---''(_/--' `-'\_) ProxyCat
Usage: ProxyCat.py [-h] [-c]
Parameters:
-h, --help Show this help message and exit
-c C Specify config file name (default: config.ini)
ip.txt Manual Proxy Entry
Add proxies to ip.txt in the following format (socks5://127.0.0.1:7890 or http://127.0.0.1:7890), one per line:
socks5://127.0.0.1:7890
https://127.0.0.1:7890
http://127.0.0.1:7890
...
Configuration File
Configure parameters in config.ini (or custom config file):
[SETTINGS]
# Local server listening port (default: 1080)
port = 1080
# Proxy rotation mode: cycle, custom, or load_balance (default: cycle)
mode = cycle
# Proxy change interval in seconds, 0 means change every request (default: 300)
interval = 300
# Local server authentication username (default: neko) empty means no auth
username = neko
# Local server authentication password (default: 123456) empty means no auth
password = 123456
# Whether to use getip module for proxy retrieval True/False (default: False)
use_getip = False
# Proxy list file (default: ip.txt)
proxy_file = ip.txt
# Enable proxy checking True/False (default: True)
check_proxies = True
# Language setting (cn/en)
language = en
# IP whitelist file path (empty to disable)
whitelist_file = whitelist.txt
# IP blacklist file path (empty to disable)
blacklist_file = blacklist.txt
# IP authentication priority (whitelist/blacklist)
# whitelist: Check whitelist first, allow if in whitelist
# blacklist: Check blacklist first, deny if in blacklist
ip_auth_priority = whitelist
After configuration, run:
python3 ProxyCat.py
Demo Effect
Fixed proxy address (default):
http://neko:123456@127.0.0.1:1080
http://127.0.0.1:1080
socks5://neko:123456@127.0.0.1:1080
socks5://127.0.0.1:1080
If you're deploying on a public network, simply replace 127.0.0.1 with your public IP.
Using API for Automatic Proxy Retrieval
The tool supports direct API calls to obtain proxy addresses. When you configure use_getip = True, the tool will no longer read from local ip.txt but instead execute getip.py script to obtain new proxy addresses (ensure your IP is whitelisted, and the format should be IP:port, only one proxy address can be used each time).
In this case, you need to modify the content of getip.py to your own API, with format IP:PORT. Default protocol is socks5, manually change to http if needed.
Docker Deployment
Please install Docker and Docker-compose in advance. You can search for installation methods online.
# Clone the project source code locally
git clone https://github.com/honmashironeko/ProxyCat.git
# Modify the content in the config.ini file in the config folder
# Enter the ProxyCat folder, build the image and start the container
docker-compose up -d --build
# Stop and start the service (you need to restart the service after modifying the configuration each time)
docker-compose down | docker-compose up -d
# View log information
docker logs proxycat
Performance
Through actual testing, when proxy server performance is sufficient, ProxyCat can handle 1000 concurrent connections without packet loss, covering most scanning and penetration testing needs.
Disclaimer
- By downloading, installing, using, or modifying this tool and related code, you indicate your trust in this tool.
- We take no responsibility for any form of loss or damage caused to yourself or others while using this tool.
- You are solely responsible for any illegal activities during your use of this tool, and we bear no legal or associated liability.
- Please carefully read and fully understand all terms, especially liability exemption or limitation clauses, and choose to accept or not.
- Unless you have read and accepted all terms of this agreement, you have no right to download, install, or use this tool.
- Your download, installation, and usage actions indicate you have read and agreed to be bound by the above agreement.
Change Log
2025/01/07
- Introduced connection pool mechanism to improve performance.
- Optimized error handling and logging.
- Enhanced proxy switching mechanism.
2025/01/03
- Centralized configuration parameters management into config files for better maintenance
- Fixed known bugs and improved stability and concurrency capabilities
2025/01/02
- Restructured software architecture for better usability
- Added blacklist/whitelist mechanism for authentication
- GetIP method now only requests proxy after receiving first request to prevent resource waste
- Changed language configuration logic, now controlled via config.ini parameter
- Updated configuration panel, addresses can be copied without username/password
- Added docker deployment support
2024/10/23
- Restructured code, split into separate files
- Added automatic proxy switching when current proxy fails during forwarding
2024/09/29
- Removed less-used single cycle mode, replaced with custom mode for customizable proxy switching logic
- Changed proxy validity checking to asynchronous for better speed
- Removed problematic SOCKS4 protocol support
- Beautified logging system
- Improved exception handling logic
- Added proxy format validation
2024/09/10
- Optimized concurrency efficiency, supporting next request before receiving response
- Added load balancing mode for random proxy selection and concurrent proxy usage
- Changed proxy validity checking to asynchronous for better efficiency
2024/09/09
- Added option to validate proxies in ip.txt at startup
- Function downgrade to support lower Python versions
2024/09/03
- Added local SOCKS5 listening for wider software compatibility
- Changed some functions to support lower Python versions
- Beautified output display
2024/08/31
- Major project structure adjustment
- Beautified display with continuous proxy switch time indication
- Added Ctrl+C support for stopping
- Major adjustment to async requests, improved concurrency efficiency
- Changed from runtime parameters to local ini config file
- Added support for local authentication-free mode
- Added version detection
- Added proxy server authentication
- Added GetIP update only on request feature
- Added proxy protocol auto-detection
- Added HTTPS protocol support
- Changed asyncio.timeout() to asyncio.wait_for() for lower Python version support
Development Plan
- Added local server authentication
- Added IP change per request feature
- Added static proxy auto-update module
- Added load balancing mode
- Added version detection
- Added proxy authentication support
- Added request-triggered getip updates
- Added initial proxy validity check
- Added SOCKS protocol support
- Add detailed logging with multi-user support
- Add Web UI interface
- Add docker deployment
- Develop babycat module
For feedback or suggestions, please contact via WeChat Official Account: 樱花庄的本间白猫
Acknowledgments
In no particular order, thanks to:
- AabyssZG
- ProbiusOfficial
- gh0stkey
- chars6
- qianzai
- ziwindlu