Proxy List Processor

Русская версия

A self-contained PHP panel for filtering and preparing proxy subscription lists.

Current project version: 1.4.0.

Each processing run uses one selected protocol module and creates two representations of the same homogeneous result:

• a Base64 subscription for NekoBox and compatible clients;
• a plain-text URI list with one configuration per line for inspection, testing and manual use, including Podkop Selector/URLTest workflows.

The project does not require a database, Composer, npm, cron, or a background service.

Project status

Version 1.4.0 is the current pre-release baseline before the repository is made public.

The primary workflow is cleaning large public lists before testing them in NekoBox/NekoRay-compatible clients and manually adding selected configurations to Podkop. Epodonios/v2ray-configs served as the first large source. Proxy List Processor is not affiliated with those projects and does not guarantee that third-party proxy servers work.

Features

• HTTP/HTTPS source URLs and local TXT uploads;
• automatic plain-text and Base64 detection;
• mixed input accepted, one selected protocol and one homogeneous result per run;
• protocol modules for VLESS, Shadowsocks, Trojan, SOCKS4/5, and Hysteria2;
• original display-name preservation, optional replacement, prefix and GeoLite2 country code;
• removal of control and bidirectional display characters from generated names;
• optional rejection of configurations containing Arabic or Persian script in the effective name or path-like text fields;
• protocol-specific validation, deduplication, and candidate scoring;
• Base64 and plain URI outputs created together;
• mathematical CAPTCHA, processing cooldown and public rate limits;
• request, file, decoded-content, line-count, URI and storage limits;
• SSRF and CSRF protection, security headers, safe HTML rendering and atomic storage;
• JSON history without a database;
• public session ownership or private shared history;
• automatic runtime cleanup without cron;
• optional GeoLite2 Country module;
• responsive light, dark, and system themes;
• installable PWA;
• Module API 2 and a dedicated Protocol Module API.

Deployment modes

Set deployment_mode in panel/config.php.

Public

This is the default and is intended for an internet-accessible installation:

• history and deletion are limited to the current browser session;
• results are retained for 24 hours;
• abandoned temporary files are retained for 1 hour;
• logs are retained for 7 days;
• no more than 3 processing attempts per IP in 10 minutes;
• no more than 20 processing attempts per installation per hour;
• runtime storage quota: 250 MiB.

The source limits remain large enough for a complete Epodonios protocol list to pass in one valid operation: 10 MiB input, 25,000 lines and 20,000 selected configurations.

Private

Private mode provides shared history, 14-day result retention, disabled public rate limits and a 1 GiB runtime quota.

Private mode does not enable authentication. Restrict access to panel/ using the web server, reverse proxy, VPN or another external access-control mechanism.

Output formats

Base64 subscription

The Base64 file contains the newline-separated URI list encoded as Base64. It is intended for NekoBox for Android and compatible clients.

Plain URI list

The plain file contains one processed URI per line. It is intended for opening, copying, testing and manually adding selected links to Podkop Connection URL, Selector or URLTest fields. It is a universal URI list, not a proprietary Podkop format.

Runtime storage

Runtime data is stored under panel/storage/ and generated results under subscriptions/. Bundled Apache rules deny HTTP access to runtime storage. For nginx add an equivalent rule:

location ^~ /proxy-list-processor/panel/storage/ {
    deny all;
    return 404;
}

Generated result URLs are stored as relative paths and resolved by the browser on the current installation domain.

Requirements

• PHP 8.2+;
• PHP cURL for URL downloads;
• JSON, filter, session and SPL;
• a web server capable of running PHP;
• HTTPS for normal PWA installation;
• PHP write access to panel/storage/ and subscriptions/.

Local file uploads work without cURL.

Manual installation

1. Copy the proxy-list-processor directory under public_html.

2. Make these directories writable by PHP:

   proxy-list-processor/panel/storage/
   proxy-list-processor/subscriptions/
   

3. Choose public or private in panel/config.php.

4. Open:

   https://example.org/proxy-list-processor/panel/
   

GeoLite2 Country

GeoLite2 data is not bundled. Place GeoLite2-Country.mmdb here:

proxy-list-processor/panel/modules/GeoLiteCountry/storage/GeoLite2-Country.mmdb

Only literal IPv4/IPv6 hosts are looked up. Domain names are not resolved.

Documentation

• Installation and upgrades
• Architecture
• Module API
• Protocol Module API
• Frontend and PWA
• Security and limits
• GeoLite2 Country
• Troubleshooting
• Changelog

Security

See SECURITY.md for vulnerability reporting and sensitive-data guidance. Do not publish complete proxy URIs, UUIDs, passwords, subscription tokens, private URLs or production logs.

License

MIT. See LICENSE.