Metadata-Version: 2.4
Name: ja4plus
Version: 0.3.0
Summary: JA4+ network fingerprinting library for TLS, TCP, HTTP, SSH, and X.509 analysis
License: BSD-3-Clause AND LicenseRef-FoxIO-1.1
Project-URL: Homepage, https://github.com/Crank-Git/ja4plus
Project-URL: Bug Tracker, https://github.com/Crank-Git/ja4plus/issues
Project-URL: Source Code, https://github.com/Crank-Git/ja4plus
Project-URL: Documentation, https://github.com/Crank-Git/ja4plus/tree/main/docs
Project-URL: JA4+ Specification, https://github.com/FoxIO-LLC/ja4
Keywords: ja4,ja4plus,fingerprinting,tls,tcp,http,ssh,x509,network,security,scapy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scapy>=2.4.0
Requires-Dist: cryptography>=42.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Provides-Extra: lookup
Requires-Dist: requests>=2.20.0; extra == "lookup"
Dynamic: license-file

[![Tests](https://github.com/Crank-Git/ja4plus/actions/workflows/test.yml/badge.svg)](https://github.com/Crank-Git/ja4plus/actions/workflows/test.yml)
[![PyPI version](https://badge.fury.io/py/ja4plus.svg)](https://pypi.org/project/ja4plus/)
[![Python versions](https://img.shields.io/pypi/pyversions/ja4plus.svg)](https://pypi.org/project/ja4plus/)

# JA4+

A Python library for JA4+ network fingerprinting. Implements all eight JA4+ methods for identifying and classifying network traffic based on TLS, TCP, HTTP, SSH, and X.509 characteristics.

JA4+ is a set of network fingerprinting standards created by [FoxIO](https://foxio.io). This library is an independent Python implementation of the published specification. For the original spec, see the [FoxIO JA4+ repository](https://github.com/FoxIO-LLC/ja4).

## Supported Fingerprint Types

| Type | Protocol | Description |
|------|----------|-------------|
| JA4 | TLS | Client fingerprint from ClientHello messages |
| JA4S | TLS | Server fingerprint from ServerHello messages |
| JA4H | HTTP | Client fingerprint from request headers and cookies |
| JA4T | TCP | Client OS fingerprint from SYN packets |
| JA4TS | TCP | Server fingerprint from SYN-ACK packets |
| JA4L | TCP | Light distance and latency estimation |
| JA4X | X.509 | Certificate structure fingerprint from OID sequences |
| JA4SSH | SSH | Session type classification from traffic patterns |

## Installation

```bash
pip install ja4plus
```

Or install from source:

```bash
git clone https://github.com/Crank-Git/ja4plus.git
cd ja4plus
pip install -e .
```

## Licensing

This library (ja4plus) is released under the **BSD 3-Clause License**.

The JA4+ fingerprinting specifications were created by [FoxIO](https://foxio.io):

- **JA4** (TLS Client Fingerprinting) is open source under **BSD-3-Clause** per FoxIO.
- **JA4S, JA4H, JA4T, JA4TS, JA4L, JA4X, JA4SSH** implement FoxIO's specifications and are subject to the **FoxIO License 1.1**.

The FoxIO License 1.1 is permissive for most use cases, including academic use, internal business use, and security research. Commercial productization or resale of these fingerprinting methods (other than JA4) may require a separate license from FoxIO.

See the [FoxIO License](https://github.com/FoxIO-LLC/ja4/blob/main/LICENSE) for full terms, and [LICENSE](LICENSE) in this repository for the complete dual-license notice.

## Quick Start

```python
from scapy.all import rdpcap
from ja4plus import JA4Fingerprinter

packets = rdpcap("capture.pcap")

fp = JA4Fingerprinter()
for packet in packets:
    result = fp.process_packet(packet)
    if result:
        print(f"JA4: {result}")
```

## Usage

### Class-Based API

Each fingerprinter processes packets and collects results:

```python
from ja4plus import JA4Fingerprinter, JA4SFingerprinter, JA4TFingerprinter

ja4 = JA4Fingerprinter()
ja4s = JA4SFingerprinter()
ja4t = JA4TFingerprinter()

for packet in packets:
    ja4.process_packet(packet)
    ja4s.process_packet(packet)
    ja4t.process_packet(packet)

for entry in ja4.get_fingerprints():
    print(entry["fingerprint"])
```

### Function-Based API

For one-shot fingerprinting of individual packets:

```python
from ja4plus import generate_ja4, generate_ja4s, generate_ja4h

fingerprint = generate_ja4(packet)
```

### All Fingerprinters

```python
from ja4plus import (
    JA4Fingerprinter,      # TLS Client
    JA4SFingerprinter,     # TLS Server
    JA4HFingerprinter,     # HTTP
    JA4TFingerprinter,     # TCP Client (SYN)
    JA4TSFingerprinter,    # TCP Server (SYN-ACK)
    JA4LFingerprinter,     # Latency
    JA4XFingerprinter,     # X.509 Certificate
    JA4SSHFingerprinter,   # SSH
)
```

All fingerprinters share a common interface:

| Method | Description |
|--------|-------------|
| `process_packet(pkt)` | Process a packet, returns fingerprint string or `None` |
| `get_fingerprints()` | Returns list of all collected fingerprint dicts |
| `reset()` | Clears all collected state |

See [`docs/usage.md`](docs/usage.md) for detailed usage of each fingerprinter.

## Fingerprint Formats

| Type | Format | Example |
|------|--------|---------|
| JA4 | `{proto}{ver}{sni}{ciphcnt}{extcnt}{alpn}_{hash}_{hash}` | `t13d1516h2_8daaf6152771_e5627efa2ab1` |
| JA4S | `{proto}{ver}{extcnt}{alpn}_{cipher}_{hash}` | `t130200_1301_a56c5b993250` |
| JA4H | `{method}{ver}{cookie}{ref}{cnt}{lang}_{hash}_{hash}_{hash}` | `ge11cr0800_edb4461d7a83_4817af47a558_...` |
| JA4T | `{window}_{options}_{mss}_{wscale}` | `65535_2-4-8-1-3_1460_7` |
| JA4TS | `{window}_{options}_{mss}_{wscale}` | `14600_2-4-8-1-3_1460_0` |
| JA4L | `{latency_us}_{ttl}` | `2500_56` |
| JA4X | `{issuer_hash}_{subject_hash}_{ext_hash}` | `a37f49ba31e2_a37f49ba31e2_dd4f1a0ef8b2` |
| JA4SSH | `c{mode}s{mode}_c{pkts}s{pkts}_c{acks}s{acks}` | `c36s36_c51s80_c69s0` |

## Requirements

- Python 3.8+
- [scapy](https://scapy.net/) >= 2.4.0
- [cryptography](https://cryptography.io/) >= 3.4.0

## Development

```bash
git clone https://github.com/Crank-Git/ja4plus.git
cd ja4plus
pip install -e ".[dev]"
pytest tests/ -v
```

## Spec Validation

ja4plus is validated against [FoxIO's official test vectors](https://github.com/FoxIO-LLC/ja4).
Run the validation suite:

```bash
python tests/download_test_vectors.py
pytest -m spec_validation -v
```

## License

BSD 3-Clause License. See [LICENSE](LICENSE) for details.

## Acknowledgments

JA4+ was created by John Althouse at [FoxIO](https://foxio.io). This library is an independent implementation of the published specification. For the original spec and reference implementation, see [github.com/FoxIO-LLC/ja4](https://github.com/FoxIO-LLC/ja4).
