ja4plus 0.2.0__tar.gz → 0.3.0__tar.gz

ja4plus-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ja4plus-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short --junitxml=test-results.xml
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: test-results.xml

ja4plus-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+# Downloaded FoxIO test vectors (not committed)
+tests/foxio_vectors/
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.omc/
+.claude/
+.gstack/

{ja4plus-0.2.0 → ja4plus-0.3.0}/LICENSE

@@ -26,3 +26,31 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+DUAL-LICENSE NOTICE
+===================
+
+This repository has a dual-license structure:
+
+1. The ja4plus library code (this repository) is licensed under the
+   BSD 3-Clause License above.
+
+2. The JA4+ fingerprinting specifications themselves were created by
+   FoxIO-LLC. The fingerprinting methods JA4S, JA4H, JA4T, JA4TS, JA4L,
+   JA4X, and JA4SSH are implementations of those specifications and are
+   subject to the FoxIO License 1.1.
+
+   JA4 (TLS Client Fingerprinting) is open source under BSD-3-Clause
+   per FoxIO's own licensing terms.
+
+   The FoxIO License 1.1 is permissive for most use cases, including:
+   - Academic and research use
+   - Internal business use
+   - Security research and tooling
+
+   Commercial productization or resale of JA4+ fingerprinting (other than
+   JA4 itself) may require a separate commercial license from FoxIO.
+
+   Full terms: https://github.com/FoxIO-LLC/ja4/blob/main/LICENSE

{ja4plus-0.2.0/ja4plus.egg-info → ja4plus-0.3.0}/PKG-INFO

@@ -1,9 +1,8 @@
 Metadata-Version: 2.4
 Name: ja4plus
-Version: 0.2.0
+Version: 0.3.0
 Summary: JA4+ network fingerprinting library for TLS, TCP, HTTP, SSH, and X.509 analysis
-Home-page: https://github.com/Crank-Git/ja4plus
-License-Expression: BSD-3-Clause
+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
@@ -28,13 +27,17 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: scapy>=2.4.0
-Requires-Dist: cryptography>=3.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"
-Dynamic: home-page
+Provides-Extra: lookup
+Requires-Dist: requests>=2.20.0; extra == "lookup"
 Dynamic: license-file
-Dynamic: requires-python
+
+[![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+
 
@@ -69,6 +72,19 @@ 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
@@ -169,6 +185,16 @@ 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.

{ja4plus-0.2.0 → ja4plus-0.3.0}/README.md

@@ -1,3 +1,7 @@
+[![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.
@@ -31,6 +35,19 @@ 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
@@ -131,6 +148,16 @@ 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.

ja4plus-0.3.0/docs/README.md

@@ -0,0 +1,19 @@
+# JA4+ Documentation
+
+## Contents
+
+- [Usage Guide](usage.md) - Detailed usage for each fingerprinter with examples
+- [API Reference](api_reference.md) - Classes, methods, and convenience functions
+
+## Quick Links
+
+- [JA4 - TLS Client](usage.md#ja4---tls-client)
+- [JA4S - TLS Server](usage.md#ja4s---tls-server)
+- [JA4H - HTTP](usage.md#ja4h---http)
+- [JA4T - TCP Client](usage.md#ja4t---tcp-client)
+- [JA4TS - TCP Server](usage.md#ja4ts---tcp-server)
+- [JA4L - Latency](usage.md#ja4l---latency)
+- [JA4X - X.509 Certificate](usage.md#ja4x---x509-certificate)
+- [JA4SSH - SSH](usage.md#ja4ssh---ssh)
+- [PCAP Analysis](usage.md#pcap-analysis)
+- [Live Capture](usage.md#live-capture)

ja4plus-0.3.0/docs/api_reference.md

@@ -0,0 +1,171 @@
+# API Reference
+
+## Fingerprinter Classes
+
+All fingerprinters inherit from `BaseFingerprinter` and share a common interface.
+
+### Common Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `process_packet(packet)` | `str` or `None` | Process a scapy packet. Returns fingerprint string if one is generated. |
+| `get_fingerprints()` | `list[dict]` | Returns all collected fingerprints as `{"fingerprint": str, ...}` dicts. |
+| `reset()` | `None` | Clears all collected fingerprints and internal state. |
+
+### JA4Fingerprinter
+
+TLS Client Hello fingerprinting.
+
+```python
+from ja4plus import JA4Fingerprinter
+
+fp = JA4Fingerprinter()
+result = fp.process_packet(packet)        # Returns JA4 string or None
+raw = fp.get_raw_fingerprint(packet)      # Returns unhashed fingerprint
+```
+
+### JA4SFingerprinter
+
+TLS Server Hello fingerprinting.
+
+```python
+from ja4plus import JA4SFingerprinter
+
+fp = JA4SFingerprinter()
+result = fp.process_packet(packet)
+```
+
+### JA4HFingerprinter
+
+HTTP request fingerprinting.
+
+```python
+from ja4plus import JA4HFingerprinter
+
+fp = JA4HFingerprinter()
+result = fp.process_packet(packet)
+```
+
+### JA4TFingerprinter
+
+TCP client fingerprinting from SYN packets.
+
+```python
+from ja4plus import JA4TFingerprinter
+
+fp = JA4TFingerprinter()
+result = fp.process_packet(packet)
+```
+
+### JA4TSFingerprinter
+
+TCP server fingerprinting from SYN-ACK packets.
+
+```python
+from ja4plus import JA4TSFingerprinter
+
+fp = JA4TSFingerprinter()
+result = fp.process_packet(packet)
+```
+
+### JA4LFingerprinter
+
+Network latency estimation from TCP handshake timing.
+
+```python
+from ja4plus import JA4LFingerprinter
+
+fp = JA4LFingerprinter()
+result = fp.process_packet(packet)
+```
+
+### JA4XFingerprinter
+
+X.509 certificate structure fingerprinting.
+
+```python
+from ja4plus import JA4XFingerprinter
+
+fp = JA4XFingerprinter()
+result = fp.fingerprint_certificate(der_bytes)  # From DER-encoded cert
+result = fp.process_packet(packet)               # From TLS packet
+details = fp.get_cert_details(x509_cert)         # Extract OID details
+```
+
+### JA4SSHFingerprinter
+
+SSH session classification.
+
+```python
+from ja4plus import JA4SSHFingerprinter
+
+fp = JA4SSHFingerprinter(packet_count=200)
+result = fp.process_packet(packet)
+info = fp.interpret_fingerprint(result)          # Session type analysis
+hassh = fp.get_hassh_fingerprints()              # HASSH fingerprints
+lookup = fp.lookup_hassh(hassh_value)            # Known HASSH lookup
+```
+
+## Convenience Functions
+
+One-shot fingerprinting without maintaining state:
+
+```python
+from ja4plus import (
+    generate_ja4,
+    generate_ja4s,
+    generate_ja4h,
+    generate_ja4t,
+    generate_ja4ts,
+    generate_ja4l,
+    generate_ja4x,
+    generate_ja4ssh,
+)
+
+# Each takes a scapy packet and returns a fingerprint string or None
+result = generate_ja4(packet)
+```
+
+| Function | Input | Description |
+|----------|-------|-------------|
+| `generate_ja4(packet)` | scapy packet | JA4 TLS client fingerprint |
+| `generate_ja4s(packet)` | scapy packet | JA4S TLS server fingerprint |
+| `generate_ja4h(packet)` | scapy packet | JA4H HTTP fingerprint |
+| `generate_ja4t(packet)` | scapy packet | JA4T TCP client fingerprint |
+| `generate_ja4ts(packet)` | scapy packet | JA4TS TCP server fingerprint |
+| `generate_ja4l(packet)` | scapy packet | JA4L latency fingerprint |
+| `generate_ja4x(cert_info)` | dict | JA4X certificate fingerprint (takes cert_info dict) |
+| `generate_ja4ssh(packet)` | scapy packet | JA4SSH session fingerprint |
+
+## Utility Modules
+
+### ja4plus.utils.tls_utils
+
+| Function | Description |
+|----------|-------------|
+| `extract_tls_info(packet)` | Extract TLS handshake details from a packet |
+| `is_grease_value(value)` | Check if a value is a GREASE value |
+| `parse_client_hello(data)` | Parse raw ClientHello bytes |
+| `parse_server_hello(data)` | Parse raw ServerHello bytes |
+
+### ja4plus.utils.http_utils
+
+| Function | Description |
+|----------|-------------|
+| `extract_http_info(packet)` | Extract HTTP request details from a packet |
+| `is_http_request(data)` | Check if data is an HTTP request |
+| `parse_http_request(data)` | Parse raw HTTP request bytes |
+
+### ja4plus.utils.ssh_utils
+
+| Function | Description |
+|----------|-------------|
+| `is_ssh_packet(data)` | Check if data is SSH traffic |
+| `parse_ssh_packet(data)` | Parse SSH packet structure |
+| `extract_hassh(data)` | Extract HASSH fingerprint from KEXINIT |
+
+### ja4plus.utils.x509_utils
+
+| Function | Description |
+|----------|-------------|
+| `oid_to_hex(oid_string)` | Convert OID dotted string to ASN.1 hex encoding |