vzrecon 3.0.0__tar.gz

vzrecon-3.0.0/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 VZLOI GROUP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

vzrecon-3.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: vzrecon
+Version: 3.0.0
+Summary: Protocol-level validator for HTTP/SOCKS4/SOCKS5 proxies
+Author: VZLOI GROUP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vzloi/vzrecon
+Project-URL: Source, https://github.com/vzloi/vzrecon
+Project-URL: Issues, https://github.com/vzloi/vzrecon/issues
+Project-URL: Changelog, https://github.com/vzloi/vzrecon/blob/main/CHANGELOG.md
+Keywords: proxy,socks,socks5,socks4,validator,recon,async
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# vzrecon
+
+Protocol-level validator for HTTP, SOCKS4 and SOCKS5 proxies.
+Zero dependencies. Termux-native.
+
+Signed: VZLOI GROUP // ops
+
+## Install
+
+    pip install -e .
+    vzrecon --self-test
+
+## Use
+
+    vzrecon                          # scan cwd for *_proxies.txt
+    vzrecon -d ./lists -o ./out      # explicit paths
+    vzrecon --preset stealth         # 200 workers
+    vzrecon --preset turbo           # 2400 workers
+    vzrecon --only http,socks5
+    vzrecon --plain
+
+## Protocols
+
+- HTTP    RFC 7231 CONNECT + forward GET fallback
+- SOCKS5  RFC 1928, no-auth greeting
+- SOCKS4  original spec, IPv4 targets only
+
+## Output
+
+- `<proto>_alive.txt` — endpoints, one per line
+- `<proto>_alive.json` — signed_by, protocol, count, proxies[]
+- `<proto>_alive.csv` — endpoint, latency_ms
+
+## Exit codes
+
+- 0 scan completed
+- 1 self-test failed
+- 2 config error
+- 3 no source files found
+
+## License
+
+MIT. Copyright (c) 2026 VZLOI GROUP.

vzrecon-3.0.0/README.md

@@ -0,0 +1,43 @@
+# vzrecon
+
+Protocol-level validator for HTTP, SOCKS4 and SOCKS5 proxies.
+Zero dependencies. Termux-native.
+
+Signed: VZLOI GROUP // ops
+
+## Install
+
+    pip install -e .
+    vzrecon --self-test
+
+## Use
+
+    vzrecon                          # scan cwd for *_proxies.txt
+    vzrecon -d ./lists -o ./out      # explicit paths
+    vzrecon --preset stealth         # 200 workers
+    vzrecon --preset turbo           # 2400 workers
+    vzrecon --only http,socks5
+    vzrecon --plain
+
+## Protocols
+
+- HTTP    RFC 7231 CONNECT + forward GET fallback
+- SOCKS5  RFC 1928, no-auth greeting
+- SOCKS4  original spec, IPv4 targets only
+
+## Output
+
+- `<proto>_alive.txt` — endpoints, one per line
+- `<proto>_alive.json` — signed_by, protocol, count, proxies[]
+- `<proto>_alive.csv` — endpoint, latency_ms
+
+## Exit codes
+
+- 0 scan completed
+- 1 self-test failed
+- 2 config error
+- 3 no source files found
+
+## License
+
+MIT. Copyright (c) 2026 VZLOI GROUP.

vzrecon-3.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vzrecon"
+version = "3.0.0"
+description = "Protocol-level validator for HTTP/SOCKS4/SOCKS5 proxies"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "VZLOI GROUP"}]
+keywords = ["proxy","socks","socks5","socks4","validator","recon","async"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet",
+  "Topic :: System :: Networking",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/vzloi/vzrecon"
+Source = "https://github.com/vzloi/vzrecon"
+Issues = "https://github.com/vzloi/vzrecon/issues"
+Changelog = "https://github.com/vzloi/vzrecon/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vzrecon = "vzrecon.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vzrecon*"]
+
+[tool.setuptools.package-data]
+vzrecon = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

vzrecon-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vzrecon-3.0.0/tests/test_config.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+import pytest
+
+from vzrecon.config import Config, PRESETS
+
+def _write(tmp_path, body):
+    p = Path(tmp_path) / "c.toml"
+    p.write_text(body)
+    return p
+
+def test_defaults():
+    Config().validate()
+
+def test_toml(tmp_path):
+    p = _write(tmp_path, 'workers = 500\ntarget_port = 8080\n')
+    c = Config.from_toml(p)
+    assert c.workers == 500
+    assert c.target_port == 8080
+
+def test_unknown(tmp_path):
+    p = _write(tmp_path, 'nope = 1\n')
+    with pytest.raises(ValueError):
+        Config.from_toml(p)
+
+def test_bad_port():
+    with pytest.raises(ValueError):
+        Config(target_port=0).validate()
+
+def test_bad_format():
+    with pytest.raises(ValueError):
+        Config(format="xml").validate()
+
+def test_preset():
+    c = Config().apply_preset("stealth")
+    assert c.workers == PRESETS["stealth"]["workers"]
+
+def test_bad_preset():
+    with pytest.raises(ValueError):
+        Config().apply_preset("nope")

vzrecon-3.0.0/tests/test_metrics.py

@@ -0,0 +1,29 @@
+from vzrecon.metrics import Meter, fmt_dur, fmt_int
+
+def test_tick():
+    m = Meter()
+    m.tick(ok=True, latency_ms=10)
+    m.tick(ok=False)
+    m.tick(ok=True, latency_ms=20)
+    assert m.done == 3
+    assert m.ok == 2
+    assert m.fail == 1
+
+def test_p95():
+    m = Meter()
+    for v in range(100):
+        m.tick(ok=True, latency_ms=float(v))
+    assert m.percentile(0.5) == 50
+    assert m.percentile(0.95) == 95
+
+def test_progress():
+    m = Meter()
+    m.total = 10
+    for _ in range(4):
+        m.tick(ok=True)
+    assert m.progress == 0.4
+
+def test_fmt():
+    assert fmt_int(1234567) == "1 234 567"
+    assert fmt_dur(None) == "--:--"
+    assert fmt_dur(65) == "01:05"

vzrecon-3.0.0/tests/test_protocols.py

@@ -0,0 +1,50 @@
+import asyncio
+import contextlib
+
+import pytest
+
+from vzrecon.protocols import (
+    http_connect,
+    socks4_connect,
+    socks5_connect,
+)
+from vzrecon.selftest import _mh, _m4, _m5
+
+async def _serve(h):
+    srv = await asyncio.start_server(h, "127.0.0.1", 0)
+    return srv, srv.sockets[0].getsockname()[1]
+
+async def _run(handler, validator):
+    srv, port = await _serve(handler)
+    try:
+        return await validator(
+            "127.0.0.1", port, "example.com", 443,
+            tcp_timeout=2.0, hs_timeout=2.0,
+        )
+    finally:
+        srv.close()
+        with contextlib.suppress(Exception):
+            await srv.wait_closed()
+
+@pytest.mark.asyncio
+async def test_http():
+    lat = await _run(_mh, http_connect)
+    assert lat is not None and lat > 0
+
+@pytest.mark.asyncio
+async def test_socks5():
+    lat = await _run(_m5, socks5_connect)
+    assert lat is not None and lat > 0
+
+@pytest.mark.asyncio
+async def test_socks4():
+    lat = await _run(_m4, socks4_connect)
+    assert lat is not None and lat > 0
+
+@pytest.mark.asyncio
+async def test_refused():
+    lat = await http_connect(
+        "127.0.0.1", 1, "example.com", 443,
+        tcp_timeout=0.5, hs_timeout=0.5,
+    )
+    assert lat is None

vzrecon-3.0.0/vzrecon/__init__.py

@@ -0,0 +1,4 @@
+__version__="3.0.0"
+__codename__="IRON VEIL"
+__author__="VZLOI GROUP"
+__all__=["Config","Scan","Meter","Hit"]

vzrecon-3.0.0/vzrecon/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

vzrecon-3.0.0/vzrecon/brand.py

@@ -0,0 +1,42 @@
+BANNER = (
+ "  ██╗   ██╗███████╗██╗      ██████╗ ██╗",
+ "  ██║   ██║╚══███╔╝██║     ██╔═══██╗██║",
+ "  ██║   ██║  ███╔╝ ██║     ██║   ██║██║",
+ "  ╚██╗ ██╔╝ ███╔╝  ██║     ██║   ██║██║",
+ "   ╚████╔╝ ███████╗███████╗╚██████╔╝██║",
+ "    ╚═══╝  ╚══════╝╚══════╝ ╚═════╝ ╚═╝",
+)
+CREW = "VZLOI GROUP"
+SUFFIX = "ops"
+TOOL = "vzrecon"
+CODENAME = "IRON VEIL"
+TAGLINE = "recon division"
+
+class SGR:
+    R     = "\x1b[0m"
+    B     = "\x1b[1m"
+    D     = "\x1b[2m"
+    I     = "\x1b[3m"
+    U     = "\x1b[4m"
+
+    BLK   = "\x1b[38;5;232m"
+    IRON  = "\x1b[38;5;240m"
+    SLATE = "\x1b[38;5;244m"
+    ASH   = "\x1b[38;5;250m"
+    IVORY = "\x1b[38;5;255m"
+
+    BLOOD = "\x1b[38;5;52m"
+    CRIM  = "\x1b[38;5;160m"
+    FLARE = "\x1b[38;5;203m"
+    GOLD  = "\x1b[38;5;220m"
+    AMBER = "\x1b[38;5;214m"
+
+    CYAN  = "\x1b[38;5;66m"
+    ICE   = "\x1b[38;5;117m"
+    VERD  = "\x1b[38;5;77m"
+    GREEN = "\x1b[38;5;114m"
+
+    # aliases for legacy call sites
+    DIM   = IRON
+    STEEL = SLATE
+    GRN   = VERD

vzrecon-3.0.0/vzrecon/cli.py

@@ -0,0 +1,131 @@
+import argparse, asyncio, contextlib, secrets, sys, time
+from pathlib import Path
+from . import __codename__, __version__
+from .brand import BANNER, CREW, SGR, SUFFIX, TOOL
+from .config import PRESETS, Config
+from .engine import Scan, discover
+from .platform import notify, wake_lock, wake_unlock
+from .tui import TUI
+from .writers import emit_csv, emit_json, emit_txt
+def _parse(a):
+    p=argparse.ArgumentParser(prog=TOOL,
+        description=f"proxy validator // {CREW} {SUFFIX}")
+    p.add_argument("--version",action="version",
+                   version=f"{TOOL} {__version__} ({__codename__})")
+    p.add_argument("-c","--config",type=Path)
+    p.add_argument("-d","--dir",type=Path,default=Path.cwd())
+    p.add_argument("-o","--output-dir",type=Path,default=Path("."))
+    p.add_argument("-t","--target")
+    p.add_argument("-w","--workers",type=int)
+    p.add_argument("--format",choices=("txt","json","csv"))
+    p.add_argument("--only")
+    p.add_argument("--preset",choices=tuple(PRESETS.keys()))
+    p.add_argument("--list-presets",action="store_true")
+    p.add_argument("--self-test",action="store_true")
+    p.add_argument("--plain",action="store_true")
+    p.add_argument("--no-notify",action="store_true")
+    p.add_argument("--verify",action="store_true",
+                   help="send a real request through the tunnel")
+    return p.parse_args(a)
+def _merge(a):
+    c=Config.from_toml(a.config) if a.config else Config()
+    if a.preset: c=c.apply_preset(a.preset)
+    c.source_dir=str(a.dir); c.output_dir=str(a.output_dir)
+    if a.workers is not None: c.workers=a.workers
+    if a.format: c.format=a.format
+    if a.target:
+        h,_,pt=a.target.partition(":")
+        c.target_host=h; c.target_port=int(pt) if pt else 443
+    if a.only:
+        c.protocols=tuple(s.strip() for s in a.only.split(",") if s.strip())
+    if a.no_notify: c.notify=False
+    if a.verify: c.verify=True
+    c.validate(); return c
+async def _dispatch(scans,cfg,plain):
+    if plain:
+        await asyncio.gather(*(s.run() for s in scans)); return
+    sid=secrets.token_hex(4).upper()
+    tui=TUI(scans,f"{cfg.target_host}:{cfg.target_port}",
+            cfg.workers,sid,"balanced")
+    tui.attach(); tui.enter()
+    ts=[asyncio.create_task(s.run()) for s in scans]
+    tick=1.0/cfg.render_hz
+    try:
+        while not all(t.done() for t in ts):
+            for s in scans: s.meter.sample()
+            tui.draw(); await asyncio.sleep(tick)
+        tui.draw()
+    finally:
+        for t in ts: t.cancel()
+        with contextlib.suppress(Exception):
+            await asyncio.gather(*ts,return_exceptions=True)
+        tui.leave()
+def _write(scans,cfg,out):
+    out.mkdir(parents=True,exist_ok=True)
+    for s in scans:
+        stem=out/f"{s.kind}_alive"
+        if cfg.format=="txt": emit_txt(stem.with_suffix(".txt"),s.hits)
+        elif cfg.format=="json": emit_json(stem.with_suffix(".json"),s.kind,s.hits)
+        else: emit_csv(stem.with_suffix(".csv"),s.hits)
+def _banner():
+    return "\n".join(f"  {SGR.CRIM}{l}{SGR.R}" for l in BANNER)
+def _presets():
+    print(f"\n  {SGR.CRIM}{SGR.B}{CREW} // {SUFFIX}{SGR.R}  ·  presets")
+    print(f"  {SGR.DIM}{'─'*46}{SGR.R}")
+    for n,v in PRESETS.items():
+        print(f"  {SGR.GOLD}{n:<10}{SGR.R} {SGR.STEEL}"
+              f"workers={v['workers']:<5} tcp={v['tcp_timeout']}s "
+              f"hs={v['hs_timeout']}s hz={v['render_hz']}{SGR.R}")
+    print(); return 0
+def main(argv=None):
+    a=_parse(argv)
+    if a.list_presets: return _presets()
+    if a.self_test:
+        from .selftest import run
+        print(f"\n  {SGR.CRIM}{SGR.B}{CREW} // {SUFFIX}{SGR.R}  "
+              f"·  protocol self-test")
+        print(f"  {SGR.DIM}{'─'*46}{SGR.R}")
+        rc=asyncio.run(run()); print(); return rc
+    try: cfg=_merge(a)
+    except (ValueError,FileNotFoundError) as e:
+        print(f"{SGR.CRIM}config:{SGR.R} {e}",file=sys.stderr)
+        return 2
+    src=discover(cfg)
+    if not src:
+        print(f"{SGR.CRIM}no sources{SGR.R} in {cfg.source_dir}",
+              file=sys.stderr)
+        return 3
+    print(_banner())
+    print(f"  {SGR.STEEL}protocols:{SGR.R} {', '.join(k for k,_ in src)}")
+    print(f"  {SGR.STEEL}sources:  {SGR.R} {len(src)} file(s)")
+    print(f"  {SGR.STEEL}target:   {SGR.R} {cfg.target_host}:{cfg.target_port}")
+    print(f"  {SGR.STEEL}workers:  {SGR.R} {cfg.workers}\n")
+    if cfg.wake_lock: wake_lock()
+    scans=[]
+    Path(cfg.output_dir).mkdir(parents=True,exist_ok=True)
+    for k,s in src:
+        scans.append(Scan(k,s,Path(cfg.output_dir)/f"{k}_alive.txt",cfg))
+    t0=time.monotonic()
+    try:
+        with contextlib.suppress(KeyboardInterrupt):
+            asyncio.run(_dispatch(scans,cfg,a.plain))
+    finally:
+        if cfg.wake_lock: wake_unlock()
+    dt=time.monotonic()-t0
+    _write(scans,cfg,Path(cfg.output_dir))
+    print(f"\n  {SGR.CRIM}{SGR.B}{CREW} // {SUFFIX}{SGR.R}  "
+          f"·  scan complete")
+    print(f"  {SGR.DIM}{'─'*46}{SGR.R}")
+    print(f"  {SGR.STEEL}duration:{SGR.R} {dt:.1f}s")
+    total=0
+    for s in scans:
+        m=s.meter
+        pct=(m.ok/m.done*100) if m.done else 0
+        total+=m.ok
+        print(f"  {s.kind:<7} {m.ok:>6} / {m.done:<6}  ({pct:5.1f}%)")
+    print(f"  {SGR.DIM}{'─'*46}{SGR.R}")
+    print(f"  total  {SGR.GRN}{total}{SGR.R} alive  →  {cfg.output_dir}\n")
+    if cfg.notify:
+        notify(f"{TOOL} · scan complete",
+               f"{total} alive · {sum(s.meter.done for s in scans)} checked · {dt:.0f}s")
+    return 0

vzrecon-3.0.0/vzrecon/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+import tomllib
+from dataclasses import dataclass,fields,replace
+from pathlib import Path
+PRESETS={
+    "stealth": {"workers":200,"tcp_timeout":4.0,"hs_timeout":8.0,"render_hz":2.0},
+    "balanced":{"workers":1200,"tcp_timeout":3.0,"hs_timeout":6.0,"render_hz":3.0},
+    "turbo":   {"workers":2400,"tcp_timeout":2.0,"hs_timeout":5.0,"render_hz":4.0},
+}
+@dataclass(slots=True)
+class Config:
+    workers:int=1200
+    tcp_timeout:float=3.0
+    hs_timeout:float=6.0
+    target_host:str="api.trongrid.io"
+    target_port:int=443
+    render_hz:float=3.0
+    sample_size:int=10
+    source_dir:str="."
+    output_dir:str="."
+    format:str="txt"
+    protocols:tuple=("http","socks4","socks5")
+    notify:bool=True
+    wake_lock:bool=True
+    verify:bool=False
+    @classmethod
+    def from_toml(cls,path):
+        raw=tomllib.loads(Path(path).read_text("utf-8"))
+        valid={f.name for f in fields(cls)}
+        unknown=set(raw)-valid
+        if unknown: raise ValueError(f"unknown keys: {sorted(unknown)}")
+        if "protocols" in raw: raw["protocols"]=tuple(raw["protocols"])
+        return cls(**raw)
+    def apply_preset(self,name):
+        if name not in PRESETS: raise ValueError(f"unknown preset: {name}")
+        return replace(self,**PRESETS[name])
+    def validate(self):
+        if self.workers<1: raise ValueError("workers must be >= 1")
+        if not (1<=self.target_port<=65535): raise ValueError("target_port out of range")
+        if self.format not in {"txt","json","csv"}: raise ValueError(f"bad format: {self.format}")
+        for p in self.protocols:
+            if p not in {"http","socks4","socks5"}: raise ValueError(f"bad protocol: {p}")

vzrecon-3.0.0/vzrecon/engine.py

@@ -0,0 +1,66 @@
+import asyncio, contextlib
+from dataclasses import dataclass
+from pathlib import Path
+from .metrics import Meter
+from .protocols import REGISTRY
+@dataclass(slots=True)
+class Hit:
+    endpoint:str
+    kind:str
+    latency_ms:float
+class Scan:
+    def __init__(self,kind,source,sink,cfg,on_hit=None):
+        self.kind=kind; self.source=source; self.sink=sink; self.cfg=cfg
+        self.on_hit=on_hit; self.meter=Meter()
+        self._q=asyncio.Queue(); self._fh=None; self.hits=[]
+    def _load(self):
+        if not self.source.exists(): return []
+        seen=set(); out=[]
+        for raw in self.source.read_text("utf-8",errors="ignore").splitlines():
+            l=raw.strip()
+            if l and l not in seen:
+                seen.add(l); out.append(l)
+        return out
+    async def run(self):
+        e=self._load(); self.meter.total=len(e)
+        if not e: return
+        for x in e: self._q.put_nowait(x)
+        self._fh=self.sink.open("w",buffering=1)
+        v=REGISTRY[self.kind]; cfg=self.cfg
+        async def consume():
+            while True:
+                try: entry=self._q.get_nowait()
+                except asyncio.QueueEmpty: return
+                try:
+                    h,_,ps=entry.rpartition(":")
+                    if not h or not ps.isdigit():
+                        self.meter.tick(ok=False); continue
+                    lat=await v(h,int(ps),cfg.target_host,cfg.target_port,
+                               tcp_timeout=cfg.tcp_timeout,
+                               hs_timeout=cfg.hs_timeout,
+                               verify=cfg.verify)
+                    if lat is None:
+                        self.meter.tick(ok=False)
+                    else:
+                        self.meter.tick(ok=True,latency_ms=lat)
+                        self._fh.write(entry+"\n")
+                        self.hits.append((entry,lat))
+                        if self.on_hit:
+                            with contextlib.suppress(Exception):
+                                self.on_hit(Hit(entry,self.kind,lat))
+                except asyncio.CancelledError: return
+                except Exception: self.meter.tick(ok=False)
+                finally: self._q.task_done()
+        ws=[asyncio.create_task(consume()) for _ in range(cfg.workers)]
+        try: await asyncio.gather(*ws)
+        finally:
+            for t in ws: t.cancel()
+            await asyncio.gather(*ws,return_exceptions=True)
+            if self._fh is not None: self._fh.close()
+def discover(cfg):
+    base=Path(cfg.source_dir); found=[]
+    for p in cfg.protocols:
+        s=base/f"{p}_proxies.txt"
+        if s.exists() and s.stat().st_size>0:
+            found.append((p,s))
+    return found

vzrecon-3.0.0/vzrecon/metrics.py

@@ -0,0 +1,54 @@
+import time
+from collections import deque
+from dataclasses import dataclass,field
+_S="▁▂▃▄▅▆▇█"
+@dataclass
+class Meter:
+    total:int=0
+    done:int=0
+    ok:int=0
+    fail:int=0
+    started_at:float=field(default_factory=time.monotonic)
+    _w:deque=field(default_factory=lambda:deque(maxlen=60))
+    _p:int=0
+    _l:deque=field(default_factory=lambda:deque(maxlen=512))
+    def tick(self,*,ok,latency_ms=None):
+        self.done+=1
+        if ok:
+            self.ok+=1
+            if latency_ms is not None: self._l.append(latency_ms)
+        else: self.fail+=1
+    def sample(self):
+        self._w.append((time.monotonic(),self.done-self._p))
+        self._p=self.done
+    def rate(self):
+        if len(self._w)<2: return 0.0
+        t0,_=self._w[0]; t1,_=self._w[-1]
+        dt=t1-t0
+        if dt<=0: return 0.0
+        return sum(n for _,n in self._w)/dt
+    def eta(self):
+        rem=self.total-self.done; r=self.rate()
+        if r<=0 or rem<=0: return None
+        return rem/r
+    def percentile(self,p):
+        if not self._l: return None
+        d=sorted(self._l)
+        return d[min(len(d)-1,int(p*len(d)))]
+    def spark(self,w=24):
+        if not self._w: return " "*w
+        s=[n for _,n in self._w][-w:]
+        hi=max(s) or 1
+        return "".join(_S[min(7,(n*8)//hi)] for n in s).rjust(w)
+    @property
+    def elapsed(self): return time.monotonic()-self.started_at
+    @property
+    def progress(self): return self.done/self.total if self.total else 0.0
+def fmt_dur(s):
+    if s is None: return "--:--"
+    n=int(s)
+    return f"{n//60:02d}:{n%60:02d}" if n<3600 else f"{n//3600}h{(n%3600)//60:02d}m"
+def fmt_int(n): return f"{n:,}".replace(","," ")
+def fmt_uptime(s):
+    s=int(s); h,r=divmod(s,3600); m,sec=divmod(r,60)
+    return f"{h:02d}:{m:02d}:{sec:02d}"

vzrecon-3.0.0/vzrecon/platform.py

@@ -0,0 +1,23 @@
+import os, shutil, subprocess
+def _have(c): return shutil.which(c) is not None
+def is_termux(): return "com.termux" in os.environ.get("PREFIX","")
+def wake_lock():
+    if not _have("termux-wake-lock"): return False
+    try:
+        subprocess.run(["termux-wake-lock"],check=False,
+                       stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+        return True
+    except Exception: return False
+def wake_unlock():
+    if not _have("termux-wake-unlock"): return
+    try:
+        subprocess.run(["termux-wake-unlock"],check=False,
+                       stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+    except Exception: pass
+def notify(t,b):
+    if not _have("termux-notification"): return
+    try:
+        subprocess.run(["termux-notification","--title",t,"--content",b,
+                        "--priority","high"],check=False,
+                       stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+    except Exception: pass

vzrecon-3.0.0/vzrecon/protocols.py

@@ -0,0 +1,100 @@
+import asyncio, socket
+from time import perf_counter
+async def _d(h,p,t):
+    return await asyncio.wait_for(asyncio.open_connection(h,p),timeout=t)
+async def _tun(host,port,th,tp,tt,ht,verify=False):
+    r=w=None; t0=perf_counter()
+    try:
+        r,w=await _d(host,port,tt)
+        req=(f"CONNECT {th}:{tp} HTTP/1.1\r\nHost: {th}:{tp}\r\n"
+             f"Proxy-Connection: keep-alive\r\n\r\n")
+        w.write(req.encode()); await w.drain()
+        line=await asyncio.wait_for(r.readline(),timeout=ht)
+        if not line.startswith(b"HTTP/"): return None
+        parts=line.split(b" ",2)
+        if len(parts)<2 or parts[1]!=b"200": return None
+        # ── verify phase: real request through the tunnel ──
+        if verify:
+            v = await _verify_through(r,w,th,tp,ht)
+            if v is None: return None
+        return (perf_counter()-t0)*1000.0
+    except (OSError,asyncio.TimeoutError,asyncio.IncompleteReadError): return None
+    finally:
+        if w is not None: w.close()
+async def _verify_through(r,w,th,tp,ht):
+    """Send a real HTTP/1.0 request through the established tunnel.
+    Any HTTP status line at all means the proxy is actually forwarding."""
+    try:
+        req=(f"HEAD / HTTP/1.0\r\nHost: {th}\r\n"
+             f"User-Agent: vzrecon/3.0\r\n\r\n")
+        w.write(req.encode()); await w.drain()
+        line=await asyncio.wait_for(r.readline(),timeout=ht)
+        if not line.startswith(b"HTTP/"): return None
+        return 1
+    except (OSError,asyncio.TimeoutError,asyncio.IncompleteReadError):
+        return None
+async def _fwd(host,port,th,tt,ht):
+    r=w=None; t0=perf_counter()
+    try:
+        r,w=await _d(host,port,tt)
+        req=(f"GET http://{th}/ HTTP/1.1\r\nHost: {th}\r\n"
+             f"User-Agent: vzrecon/3.0\r\nConnection: close\r\n\r\n")
+        w.write(req.encode()); await w.drain()
+        line=await asyncio.wait_for(r.readline(),timeout=ht)
+        if not line.startswith(b"HTTP/"): return None
+        return (perf_counter()-t0)*1000.0
+    except (OSError,asyncio.TimeoutError,asyncio.IncompleteReadError): return None
+    finally:
+        if w is not None: w.close()
+async def http_connect(host,port,th,tp,*,tcp_timeout,hs_timeout,verify=False):
+    r=await _tun(host,port,th,tp,tcp_timeout,hs_timeout,verify=verify)
+    if r is not None: return r
+    # forward-GET is already a real request; no extra verify needed
+    return await _fwd(host,port,th,tcp_timeout,hs_timeout)
+async def socks5_connect(host,port,th,tp,*,tcp_timeout,hs_timeout,verify=False):
+    r=w=None; t0=perf_counter()
+    try:
+        r,w=await _d(host,port,tcp_timeout)
+        w.write(b"\x05\x01\x00"); await w.drain()
+        g=await asyncio.wait_for(r.readexactly(2),timeout=hs_timeout)
+        if g!=b"\x05\x00": return None
+        n=th.encode("idna")
+        if len(n)>255: return None
+        w.write(b"\x05\x01\x00\x03"+bytes((len(n),))+n+tp.to_bytes(2,"big"))
+        await w.drain()
+        h=await asyncio.wait_for(r.readexactly(4),timeout=hs_timeout)
+        if h[0]!=0x05 or h[1]!=0x00: return None
+        a=h[3]
+        if a==0x01: tail=6
+        elif a==0x04: tail=18
+        elif a==0x03:
+            ln=await asyncio.wait_for(r.readexactly(1),timeout=hs_timeout)
+            tail=ln[0]+2
+        else: return None
+        await asyncio.wait_for(r.readexactly(tail),timeout=hs_timeout)
+        if verify:
+            v = await _verify_through(r,w,th,tp,hs_timeout)
+            if v is None: return None
+        return (perf_counter()-t0)*1000.0
+    except (OSError,asyncio.TimeoutError,asyncio.IncompleteReadError): return None
+    finally:
+        if w is not None: w.close()
+async def socks4_connect(host,port,th,tp,*,tcp_timeout,hs_timeout,verify=False):
+    r=w=None; t0=perf_counter()
+    try:
+        try: ipv4=socket.gethostbyname(th)
+        except OSError: return None
+        octets=bytes(int(x) for x in ipv4.split("."))
+        r,w=await _d(host,port,tcp_timeout)
+        w.write(b"\x04\x01"+tp.to_bytes(2,"big")+octets+b"\x00")
+        await w.drain()
+        rep=await asyncio.wait_for(r.readexactly(8),timeout=hs_timeout)
+        if rep[0]!=0x00 or rep[1]!=0x5A: return None
+        if verify:
+            v = await _verify_through(r,w,th,tp,hs_timeout)
+            if v is None: return None
+        return (perf_counter()-t0)*1000.0
+    except (OSError,asyncio.TimeoutError,asyncio.IncompleteReadError): return None
+    finally:
+        if w is not None: w.close()
+REGISTRY={"http":http_connect,"socks4":socks4_connect,"socks5":socks5_connect}

vzrecon-3.0.0/vzrecon/selftest.py

@@ -0,0 +1,54 @@
+import asyncio, contextlib
+from .protocols import http_connect, socks4_connect, socks5_connect
+async def _mh(r,w):
+    try:
+        l=await r.readline()
+        if l.startswith(b"CONNECT"):
+            w.write(b"HTTP/1.1 200 Connection established\r\n\r\n")
+            await w.drain()
+        while True:
+            h=await r.readline()
+            if h in (b"\r\n",b"\n",b""): break
+    finally: w.close()
+async def _m5(r,w):
+    try:
+        g=await r.readexactly(2)
+        if g!=b"\x05\x01": return
+        await r.readexactly(1)
+        w.write(b"\x05\x00"); await w.drain()
+        h=await r.readexactly(4); a=h[3]
+        if a==0x01: await r.readexactly(6)
+        elif a==0x03:
+            n=(await r.readexactly(1))[0]
+            await r.readexactly(n+2)
+        elif a==0x04: await r.readexactly(18)
+        w.write(b"\x05\x00\x00\x01\x00\x00\x00\x00\x00\x00")
+        await w.drain()
+    finally: w.close()
+async def _m4(r,w):
+    try:
+        await r.readexactly(8)
+        w.write(b"\x00\x5a\x00\x00\x00\x00\x00\x00")
+        await w.drain()
+    finally: w.close()
+CASES=[("http",_mh,http_connect),
+       ("socks5",_m5,socks5_connect),
+       ("socks4",_m4,socks4_connect)]
+async def _serve(h):
+    srv=await asyncio.start_server(h,"127.0.0.1",0)
+    return srv,srv.sockets[0].getsockname()[1]
+async def run():
+    fail=0
+    for name,handler,v in CASES:
+        srv,port=await _serve(handler)
+        try:
+            lat=await v("127.0.0.1",port,"example.com",443,
+                        tcp_timeout=2.0,hs_timeout=2.0)
+            ok=lat is not None
+            print(f"  {name:<7} {'ok  ' if ok else 'FAIL'}  {lat or 0:>7.2f} ms")
+            if not ok: fail+=1
+        finally:
+            srv.close()
+            with contextlib.suppress(Exception):
+                await srv.wait_closed()
+    return 0 if fail==0 else 1

vzrecon-3.0.0/vzrecon/tui.py

@@ -0,0 +1,206 @@
+import shutil, sys
+from datetime import datetime, timezone
+from .brand import BANNER, CODENAME, CREW, SUFFIX, TAGLINE, TOOL, SGR
+from .metrics import fmt_dur, fmt_int, fmt_uptime
+
+def _vis(s):
+    n = 0; i = 0
+    while i < len(s):
+        if s[i] == "\x1b":
+            j = s.find("m", i)
+            if j == -1: break
+            i = j + 1; continue
+        n += 1; i += 1
+    return n
+
+def _pad(s, w):
+    v = _vis(s)
+    return s if v >= w else s + " " * (w - v)
+
+def _hr(l, c, r, ch, w):
+    return f"{SGR.BLOOD}{l}{ch * w}{r}{SGR.R}"
+
+def _box_top(title, w):
+    t = f" {title} "
+    pad = w - _vis(t) - 2
+    return f"{SGR.BLOOD}┌─{r}{SGR.CRIM}{SGR.B}{t}{SGR.R}{SGR.BLOOD}{'─' * pad}─┐{SGR.R}"
+
+def _box_bot(w):
+    return f"{SGR.BLOOD}└{'─' * w}┘{SGR.R}"
+
+def _box_mid(s, w):
+    v = _vis(s)
+    return f"{SGR.BLOOD}│{SGR.R} {s}{' ' * (w - v - 1)}{SGR.BLOOD}│{SGR.R}"
+
+class TUI:
+    def __init__(self, scans, target, workers, sid, mode):
+        self.scans = scans
+        self.target = target
+        self.workers = workers
+        self.sid = sid
+        self.mode = mode
+        self._prev = ""
+        self._hits = []
+        self._cap = 7
+
+    def collect(self, h):
+        self._hits.append(h)
+        if len(self._hits) > 200:
+            self._hits = self._hits[-200:]
+
+    def attach(self):
+        for s in self.scans:
+            s.on_hit = self.collect
+
+    def _w(self):
+        try:
+            return max(64, min(shutil.get_terminal_size((80, 24)).columns - 2, 84))
+        except OSError:
+            return 78
+
+    def _header(self, W):
+        o = []
+        r = SGR.R
+        cap = f"{SGR.CRIM}{SGR.B}{CREW}{r} {SGR.IRON}·{r} {SGR.GOLD}{TOOL} 3.0.0{r} {SGR.IRON}·{r} {SGR.SLATE}{CODENAME}{r}"
+        left = f" {cap} "
+        right = f" {SGR.IRON}{TAGLINE}{r} "
+        pad = W - _vis(left) - _vis(right) - 2
+        o.append(f"{SGR.BLOOD}┌{'─' * (W - 2)}┐{r}")
+        o.append(f"{SGR.BLOOD}│{r}{left}{' ' * pad}{right}{SGR.BLOOD}│{r}")
+        for ln in BANNER:
+            p = (W - 2 - len(ln)) // 2
+            o.append(
+                f"{SGR.BLOOD}│{r}{' ' * max(0, p)}{SGR.CRIM}{SGR.B}{ln}{r}"
+                f"{' ' * max(0, W - 2 - p - len(ln))}{SGR.BLOOD}│{r}"
+            )
+        sub = f"{CREW} // {SUFFIX}"
+        p = (W - 2 - len(sub)) // 2
+        o.append(
+            f"{SGR.BLOOD}│{r}{' ' * p}{SGR.SLATE}{sub}{r}"
+            f"{' ' * (W - 2 - p - len(sub))}{SGR.BLOOD}│{r}"
+        )
+        o.append(_box_bot(W - 2))
+        return o
+
+    def _strip(self, W):
+        r = SGR.R
+        o = []
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
+        up = fmt_uptime(self.scans[0].meter.elapsed) if self.scans else "00:00:00"
+        row1 = (
+            f"{SGR.IRON}session{r}  {SGR.GOLD}{SGR.B}{self.sid}{r}"
+            f"     {SGR.IRON}uptime{r}  {SGR.IVORY}{up}{r}"
+            f"     {SGR.IRON}utc{r}  {SGR.IVORY}{now}{r}"
+        )
+        row2 = (
+            f"{SGR.IRON}target{r}  {SGR.IVORY}{self.target}{r}"
+            f"     {SGR.IRON}pool{r}  {SGR.IVORY}{self.workers}{r}"
+            f"     {SGR.IRON}mode{r}  {SGR.AMBER}{self.mode}{r}"
+        )
+        o.append(f"  {row1}")
+        o.append(f"  {row2}")
+        o.append("")
+        return o
+
+    def _panel(self, s, W):
+        r = SGR.R
+        o = []
+        m = s.meter
+        kind = s.kind.upper()
+        head = f"── {kind} "
+        rule = W - _vis(head) - 4
+        o.append(f"  {SGR.CRIM}{SGR.B}{head}{r}{SGR.BLOOD}{'─' * max(0, rule)}{r}")
+        bar_w = W - 32
+        frac = m.progress
+        fill = int(frac * bar_w)
+        bar = f"{SGR.ICE}{'█' * fill}{SGR.IRON}{'░' * (bar_w - fill)}{r}"
+        p95 = m.percentile(0.95)
+        p95s = f"{p95:>5.0f}ms" if p95 is not None else "    --"
+        eta = fmt_dur(m.eta())
+        o.append(
+            f"   {SGR.IRON}live{r} {SGR.GREEN}{SGR.B}{m.ok:>6}{r}"
+            f"   {SGR.IRON}dead{r} {SGR.CRIM}{m.fail:>6}{r}"
+            f"   {SGR.IRON}rate{r} {SGR.IVORY}{m.rate():>6.0f}/s{r}"
+            f"   {SGR.IRON}eta{r} {SGR.IVORY}{eta}{r}"
+            f"   {SGR.IRON}p95{r} {SGR.ASH}{p95s}{r}"
+        )
+        o.append(f"   {bar}  {SGR.ASH}{frac * 100:>5.1f}%{r}")
+        o.append(f"   {SGR.ICE}{m.spark(bar_w)}{r}")
+        o.append("")
+        return o
+
+    def _summary(self, W):
+        r = SGR.R
+        o = []
+        ok_t = sum(s.meter.ok for s in self.scans)
+        done_t = sum(s.meter.done for s in self.scans)
+        all_t = sum(s.meter.total for s in self.scans)
+        pct = (ok_t / done_t * 100.0) if done_t else 0.0
+        o.append(f"  {SGR.BLOOD}{'─' * (W - 4)}{r}")
+        o.append(
+            f"   {SGR.IRON}alive{r} {SGR.VERD}{SGR.B}{fmt_int(ok_t)}{r}"
+            f"    {SGR.IRON}checked{r} {SGR.ASH}{fmt_int(done_t)}/{fmt_int(all_t)}{r}"
+            f"    {SGR.IRON}hit-rate{r} {SGR.GOLD}{pct:.2f}%{r}"
+        )
+        o.append("")
+        return o
+
+    def _live(self, W):
+        r = SGR.R
+        o = []
+        if not self._hits:
+            return o
+        head = f"── live hits "
+        rule = W - _vis(head) - 4
+        o.append(f"  {SGR.CRIM}{SGR.B}{head}{r}{SGR.BLOOD}{'─' * max(0, rule)}{r}")
+        for h in self._hits[-self._cap:]:
+            if h.latency_ms < 200:
+                c = SGR.GREEN
+            elif h.latency_ms < 800:
+                c = SGR.AMBER
+            else:
+                c = SGR.CRIM
+            o.append(
+                f"   {SGR.CRIM}▸{r} {SGR.ICE}{h.kind:<7}{r}"
+                f"{SGR.IVORY}{h.endpoint:<28}{r}"
+                f"{c}{h.latency_ms:>6.0f} ms{r}"
+            )
+        o.append("")
+        return o
+
+    def _footer(self, W):
+        r = SGR.R
+        o = []
+        sig = f"{CREW} // {SUFFIX}"
+        p = (W - _vis(sig)) // 2
+        o.append(f"{' ' * max(0, p)}{SGR.BLOOD}{SGR.I}{sig}{r}")
+        return o
+
+    def _render(self):
+        W = self._w()
+        o = []
+        o += self._header(W)
+        o.append("")
+        o += self._strip(W)
+        for s in self.scans:
+            o += self._panel(s, W)
+        o += self._summary(W)
+        o += self._live(W)
+        o += self._footer(W)
+        return "\n".join(o)
+
+    def draw(self):
+        f = self._render()
+        if f == self._prev:
+            return
+        self._prev = f
+        sys.stdout.write("\x1b[H\x1b[2J" + f)
+        sys.stdout.flush()
+
+    def enter(self):
+        sys.stdout.write("\x1b[?1049h\x1b[?25l")
+        sys.stdout.flush()
+
+    def leave(self):
+        sys.stdout.write("\x1b[?25h\x1b[?1049l")
+        sys.stdout.flush()

vzrecon-3.0.0/vzrecon/writers.py

@@ -0,0 +1,14 @@
+import csv, json
+from pathlib import Path
+from .brand import CREW
+def emit_txt(p,hits):
+    b="\n".join(e for e,_ in hits)
+    Path(p).write_text(b+("\n" if b else ""),encoding="utf-8")
+def emit_json(p,kind,hits):
+    payload={"signed_by":CREW,"protocol":kind,"count":len(hits),
+             "proxies":[{"endpoint":e,"latency_ms":round(l,2)} for e,l in hits]}
+    Path(p).write_text(json.dumps(payload,indent=2),encoding="utf-8")
+def emit_csv(p,hits):
+    with Path(p).open("w",newline="",encoding="utf-8") as f:
+        w=csv.writer(f); w.writerow(["endpoint","latency_ms"])
+        for e,l in hits: w.writerow([e,f"{l:.2f}"])

vzrecon-3.0.0/vzrecon.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: vzrecon
+Version: 3.0.0
+Summary: Protocol-level validator for HTTP/SOCKS4/SOCKS5 proxies
+Author: VZLOI GROUP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vzloi/vzrecon
+Project-URL: Source, https://github.com/vzloi/vzrecon
+Project-URL: Issues, https://github.com/vzloi/vzrecon/issues
+Project-URL: Changelog, https://github.com/vzloi/vzrecon/blob/main/CHANGELOG.md
+Keywords: proxy,socks,socks5,socks4,validator,recon,async
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# vzrecon
+
+Protocol-level validator for HTTP, SOCKS4 and SOCKS5 proxies.
+Zero dependencies. Termux-native.
+
+Signed: VZLOI GROUP // ops
+
+## Install
+
+    pip install -e .
+    vzrecon --self-test
+
+## Use
+
+    vzrecon                          # scan cwd for *_proxies.txt
+    vzrecon -d ./lists -o ./out      # explicit paths
+    vzrecon --preset stealth         # 200 workers
+    vzrecon --preset turbo           # 2400 workers
+    vzrecon --only http,socks5
+    vzrecon --plain
+
+## Protocols
+
+- HTTP    RFC 7231 CONNECT + forward GET fallback
+- SOCKS5  RFC 1928, no-auth greeting
+- SOCKS4  original spec, IPv4 targets only
+
+## Output
+
+- `<proto>_alive.txt` — endpoints, one per line
+- `<proto>_alive.json` — signed_by, protocol, count, proxies[]
+- `<proto>_alive.csv` — endpoint, latency_ms
+
+## Exit codes
+
+- 0 scan completed
+- 1 self-test failed
+- 2 config error
+- 3 no source files found
+
+## License
+
+MIT. Copyright (c) 2026 VZLOI GROUP.

vzrecon-3.0.0/vzrecon.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_config.py
+tests/test_metrics.py
+tests/test_protocols.py
+vzrecon/__init__.py
+vzrecon/__main__.py
+vzrecon/brand.py
+vzrecon/cli.py
+vzrecon/config.py
+vzrecon/engine.py
+vzrecon/metrics.py
+vzrecon/platform.py
+vzrecon/protocols.py
+vzrecon/py.typed
+vzrecon/selftest.py
+vzrecon/tui.py
+vzrecon/writers.py
+vzrecon.egg-info/PKG-INFO
+vzrecon.egg-info/SOURCES.txt
+vzrecon.egg-info/dependency_links.txt
+vzrecon.egg-info/entry_points.txt
+vzrecon.egg-info/requires.txt
+vzrecon.egg-info/top_level.txt

vzrecon-3.0.0/vzrecon.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vzrecon-3.0.0/vzrecon.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vzrecon = vzrecon.cli:main

vzrecon-3.0.0/vzrecon.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23

vzrecon-3.0.0/vzrecon.egg-info/top_level.txt

@@ -0,0 +1 @@
+vzrecon