ja4proxy 0.3.0__tar.gz → 0.4.0__tar.gz

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ja4proxy
-Version: 0.3.0
+Version: 0.4.0
 Summary: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation
 Author-email: cipherwire <dev@cipherwire.link>
 License-Expression: MIT

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/ja4proxy/__init__.py

@@ -1,6 +1,6 @@
 """ja4proxy: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __author__ = "cipherwire"
 
 from ja4proxy.engine.bridge import NativeEngine

ja4proxy-0.4.0/ja4proxy/cli.py

@@ -0,0 +1,266 @@
+import asyncio
+import logging
+import os
+import shutil
+import sys
+
+import click
+
+from ja4proxy import __version__
+from ja4proxy.certs import CertificateAuthority
+from ja4proxy.engine.bridge import NativeEngine
+from ja4proxy.profiles import SUPPORTED_PROFILES, normalize_profile
+from ja4proxy.server import ProxyServer
+
+ASCII_BANNER = r"""
+      _       __ __                             
+     (_)___ _/ // / ____  _________  _  ____  __
+    / / __ `/ // /_/ __ \/ ___/ __ \| |/_/ / / /
+   / / /_/ /__  __/ /_/ / /  / /_/ />  </ /_/ / 
+__/ /\__,_/  /_/ / .___/_/   \____/_/|_|\__, /  
+/___/            /_/                    /____/   
+"""
+
+
+def render_banner() -> str:
+    banner_art = click.style(ASCII_BANNER.strip("\r\n"), fg="cyan", bold=True)
+    tagline = click.style(
+        "  Universal Browser TLS & JA4 Impersonation Proxy",
+        fg="white",
+        bold=True,
+    )
+    meta = click.style(
+        f"  Version: {__version__}  |  Docs: https://ja4proxy.cipherwire.link",
+        fg="bright_black",
+    )
+    return f"{banner_art}\n{tagline}\n{meta}\n"
+
+
+class BannerGroup(click.Group):
+    """Custom Click Group that renders the cyberpunk ASCII banner on help."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        formatter.write(render_banner() + "\n")
+        super().format_help(ctx, formatter)
+
+
+@click.group(cls=BannerGroup, no_args_is_help=True)
+@click.version_option(__version__, prog_name="ja4proxy")
+def main() -> None:
+    """High-performance universal forward proxy with authentic browser TLS and HTTP/2 framing."""
+    pass
+
+
+@main.command()
+@click.option("--host", default="127.0.0.1", help="Binding IP address.")
+@click.option("--port", "-p", default=8888, type=int, help="Port to listen on.")
+@click.option(
+    "--profile",
+    default="chrome_133",
+    help="Default browser profile (e.g. chrome_133, safari_16_0, firefox_133).",
+)
+@click.option(
+    "--upstream-proxy",
+    default=None,
+    help="Default upstream proxy URL (e.g. socks5://user:pass@host:1080).",
+)
+@click.option(
+    "--auth",
+    default=None,
+    help="Require username:password authentication for client connections.",
+)
+@click.option(
+    "--cert-dir", default=None, help="Directory to store CA and leaf certificates."
+)
+@click.option(
+    "--allow-private-networks",
+    is_flag=True,
+    help="Allow forwarding requests to private and loopback IP ranges.",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose debug logging.")
+def start(
+    host: str,
+    port: int,
+    profile: str,
+    upstream_proxy: str | None,
+    auth: str | None,
+    cert_dir: str | None,
+    allow_private_networks: bool,
+    verbose: bool,
+) -> None:
+    """Starts the ja4proxy server."""
+    log_level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    )
+
+    prof = normalize_profile(profile)
+    server = ProxyServer(
+        host=host,
+        port=port,
+        default_profile=prof,
+        cert_dir=cert_dir,
+        allow_private_networks=allow_private_networks,
+        upstream_proxy=upstream_proxy,
+        auth=auth,
+    )
+
+    ca_path = server.ca.ca_cert_path
+    sep = click.style("=" * 72, fg="cyan")
+    divider = click.style("-" * 72, fg="bright_black")
+
+    click.echo(render_banner())
+    click.echo(sep)
+    click.echo(
+        f" {click.style('[*] Engine Status:', fg='bright_white', bold=True)}   "
+        f"{click.style('ONLINE', fg='green', bold=True)}"
+    )
+    click.echo(
+        f" {click.style('[*] HTTP Ingress:', fg='bright_white', bold=True)}    "
+        f"{click.style(f'http://{host}:{port}', fg='cyan', underline=True)}"
+    )
+    click.echo(
+        f" {click.style('[*] SOCKS5 Ingress:', fg='bright_white', bold=True)}  "
+        f"{click.style(f'socks5://{host}:{port}', fg='cyan', underline=True)} "
+        f"{click.style('(Auto-detect on same port)', fg='bright_black')}"
+    )
+    click.echo(
+        f" {click.style('[*] Active Profile:', fg='bright_white', bold=True)}  "
+        f"{click.style(prof, fg='yellow', bold=True)}"
+    )
+    upstream_desc = upstream_proxy if upstream_proxy else "DIRECT"
+    click.echo(
+        f" {click.style('[*] Upstream Proxy:', fg='bright_white', bold=True)}  "
+        f"{click.style(upstream_desc, fg='bright_white')}"
+    )
+    auth_desc = "Enabled (HTTP Basic / SOCKS5)" if auth else "None (Open)"
+    click.echo(
+        f" {click.style('[*] Authentication:', fg='bright_white', bold=True)}  "
+        f"{click.style(auth_desc, fg='bright_white')}"
+    )
+    ssrf_status = (
+        click.style("PERMISSIVE (--allow-private-networks)", fg="yellow")
+        if allow_private_networks
+        else click.style("ENFORCED (RFC1918 & Loopback blocked)", fg="green")
+    )
+    click.echo(
+        f" {click.style('[*] SSRF Guard:', fg='bright_white', bold=True)}      "
+        f"{ssrf_status}"
+    )
+    click.echo(
+        f" {click.style('[*] Root CA Path:', fg='bright_white', bold=True)}    "
+        f"{click.style(ca_path, fg='bright_black')}"
+    )
+    click.echo(divider)
+    click.echo(
+        f" {click.style('Quick Test Command:', fg='bright_white', bold=True)}"
+    )
+    click.echo(
+        f"   {click.style(f'curl -x http://{host}:{port} https://tls.peet.ws/api/all', fg='yellow')}"
+    )
+    click.echo(sep)
+    click.echo("")
+
+    try:
+        asyncio.run(server.serve_forever())
+    except KeyboardInterrupt:
+        click.echo(click.style("\n[*] Shutting down ja4proxy...", fg="yellow"))
+
+
+@main.command(name="profiles")
+def list_profiles() -> None:
+    """Lists all supported browser profiles for TLS and HTTP/2 emulation."""
+    click.echo(render_banner())
+    click.echo(click.style("Available Browser Profiles (JA4 / TLS / HTTP/2):", fg="bright_white", bold=True))
+    click.echo("")
+
+    chrome_profs = [p for p in SUPPORTED_PROFILES if p.startswith("chrome")]
+    safari_profs = [p for p in SUPPORTED_PROFILES if p.startswith("safari")]
+    firefox_profs = [p for p in SUPPORTED_PROFILES if p.startswith("firefox")]
+
+    click.echo(click.style("  Google Chrome / Chromium:", fg="cyan", bold=True))
+    for p in chrome_profs:
+        tag = click.style(" (Default)", fg="green", bold=True) if p == "chrome_133" else ""
+        click.echo(f"    - {p}{tag}")
+
+    click.echo("")
+    click.echo(click.style("  Apple Safari & iOS WebKit:", fg="cyan", bold=True))
+    for p in safari_profs:
+        click.echo(f"    - {p}")
+
+    click.echo("")
+    click.echo(click.style("  Mozilla Firefox:", fg="cyan", bold=True))
+    for p in firefox_profs:
+        click.echo(f"    - {p}")
+    click.echo("")
+
+
+@main.command(name="ca")
+@click.option(
+    "--export",
+    "-e",
+    "export_path",
+    default=None,
+    help="Export root CA certificate (ca.pem) to specified path.",
+)
+def manage_ca(export_path: str | None) -> None:
+    """Inspects or exports the local Root CA certificate."""
+    ca = CertificateAuthority()
+    click.echo(render_banner())
+    sep = click.style("-" * 72, fg="bright_black")
+    click.echo(sep)
+    click.echo(f" {click.style('Root CA Certificate:', fg='bright_white', bold=True)} {ca.ca_cert_path}")
+    click.echo(f" {click.style('Root CA Private Key:', fg='bright_white', bold=True)} {ca.ca_key_path}")
+    click.echo(sep)
+
+    if export_path:
+        dest = os.path.abspath(export_path)
+        shutil.copyfile(ca.ca_cert_path, dest)
+        click.echo(click.style(f"[+] Successfully exported CA to: {dest}", fg="green", bold=True))
+
+
+@main.command(name="test")
+@click.option(
+    "--profile",
+    default="chrome_133",
+    help="Browser profile to test against tls.peet.ws.",
+)
+def test_handshake(profile: str) -> None:
+    """Performs a direct live handshake against tls.peet.ws to inspect upstream JA4."""
+    import json
+
+    prof = normalize_profile(profile)
+    click.echo(render_banner())
+    click.echo(f"[*] Testing upstream TLS handshake with profile: {click.style(prof, fg='yellow', bold=True)}...")
+
+    async def _test():
+        engine = NativeEngine.get_instance()
+        res = await engine.request(
+            method="GET",
+            url="https://tls.peet.ws/api/all",
+            profile=prof,
+            timeout_seconds=15,
+        )
+        return res
+
+    try:
+        res = asyncio.run(_test())
+        sep = click.style("-" * 72, fg="bright_black")
+        click.echo(sep)
+        status_color = "green" if res["status"] == 200 else "red"
+        click.echo(f" {click.style('Status Code:', fg='bright_white', bold=True)}        {click.style(str(res['status']), fg=status_color, bold=True)}")
+        click.echo(f" {click.style('Negotiated Protocol:', fg='bright_white', bold=True)} {click.style(res['protocol'], fg='cyan')}")
+
+        body = json.loads(res["body"].decode("utf-8", errors="replace"))
+        tls_info = body.get("tls", {})
+        click.echo(f" {click.style('Remote Peer JA4:', fg='bright_white', bold=True)}     {click.style(str(tls_info.get('ja4')), fg='yellow', bold=True)}")
+        click.echo(f" {click.style('Remote Peer JA3:', fg='bright_white', bold=True)}     {tls_info.get('ja3')}")
+        click.echo(f" {click.style('HTTP Version:', fg='bright_white', bold=True)}        {body.get('http_version')}")
+        click.echo(sep)
+    except Exception as e:
+        click.echo(click.style(f"Error executing test: {e}", fg="red", bold=True), err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/ja4proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ja4proxy
-Version: 0.3.0
+Version: 0.4.0
 Summary: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation
 Author-email: cipherwire <dev@cipherwire.link>
 License-Expression: MIT

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/ja4proxy.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ ja4proxy.egg-info/top_level.txt
 ja4proxy/engine/bridge.py
 ja4proxy/engine/loader.py
 tests/test_certs.py
+tests/test_cli.py
 tests/test_engine.py
 tests/test_live_proxy.py
 tests/test_parser.py

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ja4proxy"
-version = "0.3.0"
+version = "0.4.0"
 description = "High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation"
 readme = "README.md"
 authors = [{ name = "cipherwire", email = "dev@cipherwire.link" }]

ja4proxy-0.4.0/tests/test_cli.py

@@ -0,0 +1,40 @@
+import unittest
+from click.testing import CliRunner
+
+from ja4proxy import __version__
+from ja4proxy.cli import main
+
+
+class TestCLI(unittest.TestCase):
+    def setUp(self):
+        self.runner = CliRunner()
+
+    def test_cli_help_displays_banner_and_version(self):
+        result = self.runner.invoke(main, ["--help"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Universal Browser TLS & JA4 Impersonation Proxy", result.output)
+        self.assertIn(__version__, result.output)
+        self.assertIn("https://ja4proxy.cipherwire.link", result.output)
+        self.assertIn("start", result.output)
+        self.assertIn("profiles", result.output)
+        self.assertIn("ca", result.output)
+
+    def test_cli_version_flag(self):
+        result = self.runner.invoke(main, ["--version"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn(f"ja4proxy, version {__version__}", result.output)
+
+    def test_cli_profiles_command(self):
+        result = self.runner.invoke(main, ["profiles"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Available Browser Profiles", result.output)
+        self.assertIn("chrome_133 (Default)", result.output)
+        self.assertIn("firefox_133", result.output)
+        self.assertIn("safari_16_0", result.output)
+
+    def test_cli_ca_command(self):
+        result = self.runner.invoke(main, ["ca"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Root CA Certificate:", result.output)
+        self.assertIn("ca.pem", result.output)
+        self.assertIn("Root CA Private Key:", result.output)

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/tests/test_engine.py

@@ -11,14 +11,26 @@ class TestNativeEngine(unittest.TestCase):
 
     def test_live_handshake_chrome(self):
         async def _run():
-            return await self.engine.request(
-                method="GET",
-                url="https://tls.peet.ws/api/all",
-                profile="chrome_133",
-                timeout_seconds=15,
-            )
+            last_res = None
+            for attempt in range(3):
+                try:
+                    res = await self.engine.request(
+                        method="GET",
+                        url="https://tls.peet.ws/api/all",
+                        profile="chrome_133",
+                        timeout_seconds=15,
+                    )
+                    if res.get("status") == 200:
+                        return res
+                    last_res = res
+                except Exception as exc:
+                    last_res = {"status": 0, "body": str(exc).encode()}
+                await asyncio.sleep(1.0 * (attempt + 1))
+            return last_res
 
         res = asyncio.run(_run())
+        if res and res.get("status") in (429, 502, 503, 504):
+            self.skipTest(f"tls.peet.ws rate limit or transient upstream status {res.get('status')}")
         self.assertEqual(res["status"], 200)
         self.assertTrue(len(res["body"]) > 0)
         data = json.loads(res["body"].decode("utf-8"))

{ja4proxy-0.3.0 → ja4proxy-0.4.0}/tests/test_live_proxy.py

@@ -76,6 +76,10 @@ class TestLiveProxy(unittest.IsolatedAsyncioTestCase):
 
         # Read response
         status_line = await reader.readline()
+        if b"502" in status_line or b"429" in status_line or b"503" in status_line:
+            writer.close()
+            await writer.wait_closed()
+            self.skipTest(f"tls.peet.ws public service returned transient error: {status_line.decode('utf-8', errors='replace').strip()}")
         self.assertIn(b"200 OK", status_line)
 
         headers = {}
@@ -115,6 +119,10 @@ class TestLiveProxy(unittest.IsolatedAsyncioTestCase):
         await writer.drain()
 
         status_line = await reader.readline()
+        if b"502" in status_line or b"429" in status_line or b"503" in status_line:
+            writer.close()
+            await writer.wait_closed()
+            self.skipTest(f"tls.peet.ws public service returned transient error: {status_line.decode('utf-8', errors='replace').strip()}")
         self.assertIn(b"200 OK", status_line)
 
         while True:
@@ -226,6 +234,10 @@ class TestLiveProxy(unittest.IsolatedAsyncioTestCase):
         await writer.drain()
 
         status_line = await reader.readline()
+        if b"502" in status_line or b"429" in status_line or b"503" in status_line:
+            writer.close()
+            await writer.wait_closed()
+            self.skipTest(f"tls.peet.ws public service returned transient error: {status_line.decode('utf-8', errors='replace').strip()}")
         self.assertIn(b"200 OK", status_line)
 
         while True:

ja4proxy-0.3.0/ja4proxy/cli.py

@@ -1,161 +0,0 @@
-import asyncio
-import logging
-import os
-import shutil
-import sys
-
-import click
-
-from ja4proxy import __version__
-from ja4proxy.certs import CertificateAuthority
-from ja4proxy.engine.bridge import NativeEngine
-from ja4proxy.profiles import SUPPORTED_PROFILES, normalize_profile
-from ja4proxy.server import ProxyServer
-
-
-@click.group()
-@click.version_option(__version__, prog_name="ja4proxy")
-def main() -> None:
-    """ja4proxy: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation."""
-    pass
-
-
-@main.command()
-@click.option("--host", default="127.0.0.1", help="Binding IP address.")
-@click.option("--port", "-p", default=8888, type=int, help="Port to listen on.")
-@click.option(
-    "--profile",
-    default="chrome_133",
-    help="Default browser profile (e.g. chrome_133, safari_16_0, firefox_133).",
-)
-@click.option(
-    "--upstream-proxy",
-    default=None,
-    help="Default upstream proxy URL (e.g. socks5://user:pass@host:1080).",
-)
-@click.option(
-    "--auth",
-    default=None,
-    help="Require username:password authentication for client connections.",
-)
-@click.option(
-    "--cert-dir", default=None, help="Directory to store CA and leaf certificates."
-)
-@click.option(
-    "--allow-private-networks",
-    is_flag=True,
-    help="Allow forwarding requests to private and loopback IP ranges.",
-)
-@click.option("--verbose", "-v", is_flag=True, help="Enable verbose debug logging.")
-def start(
-    host: str,
-    port: int,
-    profile: str,
-    upstream_proxy: str | None,
-    auth: str | None,
-    cert_dir: str | None,
-    allow_private_networks: bool,
-    verbose: bool,
-) -> None:
-    """Starts the ja4proxy server."""
-    log_level = logging.DEBUG if verbose else logging.INFO
-    logging.basicConfig(
-        level=log_level, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
-    )
-
-    prof = normalize_profile(profile)
-    server = ProxyServer(
-        host=host,
-        port=port,
-        default_profile=prof,
-        cert_dir=cert_dir,
-        allow_private_networks=allow_private_networks,
-        upstream_proxy=upstream_proxy,
-        auth=auth,
-    )
-
-    ca_path = server.ca.ca_cert_path
-    click.echo(
-        f"[*] ja4proxy v{__version__} starting on http://{host}:{port}"
-    )
-    click.echo(f"[*] Default Profile: {prof}")
-    click.echo(f"[*] Protocols Supported: HTTP CONNECT, HTTP Gateway, SOCKS5 (Auto-detect)")
-    click.echo(f"[*] CA Certificate: {ca_path}")
-    click.echo(
-        "[*] Ready for HTTP and SOCKS5 clients (Python requests, Node axios, cURL, etc.)"
-    )
-
-    try:
-        asyncio.run(server.serve_forever())
-    except KeyboardInterrupt:
-        click.echo("\n[*] Shutting down ja4proxy...")
-
-
-@main.command(name="profiles")
-def list_profiles() -> None:
-    """Lists all supported browser profiles for TLS and HTTP/2 emulation."""
-    click.echo("Supported Browser Profiles:")
-    for prof in SUPPORTED_PROFILES:
-        click.echo(f"  - {prof}")
-
-
-@main.command(name="ca")
-@click.option(
-    "--export",
-    "-e",
-    "export_path",
-    default=None,
-    help="Export root CA certificate (ca.pem) to specified path.",
-)
-def manage_ca(export_path: str | None) -> None:
-    """Inspects or exports the local Root CA certificate."""
-    ca = CertificateAuthority()
-    click.echo(f"Root CA Certificate: {ca.ca_cert_path}")
-    click.echo(f"Root CA Private Key: {ca.ca_key_path}")
-
-    if export_path:
-        dest = os.path.abspath(export_path)
-        shutil.copyfile(ca.ca_cert_path, dest)
-        click.echo(f"Exported CA to: {dest}")
-
-
-@main.command(name="test")
-@click.option(
-    "--profile",
-    default="chrome_133",
-    help="Browser profile to test against tls.peet.ws.",
-)
-def test_handshake(profile: str) -> None:
-    """Performs a direct live handshake against tls.peet.ws to inspect upstream JA4."""
-    import json
-
-    prof = normalize_profile(profile)
-    click.echo(f"Testing upstream handshake for profile: {prof}...")
-
-    async def _test():
-        engine = NativeEngine.get_instance()
-        res = await engine.request(
-            method="GET",
-            url="https://tls.peet.ws/api/all",
-            profile=prof,
-            timeout_seconds=15,
-        )
-        return res
-
-    try:
-        res = asyncio.run(_test())
-        click.echo(f"Status Code: {res['status']}")
-        click.echo(f"Negotiated Protocol: {res['protocol']}")
-
-        body = json.loads(res["body"].decode("utf-8", errors="replace"))
-        tls_info = body.get("tls", {})
-        click.echo(f"Remote Peer JA4: {tls_info.get('ja4')}")
-        click.echo(f"Remote Peer JA3: {tls_info.get('ja3')}")
-        click.echo(f"HTTP Version: {body.get('http_version')}")
-    except Exception as e:
-        click.echo(f"Error executing test: {e}", err=True)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()