NepTLS

NepTLS is a dependency-light Python HTTP client and TLS research toolkit. It combines a requests-style API with structured TLS configuration, browser network profiles, local fingerprint analysis, diagnostics, pools, compression, authentication hooks, hashing/encoding utilities, and a generic proof-of-work framework.

Developed by Diwas Khatri (@diwaskhatri07).

Security boundary

NepTLS is for networking research, browser compatibility, API testing, protocol interoperability, performance testing, debugging, authorized automation, and defensive security research. It is not designed to bypass CAPTCHAs, authentication, payment security, access controls, or anti-abuse systems, and it does not include session theft or credential attack features. Fingerprint objects describe and compare configurations; they do not spoof browser security signals.

Installation

python -m pip install neptls

NepTLS has no runtime dependencies and supports Python 3.10+.

Quick start

import neptls

response = neptls.get("https://example.com", timeout=10)
response.raise_for_status()
print(response.status_code)
print(response.text[:80])

Reusable clients retain cookies and configuration:

client = neptls.Client(
    profile="chrome",
    headers={"X-Research-Client": "neptls"},
    retries=2,
)

response = client.post("https://httpbin.org/post", json={"hello": "world"})
print(response.json())

Client requests automatically advertise and decode gzip and deflate responses. Use stream=True for incremental response reads:

with neptls.get("https://example.com/large-file", stream=True) as response:
    for chunk in response.iter_bytes(64 * 1024):
        process(chunk)

Authentication hooks are explicit and reusable:

from neptls import BasicAuth, BearerAuth

client.get(url, auth=BasicAuth("username", "password"))
client.get(url, auth=BearerAuth("token"))

Malformed or transient HTTP transport errors are normalized to neptls.RequestError. Set retries=2 or another value to retry temporary network failures and 429/5xx responses.

Async calls use the same public API:

import asyncio
from neptls import AsyncClient

async def main():
    async with AsyncClient(timeout=10) as client:
        response = await client.get("https://example.com")
        print(response.status_code)

asyncio.run(main())

TLS and profiles

TLSConfig creates standard-library ssl.SSLContext objects and can be serialized for experiments:

from neptls import TLSConfig, TLSFingerprint

config = TLSConfig(minimum_version="TLSv1.2", alpn_protocols=("h2", "http/1.1"))
print(config.to_json())
print(TLSFingerprint.from_config(config).digest)
print(TLSFingerprint.from_config(config).ja3_hash)

Profiles are structured metadata, not browser impersonation:

client = neptls.Client(profile="firefox")
print(client.fingerprint().to_dict())
print(neptls.profiles.get_profile("chrome").to_json())

For a real, verified TLS handshake against a host:

fingerprint = neptls.probe_tls("example.com")
print(fingerprint.version, fingerprint.cipher, fingerprint.alpn)
print(fingerprint.metadata["source"])

Client.fingerprint() describes the configured profile. probe_tls() reports properties negotiated with a real endpoint. They are intentionally different: the standard-library transport does not claim to reproduce a browser's private ClientHello byte-for-byte.

Fingerprints and user agents

profile = neptls.fingerprint.generate(browser="chrome", platform="windows", seed=7)
print(profile.validate().to_json())
print(neptls.ua.chrome())
print(neptls.user_agents.parse(neptls.ua.random()))

The built-in catalog includes common desktop and mobile Chrome, Firefox, Edge, Safari, and bot strings. It is intentionally curated. Load a properly licensed dataset into UserAgentDatabase when your application needs a larger pool; NepTLS does not bundle a copied 40,000-entry third-party list.

Diagnostics

inspect() performs read-only DNS, TCP, TLS, and HTTP observations:

report = neptls.inspect("https://example.com")
print(report["tls"]["version"])

Pools, proxies, hashing, and generic PoW

from neptls import Proxy
from neptls.crypto import sha256
from neptls.pools import Pool
from neptls.pow import Challenge, benchmark, solve, solve_parallel

pool = Pool(["profile-a", "profile-b"])
print(pool.next())
client = neptls.Client(proxy="http://127.0.0.1:8080")
print(sha256("protocol message"))
result = solve_parallel(Challenge("demo", difficulty=3, algorithm="sha512"), workers=2)
print(benchmark(Challenge("demo", algorithm="sha256"), attempts=1000))

The PoW implementation supports hashlib algorithms such as SHA-256, SHA-512, SHA-1, BLAKE2, and MD5 for legacy protocol research. It is generic and intentionally not tied to any anti-abuse or security system.

Hashing and encoding

All helpers use the standard library:

from neptls.crypto import (
    base32decode, base32encode, digest, hash_file, json_decode,
    json_encode, urlsafe_b64decode, urlsafe_b64encode,
)

print(digest("message", "sha3_256"))
print(hash_file("payload.bin", "sha256"))
token = urlsafe_b64encode("hello")
assert urlsafe_b64decode(token) == b"hello"
assert base32decode(base32encode("hello")) == b"hello"
payload = json_decode(json_encode({"ready": True}))

hash_file() reads incrementally, so large files do not need to fit in memory.

CLI

neptls version
neptls get https://example.com
neptls inspect https://example.com
neptls profile chrome
neptls ua mobile
neptls hash "protocol message" --algorithm sha256
neptls pow demo --difficulty 3

Compatibility and transport boundaries

NepTLS 0.2.0 provides a reliable, dependency-free HTTP/1.1 transport with TLS configuration, ALPN advertisement, cookies, redirects, retries, compression, and diagnostics. It does not pretend that urllib can provide curl-cffi's native HTTP/2/HTTP/3 stack or byte-identical browser TLS impersonation. Native HTTP/2 and HTTP/3 transports can be added as optional, tested backends without changing the public API.

Do not use a profile, user-agent, or fingerprint description to misrepresent identity or evade a security control. Keep use limited to systems you own or are authorized to test.

Development

PYTHONPATH=src python -m unittest discover -s tests -v
python -m compileall -q src
python -m build --sdist --wheel

The project is organized into focused modules for HTTP transport, TLS models, profiles, fingerprints, user agents, pools, proxy data, diagnostics, crypto, PoW, and the CLI. The attached Windows troubleshooting results and the latest automated counts are maintained in TEST_REPORT.md.

License and credits

NepTLS is released under the MIT License. See LICENSE.