pybrws 0.1.0__tar.gz

pybrws-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernesto Pérez Costa
+
+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, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybrws-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: pybrws
+Version: 0.1.0
+Summary: An HTTPS client that sends what Firefox 157 and Chrome 155 send over TLS and HTTP/2, and what Firefox 157 sends over HTTP/3
+Author: Ernesto
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/epcosta17/pybrws
+Project-URL: Documentation, https://pybrws.readthedocs.io/
+Project-URL: Source, https://github.com/epcosta17/pybrws
+Project-URL: Issues, https://github.com/epcosta17/pybrws/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=50
+Requires-Dist: hpack
+Requires-Dist: brotli
+Requires-Dist: publicsuffixlist
+Requires-Dist: idna
+Requires-Dist: certifi
+Requires-Dist: zstandard; python_version < "3.14"
+Provides-Extra: client
+Provides-Extra: zstd
+Provides-Extra: http3
+Requires-Dist: aioquic<2,>=1.3; extra == "http3"
+Provides-Extra: measure
+Requires-Dist: httpx[http2]<1,>=0.28; extra == "measure"
+Provides-Extra: docs
+Requires-Dist: zensical<0.2,>=0.1.1; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: aioquic<2,>=1.3; extra == "dev"
+Requires-Dist: httpx[http2]<1,>=0.28; extra == "dev"
+Dynamic: license-file
+
+# pybrws
+
+Python + browser: an HTTPS client that sends what a real browser sends
+
+pybrws is written from scratch in Python. It sends what Firefox 157 and Chrome 155 send on the wire: the TLS ClientHello, the HTTP/2 start and the headers. It also sends Firefox's QUIC hello over HTTP/3. It is a learning and measurement tool that you can install, and it began as a way to see how browsers look on the wire.
+
+It is not a replacement for [curl_cffi](https://pypi.org/project/curl-cffi/). For production use, use curl_cffi. pybrws makes no promise that any site will accept its requests.
+
+## Install
+
+```
+pip install pybrws
+```
+
+Python 3.11 or newer. Two optional extras:
+
+- `pip install "pybrws[http3]"` adds aioquic, for HTTP/3.
+- `pip install "pybrws[measure]"` adds httpx, for the A/B controls of `pybrws ab`.
+
+## Use it from Python
+
+```python
+from pybrws.client import get
+from pybrws.profiles import chrome155
+
+response = get("https://example.com/", profile=chrome155)
+print(response.status, response.header("content-type"))
+print(response.text()[:200])
+```
+
+The default profile is `firefox157`. `post` and `request` work the same way. HTTP/3 is `pybrws.h3.get(url)`, Firefox only.
+
+## Use it from the command line
+
+```
+pybrws https://example.com/
+pybrws verify --local
+```
+
+The first fetches a page like curl. The second compares the default profile's ClientHello with the browser capture shipped in the package, offline, and prints "same string as the capture". Other subcommands: `capture`, `read-quic`, `ja4`, `verify`, `probe`, `ab`, `isolate`, `waf`.
+
+## More
+
+- Documentation: https://pybrws.readthedocs.io/
+- Source: https://github.com/epcosta17/pybrws
+- Licence: [MIT](https://github.com/epcosta17/pybrws/blob/master/LICENSE)

pybrws-0.1.0/README.md

@@ -0,0 +1,46 @@
+# pybrws
+
+Python + browser: an HTTPS client that sends what a real browser sends
+
+pybrws is written from scratch in Python. It sends what Firefox 157 and Chrome 155 send on the wire: the TLS ClientHello, the HTTP/2 start and the headers. It also sends Firefox's QUIC hello over HTTP/3. It is a learning and measurement tool that you can install, and it began as a way to see how browsers look on the wire.
+
+It is not a replacement for [curl_cffi](https://pypi.org/project/curl-cffi/). For production use, use curl_cffi. pybrws makes no promise that any site will accept its requests.
+
+## Install
+
+```
+pip install pybrws
+```
+
+Python 3.11 or newer. Two optional extras:
+
+- `pip install "pybrws[http3]"` adds aioquic, for HTTP/3.
+- `pip install "pybrws[measure]"` adds httpx, for the A/B controls of `pybrws ab`.
+
+## Use it from Python
+
+```python
+from pybrws.client import get
+from pybrws.profiles import chrome155
+
+response = get("https://example.com/", profile=chrome155)
+print(response.status, response.header("content-type"))
+print(response.text()[:200])
+```
+
+The default profile is `firefox157`. `post` and `request` work the same way. HTTP/3 is `pybrws.h3.get(url)`, Firefox only.
+
+## Use it from the command line
+
+```
+pybrws https://example.com/
+pybrws verify --local
+```
+
+The first fetches a page like curl. The second compares the default profile's ClientHello with the browser capture shipped in the package, offline, and prints "same string as the capture". Other subcommands: `capture`, `read-quic`, `ja4`, `verify`, `probe`, `ab`, `isolate`, `waf`.
+
+## More
+
+- Documentation: https://pybrws.readthedocs.io/
+- Source: https://github.com/epcosta17/pybrws
+- Licence: [MIT](https://github.com/epcosta17/pybrws/blob/master/LICENSE)

pybrws-0.1.0/pybrws/__init__.py

@@ -0,0 +1,3 @@
+"""pybrws - a from-scratch browser-fingerprinted TLS client."""
+
+__version__ = "0.1.0"

pybrws-0.1.0/pybrws/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pybrws-0.1.0/pybrws/certs.py

@@ -0,0 +1,275 @@
+"""Certificate handling: parsing, decompression, chain and signature checks.
+
+Path validation is delegated to `cryptography.x509.verification`. Hand-rolling
+it would mean reimplementing name constraints, policy handling and revocation
+semantics, which is the kind of code that is wrong in ways nobody notices
+until it matters.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import ssl
+import warnings
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519, padding, rsa
+from cryptography.x509.verification import PolicyBuilder, Store
+
+from . import hosts
+from .parser import _Reader
+
+# RFC 8879
+COMPRESSION_ZLIB = 1
+COMPRESSION_BROTLI = 2
+COMPRESSION_ZSTD = 3
+
+# The string a TLS 1.3 server signs, RFC 8446 section 4.4.3.
+SIGNATURE_CONTEXT = b" " * 64 + b"TLS 1.3, server CertificateVerify" + b"\x00"
+
+RSA_PSS = {
+    0x0804: hashes.SHA256,
+    0x0805: hashes.SHA384,
+    0x0806: hashes.SHA512,
+}
+ECDSA = {
+    0x0403: hashes.SHA256,
+    0x0503: hashes.SHA384,
+    0x0603: hashes.SHA512,
+}
+RSA_PKCS1 = {
+    0x0401: hashes.SHA256,
+    0x0501: hashes.SHA384,
+    0x0601: hashes.SHA512,
+}
+ED25519 = 0x0807
+
+
+class CertificateError(Exception):
+    pass
+
+
+def decompress_certificate(message: bytes) -> bytes:
+    """Turn an RFC 8879 CompressedCertificate body into a Certificate body.
+
+    The output is bounded by the declared length *while* decompressing.
+    Checking it afterwards would be too late: this message arrives before the
+    server has proved anything, and a kilobyte of brotli can expand to a
+    gigabyte. RFC 8879 section 4 asks for exactly this bound. The declared
+    length is a uint24, so its own ceiling of 2**24 - 1 holds by construction.
+    """
+    reader = _Reader(message, "CompressedCertificate")
+    algorithm = reader.uint(2)
+    expected = reader.uint(3)
+    compressed = reader.vector(3)
+    # One byte past the declared length is enough to know it was a lie.
+    limit = expected + 1
+
+    try:
+        if algorithm == COMPRESSION_ZLIB:
+            import zlib
+
+            plain = zlib.decompressobj().decompress(compressed, limit)
+        elif algorithm == COMPRESSION_BROTLI:
+            import brotli
+
+            # Bounded to within one internal block of the limit, which is
+            # enough: the length check below rejects anything past it.
+            plain = brotli.Decompressor().process(
+                compressed, output_buffer_limit=limit)
+        elif algorithm == COMPRESSION_ZSTD:
+            try:
+                from compression import zstd
+            except ImportError:
+                import io
+
+                import zstandard
+
+                with zstandard.ZstdDecompressor().stream_reader(
+                        io.BytesIO(compressed)) as source:
+                    plain = source.read(limit)
+            else:
+                plain = zstd.ZstdDecompressor().decompress(
+                    compressed, max_length=limit)
+        else:
+            raise CertificateError(
+                "unknown certificate compression " + str(algorithm))
+    except CertificateError:
+        raise
+    except Exception as exc:
+        raise CertificateError(
+            "certificate decompression failed: " + str(exc)) from exc
+
+    if len(plain) != expected:
+        raise CertificateError(
+            "decompressed to %d bytes, the server said %d" % (len(plain), expected)
+        )
+    return plain
+
+
+def parse_certificate(body: bytes) -> list[bytes]:
+    """Return the DER certificates in a Certificate message body, leaf first."""
+    reader = _Reader(body, "Certificate")
+    reader.vector(1)  # certificate_request_context, empty for a server
+    entries = _Reader(reader.vector(3), "certificate_list")
+    chain = []
+    while entries.remaining:
+        chain.append(entries.vector(3))
+        entries.vector(2)  # per-certificate extensions
+    if not chain:
+        raise CertificateError("the server sent an empty certificate list")
+    return chain
+
+
+def _parse_anchors(ders) -> list:
+    anchors = []
+    for der in ders:
+        try:
+            anchors.append(x509.load_der_x509_certificate(der))
+        except Exception:
+            # Bundles carry the occasional malformed anchor. One
+            # unparseable certificate should not cost the other few hundred.
+            continue
+    return anchors
+
+
+def _platform_roots() -> list[bytes]:
+    context = ssl.create_default_context()
+    return list(context.get_ca_certs(binary_form=True))
+
+
+def _mozilla_roots() -> list[bytes]:
+    """The DER of each certificate in the certifi bundle, which is Mozilla's
+    root program. A bundle that cannot be read counts as having none."""
+    import certifi
+
+    try:
+        with open(certifi.where(), encoding="ascii") as bundle:
+            text = bundle.read()
+    except (OSError, UnicodeDecodeError):
+        return []
+    begin, end = "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE-----"
+    ders = []
+    for block in text.split(end)[:-1]:
+        # The bundle puts a comment above each certificate.
+        _, found, body = block.partition(begin)
+        if not found:
+            continue
+        try:
+            ders.append(ssl.PEM_cert_to_DER_cert(begin + body + end + "\n"))
+        except ValueError:
+            continue
+    return ders
+
+
+def system_store() -> Store:
+    """The platform's trust anchors alone, as Python's ssl module sees them.
+
+    Raises:
+        CertificateError: if the platform has none.
+    """
+    warnings.filterwarnings("ignore", message="Parsed a serial number")
+    anchors = _parse_anchors(_platform_roots())
+    if not anchors:
+        raise CertificateError("no trust anchors available from the system store")
+    return Store(anchors)
+
+
+def default_store() -> Store:
+    """The roots a connection is verified against by default: Mozilla's
+    (the certifi bundle) plus whatever the platform adds, an enterprise CA
+    for example. That is close to Firefox's mix: Firefox adds only the roots
+    an administrator or user installed on the system, not the platform's
+    whole root program.
+
+    A certificate that is in both counts once. A source that cannot be read
+    counts as having none.
+
+    Raises:
+        CertificateError: if both sources yield no anchors.
+    """
+    warnings.filterwarnings("ignore", message="Parsed a serial number")
+    seen = set()
+    unique = []
+    for der in _mozilla_roots() + _platform_roots():
+        if der not in seen:
+            seen.add(der)
+            unique.append(der)
+    anchors = _parse_anchors(unique)
+    if not anchors:
+        raise CertificateError("no trust anchors available from certifi or the system store")
+    return Store(anchors)
+
+
+def verify_chain(chain: list[bytes], hostname: str, store: Store | None = None):
+    """Validate the chain for `hostname`, returning the leaf certificate.
+
+    Raises:
+        CertificateError: if the chain does not validate.
+    """
+    certificates = [x509.load_der_x509_certificate(der) for der in chain]
+    leaf, intermediates = certificates[0], certificates[1:]
+    if hosts.is_ip_literal(hostname):
+        # An address is matched against an IP address SAN, never a DNS one.
+        subject = x509.IPAddress(ipaddress.ip_address(hostname.strip("[]")))
+    else:
+        subject = x509.DNSName(hostname)
+    verifier = (
+        PolicyBuilder()
+        .store(store if store is not None else default_store())
+        .build_server_verifier(subject)
+    )
+    try:
+        verifier.verify(leaf, intermediates)
+    except Exception as exc:
+        raise CertificateError("certificate chain rejected: " + str(exc)) from exc
+    return leaf
+
+
+def verify_signature(leaf, scheme: int, signature: bytes, transcript_hash: bytes) -> None:
+    """Check the CertificateVerify signature over the handshake transcript.
+
+    This is what proves the peer holds the key in the certificate, rather
+    than merely having a copy of someone else's chain.
+    """
+    signed = SIGNATURE_CONTEXT + transcript_hash
+    key = leaf.public_key()
+    try:
+        if scheme in RSA_PSS:
+            algorithm = RSA_PSS[scheme]()
+            key.verify(signature, signed,
+                       padding.PSS(mgf=padding.MGF1(algorithm),
+                                   salt_length=algorithm.digest_size),
+                       algorithm)
+        elif scheme in ECDSA:
+            key.verify(signature, signed, ec.ECDSA(ECDSA[scheme]()))
+        elif scheme == ED25519:
+            key.verify(signature, signed)
+        elif scheme in RSA_PKCS1:
+            # Not permitted for TLS 1.3 CertificateVerify, but accepting it
+            # silently would hide a server doing the wrong thing.
+            raise CertificateError(
+                "server signed with rsa_pkcs1, which TLS 1.3 forbids here"
+            )
+        else:
+            raise CertificateError("unsupported signature scheme 0x%04x" % scheme)
+    except InvalidSignature as exc:
+        raise CertificateError("CertificateVerify signature is invalid") from exc
+    except CertificateError:
+        raise
+    except Exception as exc:
+        raise CertificateError("CertificateVerify could not be checked: "
+                               + str(exc)) from exc
+
+
+def expected_key_type(leaf) -> str:
+    key = leaf.public_key()
+    if isinstance(key, rsa.RSAPublicKey):
+        return "rsa"
+    if isinstance(key, ec.EllipticCurvePublicKey):
+        return "ecdsa"
+    if isinstance(key, ed25519.Ed25519PublicKey):
+        return "ed25519"
+    return type(key).__name__