Skip to content

Commit d7ae3e2

Browse files
Crank-GitCrank-Git
committed
docs: clean up README structure and ordering
1 parent 5bd1727 commit d7ae3e2

1 file changed

Lines changed: 51 additions & 86 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
[![Tests](https://github.com/Crank-Git/ja4plus/actions/workflows/test.yml/badge.svg)](https://github.com/Crank-Git/ja4plus/actions/workflows/test.yml)
22
[![PyPI version](https://badge.fury.io/py/ja4plus.svg)](https://pypi.org/project/ja4plus/)
33
[![Python versions](https://img.shields.io/pypi/pyversions/ja4plus.svg)](https://pypi.org/project/ja4plus/)
4+
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
45

56
# JA4+
67

7-
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.
8+
A Python library and CLI 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.
89

910
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).
1011

@@ -27,69 +28,52 @@ JA4+ is a set of network fingerprinting standards created by [FoxIO](https://fox
2728
pip install ja4plus
2829
```
2930

30-
Or install from source:
31+
For fingerprint identification (browsers, malware, C2 frameworks):
3132

3233
```bash
33-
git clone https://github.com/Crank-Git/ja4plus.git
34-
cd ja4plus
35-
pip install -e .
34+
pip install ja4plus[lookup]
3635
```
3736

38-
## Licensing
39-
40-
This library (ja4plus) is released under the **BSD 3-Clause License**.
41-
42-
The JA4+ fingerprinting specifications were created by [FoxIO](https://foxio.io):
43-
44-
- **JA4** (TLS Client Fingerprinting) is open source under **BSD-3-Clause** per FoxIO.
45-
- **JA4S, JA4H, JA4T, JA4TS, JA4L, JA4X, JA4SSH** implement FoxIO's specifications and are subject to the **FoxIO License 1.1**.
46-
47-
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.
48-
49-
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.
37+
## CLI
5038

51-
## CLI Tool
52-
53-
After installing, the `ja4plus` command is available:
39+
The `ja4plus` command is available after installation:
5440

5541
```bash
56-
# Fingerprint a PCAP file
42+
# Analyze a PCAP file
5743
ja4plus analyze capture.pcap
5844

59-
# Output as JSON (for SIEM ingestion)
45+
# JSON output for SIEM ingestion
6046
ja4plus --format json analyze capture.pcap
6147

62-
# Filter to specific fingerprint types
48+
# Only specific fingerprint types
6349
ja4plus --types ja4,ja4t analyze capture.pcap
6450

65-
# Live capture from a network interface (requires root)
51+
# Live capture (requires root)
6652
sudo ja4plus live eth0
6753

68-
# Fingerprint an X.509 certificate
54+
# Fingerprint a certificate
6955
ja4plus cert server.der
7056

71-
# Identify known fingerprints (browsers, malware, C2)
57+
# Identify known fingerprints
7258
ja4plus --lookup analyze capture.pcap
7359
```
7460

75-
### Fingerprint Lookup
76-
77-
ja4plus includes a bundled database of known JA4+ fingerprints from FoxIO's [ja4plus-mapping.csv](https://github.com/FoxIO-LLC/ja4/blob/main/ja4plus-mapping.csv), identifying browsers (Chrome, Firefox, Safari), malware (IcedID, Cobalt Strike, Sliver), and operating systems.
61+
Output formats: `--format table` (default), `json` (JSONL), `csv`
7862

79-
```bash
80-
# Install with lookup support (adds optional requests dependency)
81-
pip install ja4plus[lookup]
63+
## Fingerprint Lookup
8264

83-
# Use in CLI
84-
ja4plus --lookup analyze capture.pcap
65+
ja4plus includes a bundled database of known JA4+ fingerprints from FoxIO's [ja4plus-mapping.csv](https://github.com/FoxIO-LLC/ja4/blob/main/ja4plus-mapping.csv). Identifies Chrome, Firefox, Safari, Python, Cobalt Strike, Sliver, IcedID, and more.
8566

86-
# Use in code
67+
```python
8768
from ja4plus.ja4db import lookup
69+
8870
result = lookup("t13d1516h2_8daaf6152771_02713d6af862")
8971
# {"application": "Chromium Browser", "type": "ja4", "notes": ""}
9072
```
9173

92-
## Quick Start
74+
## Python API
75+
76+
### Quick Start
9377

9478
```python
9579
from scapy.all import rdpcap
@@ -104,38 +88,6 @@ for packet in packets:
10488
print(f"JA4: {result}")
10589
```
10690

107-
## Usage
108-
109-
### Class-Based API
110-
111-
Each fingerprinter processes packets and collects results:
112-
113-
```python
114-
from ja4plus import JA4Fingerprinter, JA4SFingerprinter, JA4TFingerprinter
115-
116-
ja4 = JA4Fingerprinter()
117-
ja4s = JA4SFingerprinter()
118-
ja4t = JA4TFingerprinter()
119-
120-
for packet in packets:
121-
ja4.process_packet(packet)
122-
ja4s.process_packet(packet)
123-
ja4t.process_packet(packet)
124-
125-
for entry in ja4.get_fingerprints():
126-
print(entry["fingerprint"])
127-
```
128-
129-
### Function-Based API
130-
131-
For one-shot fingerprinting of individual packets:
132-
133-
```python
134-
from ja4plus import generate_ja4, generate_ja4s, generate_ja4h
135-
136-
fingerprint = generate_ja4(packet)
137-
```
138-
13991
### All Fingerprinters
14092

14193
```python
@@ -159,26 +111,39 @@ All fingerprinters share a common interface:
159111
| `get_fingerprints()` | Returns list of all collected fingerprint dicts |
160112
| `reset()` | Clears all collected state |
161113

162-
See [`docs/usage.md`](docs/usage.md) for detailed usage of each fingerprinter.
114+
### Function-Based API
115+
116+
For one-shot fingerprinting without maintaining state:
117+
118+
```python
119+
from ja4plus import generate_ja4, generate_ja4s, generate_ja4h
120+
121+
fingerprint = generate_ja4(packet)
122+
```
123+
124+
See [`docs/usage.md`](docs/usage.md) for detailed usage of each fingerprinter and [`docs/api_reference.md`](docs/api_reference.md) for the full API.
163125

164126
## Fingerprint Formats
165127

166128
| Type | Format | Example |
167129
|------|--------|---------|
168-
| JA4 | `{proto}{ver}{sni}{ciphcnt}{extcnt}{alpn}_{hash}_{hash}` | `t13d1516h2_8daaf6152771_e5627efa2ab1` |
169-
| JA4S | `{proto}{ver}{extcnt}{alpn}_{cipher}_{hash}` | `t130200_1301_a56c5b993250` |
170-
| JA4H | `{method}{ver}{cookie}{ref}{cnt}{lang}_{hash}_{hash}_{hash}` | `ge11cr0800_edb4461d7a83_4817af47a558_...` |
130+
| JA4 | `{proto}{ver}{sni}{ciphers}{exts}{alpn}_{hash}_{hash}` | `t13d1516h2_8daaf6152771_e5627efa2ab1` |
131+
| JA4S | `{proto}{ver}{exts}{alpn}_{cipher}_{hash}` | `t130200_1301_a56c5b993250` |
132+
| JA4H | `{method}{ver}{cookie}{ref}{cnt}{lang}_{h}_{h}_{h}` | `ge11cr0800_edb4461d7a83_...` |
171133
| JA4T | `{window}_{options}_{mss}_{wscale}` | `65535_2-4-8-1-3_1460_7` |
172134
| JA4TS | `{window}_{options}_{mss}_{wscale}` | `14600_2-4-8-1-3_1460_0` |
173135
| JA4L | `{latency_us}_{ttl}` | `2500_56` |
174-
| JA4X | `{issuer_hash}_{subject_hash}_{ext_hash}` | `a37f49ba31e2_a37f49ba31e2_dd4f1a0ef8b2` |
136+
| JA4X | `{issuer}_{subject}_{extensions}` | `a37f49ba31e2_a37f49ba31e2_dd4f1a0ef8b2` |
175137
| JA4SSH | `c{mode}s{mode}_c{pkts}s{pkts}_c{acks}s{acks}` | `c36s36_c51s80_c69s0` |
176138

177-
## Requirements
139+
## Spec Validation
178140

179-
- Python 3.8+
180-
- [scapy](https://scapy.net/) >= 2.4.0
181-
- [cryptography](https://cryptography.io/) >= 42.0.0
141+
ja4plus is validated against [FoxIO's official test vectors](https://github.com/FoxIO-LLC/ja4):
142+
143+
```bash
144+
python tests/download_test_vectors.py
145+
pytest -m spec_validation -v
146+
```
182147

183148
## Development
184149

@@ -189,19 +154,19 @@ pip install -e ".[dev]"
189154
pytest tests/ -v
190155
```
191156

192-
## Spec Validation
193-
194-
ja4plus is validated against [FoxIO's official test vectors](https://github.com/FoxIO-LLC/ja4).
195-
Run the validation suite:
157+
### Requirements
196158

197-
```bash
198-
python tests/download_test_vectors.py
199-
pytest -m spec_validation -v
200-
```
159+
- Python 3.8+
160+
- [scapy](https://scapy.net/) >= 2.4.0
161+
- [cryptography](https://cryptography.io/) >= 42.0.0
201162

202163
## License
203164

204-
BSD 3-Clause License. See [LICENSE](LICENSE) for details.
165+
This library is released under the **BSD 3-Clause License**.
166+
167+
The JA4+ fingerprinting specifications were created by [FoxIO](https://foxio.io). JA4 (TLS Client) is open source under BSD-3-Clause per FoxIO. Other JA4+ methods (JA4S, JA4H, JA4T, JA4TS, JA4L, JA4X, JA4SSH) implement FoxIO's specifications under the [FoxIO License 1.1](https://github.com/FoxIO-LLC/ja4/blob/main/LICENSE), which is permissive for academic, internal business, and security research use.
168+
169+
See [LICENSE](LICENSE) for full details.
205170

206171
## Acknowledgments
207172

0 commit comments

Comments
 (0)