JA4 CLI Tool

A TypeScript-based command-line interface for analyzing JA4+ network fingerprints with comprehensive threat intelligence integration.

Features

Multi-format Support: Analyze JA4, JA4S, JA4H, JA4X, and JA4T fingerprints
Database Integration: Automatic lookup against the JA4+ database
Comparison Tools: Compare fingerprints to identify similarities and differences
Batch Processing: Process multiple fingerprints from files
Search Capabilities: Search by application name or operating system
Pretty Output: Beautiful colored terminal output with progress indicators
JSON Export: Machine-readable output for automation

Installation

Prerequisites

Node.js >= 20.0.0
npm or yarn

Installation

To install the CLI globally, run:

npm install -g

Alternatively, you can use the CLI directly without installation:

npx ja4-mcp-server cli [command]

Install Dependencies

npm install
# or
yarn install

Make CLI Executable

chmod +x cli.ts

Usage

Basic Analysis

Analyze a single JA4 fingerprint:

npm run cli analyze "t13d1516h2_8daaf6152771_b0da82dd1658"

Analyze different fingerprint types:

# JA4S (Server)
npm run cli analyze -t ja4s "t13d15h2_002f_0035"

# JA4H (HTTP)
npm run cli analyze -t ja4h "ge11nn05_7a9c_b4a9_ad9e"

# JA4T (TCP)
npm run cli analyze -t ja4t "1460_020405b4_1460_8"

Verbose Analysis

Get detailed breakdown of all components:

npm run cli analyze -v "t13d1516h2_8daaf6152771_b0da82dd1658"

Skip Database Lookup

For faster analysis without database queries:

ja4 analyze --no-db "t13d1516h2_8daaf6152771_b0da82dd1658"

JSON Output

Get machine-readable output:

ja4 analyze -j "t13d1516h2_8daaf6152771_b0da82dd1658"

Compare Fingerprints

Compare two fingerprints to identify differences:

ja4 compare "t13d1516h2_8daaf6152771_b0da82dd1658" "t13d1517h2_8daaf6152771_7128f82b508a"

ja4 compare "t13d1516h2_8daaf6152771_b0da82dd1658" "t13d1516h2_8daaf6152772_b0da82dd1659"

JSON comparison output:

ja4 compare -j "fp1" "fp2"

Search Database

Search by application name:

ja4 search "Chrome"
ja4 search "Firefox"
ja4 search -l 100 "Safari"  # Limit to 100 results

Search by operating system:

ja4 search -t os "Windows"
ja4 search -t os "Linux"

Database Statistics

View database statistics:

ja4 stats

JSON output:

npm run cli stats -j

Batch Processing

Process multiple fingerprints from a file:

Create a file fingerprints.txt:

t13d1516h2_8daaf6152771_b0da82dd1658
t13d1715h2_9daaf6152771_c1da82dd1659
t12d1314h1_5daaf6152771_a2da82dd1660

Process the batch:

ja4 batch fingerprints.txt

Process with options:

# Different fingerprint type
ja4 batch -t ja4s server_fingerprints.txt

# Save to JSON file
ja4 batch -o results.json fingerprints.txt

# Skip database lookups for speed
ja4 batch --no-db fingerprints.txt

Command Reference

`analyze`

Analyze a single JA4+ fingerprint.

Usage: analyze <fingerprint> [options]

Options:

-t, --type <type> - Fingerprint type (ja4, ja4s, ja4h, ja4x, ja4t) [default: ja4]
--no-db - Skip database lookup
-j, --json - Output as JSON
-v, --verbose - Verbose output with detailed breakdown

Examples:

npm run cli analyze "t13d1516h2_8daaf6152771_b0da82dd1658"
npm run cli analyze -t ja4s -v "t13d15h2_002f_0035"
npm run cli analyze -j --no-db "ge11nn05_7a9c_b4a9_ad9e"

`compare`

Compare two JA4+ fingerprints.

Usage: compare <fingerprint1> <fingerprint2> [options]

Options:

-j, --json - Output as JSON

Examples:

npm run cli compare "fp1" "fp2"
npm run cli compare -j "fp1" "fp2"

`search`

Search the JA4+ database.

Usage: search <query> [options]

Options:

-t, --type <type> - Search type (app or os) [default: app]
-l, --limit <number> - Limit results [default: 50]
-j, --json - Output as JSON

Examples:

npm run cli search "Chrome"
npm run cli search -t os "Windows"
npm run cli search -l 100 -j "Firefox"

`stats`

Show database statistics.

Usage: stats [options]

Options:

-j, --json - Output as JSON

Examples:

npm run cli stats
npm run cli stats -j

`batch`

Process multiple fingerprints from a file.

Usage: batch <file> [options]

Options:

-t, --type <type> - Fingerprint type [default: ja4]
-o, --output <file> - Output file (JSON format)
--no-db - Skip database lookups

Examples:

npm run cli batch fingerprints.txt
npm run cli batch -t ja4s -o results.json server_fps.txt
npm run cli batch --no-db large_dataset.txt

Output Examples

Analysis Output (Pretty)

📊 JA4 Analysis
──────────────────────────────────────────────────
Fingerprint: t13d1516h2_8daaf6152771_b0da82dd1658
Format: JA4
Summary: TCP TLS 1.3 connection with SNI present, using HTTP/2

🔍 Breakdown:
  PART_A: t13d1516h2
  PART_B: 8daaf6152771
  PART_C: b0da82dd1658

💡 Use Cases:
  • TLS client fingerprinting
  • Bot detection
  • Security analysis

🗄️  Database Results (3 found):
  1. Google Chrome
     OS: Windows 10
     ✓ Verified
  2. Chromium Browser
     OS: Linux
  3. Edge Browser
     OS: Windows 11
     ✓ Verified

Comparison Output (Pretty)

🔍 Fingerprint Comparison
──────────────────────────────────────────────────
⚠️  Fingerprints differ

Analysis: Fingerprints are similar (67% match) - likely same client type with minor differences

✅ Similarities:
  Part A: t13d1516h2
  Part B: 8daaf6152771

❌ Differences:
  Part C:
    FP1: b0da82dd1658
    FP2: b0da82dd1659
    Note: Different cryptographic hash values indicating different cipher/extension sets

JSON Output

{
  "fingerprint": "t13d1516h2_8daaf6152771_b0da82dd1658",
  "type": "JA4",
  "analysis": {
    "format": "JA4",
    "breakdown": {
      "part_a": {
        "raw": "t13d1516h2",
        "protocol": "TCP",
        "tls_version": "TLS 1.3",
        "sni_presence": "SNI Present",
        "cipher_count": 21,
        "extension_count": 22,
        "alpn": "HTTP/2"
      }
    },
    "human_readable": "TCP TLS 1.3 connection with SNI present, using HTTP/2"
  },
  "database": {
    "count": 3,
    "results": [
      {
        "ja4": "t13d1516h2_8daaf6152771_b0da82dd1658",
        "application": "Google Chrome",
        "os": "Windows 10",
        "verified": true
      }
    ]
  }
}

Development

Build the CLI

npm run build:cli

Run in Development Mode

npm run cli -- analyze "fingerprint"

Add New Commands

Import the Command class from commander
Add your command definition
Implement the action handler
Update this README

Error Handling

The CLI includes comprehensive error handling:

Invalid fingerprint formats
Network connectivity issues
File I/O problems
Malformed data

All errors are displayed with colored output and appropriate exit codes.

Integration

Use with Scripts

# Check exit code
npm run cli analyze "fingerprint" && echo "Success" || echo "Failed"

# Pipe JSON output
npm run cli analyze -j "fingerprint" | jq '.analysis.human_readable'

# Batch processing with custom logic
while read -r fp; do
  npm run cli analyze -j "$fp" >> results.jsonl
done < fingerprints.txt

CI/CD Integration

# GitHub Actions example
- name: Analyze fingerprints
  run: |
    npm install
    npm run cli batch --no-db -o analysis.json fingerprints.txt
    
- name: Upload results
  uses: actions/upload-artifact@v2
  with:
    name: ja4-analysis
    path: analysis.json

Performance Tips

Use --no-db flag for faster analysis when database lookup isn’t needed
Process large batches in chunks to avoid memory issues
Use JSON output for programmatic processing
Cache database locally (happens automatically)

Troubleshooting

Database Download Issues

If database download fails:

# Check network connectivity
curl -I https://ja4db.com/api/download/ja4plus_db.json

# Clear cache and retry
rm -rf ~/.cache/ja4-cli
npm run cli stats

TypeScript Errors

Ensure you have the correct Node.js version:

node --version  # Should be >= 20.0.0
npm install     # Reinstall dependencies

Performance Issues

For large datasets:

# Use smaller batch sizes
split -l 1000 large_dataset.txt batch_
for file in batch_*; do
  npm run cli batch "$file" -o "results_$file.json"
done