JA4+ MCP Server

A Model Context Protocol (MCP) server that provides comprehensive analysis of JA4+ network fingerprints. This server helps security analysts and threat hunters gain actionable insights from JA4, JA4S, JA4H, and JA4X fingerprints with human-readable explanations, pattern detection, and threat intelligence integration.

Features

Comprehensive Fingerprint Analysis: Detailed breakdown of JA4, JA4S, JA4H, and JA4X fingerprints
Pattern Detection: Identify similarities, outliers, and groupings across multiple fingerprints
JA4DB Integration: Automatic lookup against the community-maintained ja4db.com database
MCP Resources: Direct access to fingerprint databases and reference documentation
Investigation Guidance: Actionable recommendations and threat indicators for incident response
Auto-updating Database: Daily refresh of fingerprint intelligence from ja4db.com
Human-Readable Output: Technical but accessible explanations for all components
Analyst Prompts: Built-in MCP prompts to guide AI assistants in effective JA4+ analysis
Command Line Interface: Standalone CLI tool for local JA4+ analysis

What is JA4+?

JA4+ is a suite of network fingerprinting methods created by FoxIO that are both human and machine-readable. Unlike its predecessor JA3, JA4+ uses a modular a_b_c format that allows for:

Command Line Interface

The project also includes a standalone command-line interface (CLI) tool for analyzing JA4+ fingerprints locally:

# Install the CLI globally
npm install -g

# Analyze a JA4 fingerprint
ja4 analyze t13d1517h2_8daaf6152771_7128f82b508a

# Compare two fingerprints
ja4 compare t13d1517h2_8daaf6152771_7128f82b508a t13d1516h2_8daaf6152771_7128f82b508a

# Search the JA4 database
ja4 search "Chrome"

# Analyze multiple fingerprints from a file
ja4 batch fingerprints.txt

# Show database statistics
ja4 stats

For more information about the CLI commands and options, run:

ja4 --help
ja4 analyze --help
ja4 compare --help
ja4 search --help
ja4 batch --help
ja4 stats --help

Locality-preserving analysis: Hunt on specific parts (e.g., JA4_ac to track actors who vary only cipher selection)
Resistant to evasion: Sorted ciphers and extensions prevent simple randomization attacks
Multi-protocol support: TLS (TCP/QUIC), HTTP, SSH, X.509 certificates
Enhanced context: Includes ALPN, signature algorithms, and more metadata

JA4 Format Example

t13d1516h2_8daaf6152771_02713d6af862
│││││││││  │            │
│││││││││  │            └─ Part C: Hash of extensions + signature algorithms
│││││││││  └────────────── Part B: Hash of sorted cipher suites
│││││││││
││││││││└─ ALPN: h2 (HTTP/2)
││││││└─── Extension count: 16
││││└───── Cipher count: 15
│││└─────── SNI: d (domain)
││└──────── TLS version: 13 (1.3)
│└───────── Protocol: t (TCP)

Installation

# Clone or create the server directory
mkdir ja4-mcp-server
cd ja4-mcp-server

# Install dependencies
npm install

# Make executable
chmod +x index.js

Configuration

Add the server to your MCP settings file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ja4-analysis": {
      "command": "node",
      "args": ["/path/to/ja4-mcp-server/index.js"]
    }
  }
}

Or for global installation:

npm install -g .

# Then in config:
{
  "mcpServers": {
    "ja4-analysis": {
      "command": "ja4-mcp-server"
    }
  }
}

Testing

Test the resources functionality:

# Run the resource test script
node test-resources.js

This will verify:

Resource listing works correctly
Database resources return valid JSON
Documentation resources provide reference data
Error handling for invalid resources
Resource annotations are properly set

Available Prompts

analyst-guidance

Load this prompt when starting a new analysis session to provide the AI assistant with comprehensive guidance on JA4+ fingerprint analysis, threat hunting patterns, and investigation workflows.

Usage:

{
  "name": "analyst-guidance"
}

This prompt provides:

Core JA4+ fingerprint knowledge and security indicators
Structured analysis workflows using available MCP tools
Threat hunting patterns for malware, C2, and campaign detection
Database interpretation guidelines
Response framework for actionable intelligence

Available Tools

1. analyze_ja4

Analyze a JA4 (TLS Client) fingerprint with detailed breakdown.

Example Usage:

{
  "fingerprint": "t13d1516h2_8daaf6152771_02713d6af862",
  "include_database_lookup": true
}

Returns:

Protocol details (TCP/QUIC)
TLS version and security assessment
SNI presence (domain vs. IP)
Cipher and extension counts
ALPN (application protocol negotiation)
Human-readable explanation
Database matches from ja4db.com

2. analyze_ja4s

Analyze a JA4S (TLS Server Response) fingerprint.

Example Usage:

{
  "fingerprint": "t130200_1301_a56c5b993250",
  "include_database_lookup": true
}

Returns:

Server protocol and TLS version
Selected cipher suite
Server extensions
Database matches

3. analyze_ja4h

Analyze a JA4H (HTTP Client) fingerprint.

Example Usage:

{
  "fingerprint": "ge11cn020000_9ed1ff1f7b03_cd8dafe26982_ab12cd34ef56",
  "include_database_lookup": true
}

Returns:

HTTP method and version
Cookie and referer presence
Header analysis
Use cases (bot detection, user tracking, etc.)

4. analyze_ja4x

Analyze a JA4X (X.509 Certificate) fingerprint.

Example Usage:

{
  "fingerprint": "2166164053c1_2166164053c1_30d204a01551",
  "include_database_lookup": true
}

Returns:

Issuer fingerprint (CA identification)
Subject fingerprint (certificate owner)
Extension fingerprint
Threat actor tracking use cases

5. compare_fingerprints

Compare two fingerprints to identify similarities and differences.

Example Usage:

{
  "fingerprint1": "t13d1516h2_8daaf6152771_02713d6af862",
  "fingerprint2": "t13d1516h2_9dc949149365_02713d6af862"
}

Use Cases:

Track related malware variants
Identify client family relationships
Detect fingerprint evasion attempts
Group similar threat actors

6. detect_patterns

Analyze multiple fingerprints to detect patterns and outliers.

Example Usage:

{
  "fingerprints": [
    "t13d1516h2_8daaf6152771_02713d6af862",
    "t13d1516h2_8daaf6152771_b0da82dd1658",
    "t13d1517h2_8daaf6152771_b1ff8ab2d16f",
    "q13d0312h3_55b375c5d22e_06cda9e17597"
  ]
}

Returns:

Common protocol configurations
Cipher suite groupings
Outlier identification
Campaign clustering

7. search_database

Search the JA4DB community database.

Example Usage:

{
  "query": "Chrome",
  "search_type": "application",
  "limit": 10
}

Search Types:

application: Search by application name
os: Search by operating system
all: Search across all fields

8. get_investigation_tips

Generate investigation recommendations for a fingerprint.

Example Usage:

{
  "fingerprint": "t10d1516h2_8daaf6152771_02713d6af862",
  "fingerprint_type": "ja4"
}

Returns:

Threat indicators (severity, findings, recommendations)
Investigation steps
Known application context
Correlation suggestions

9. database_stats

Get statistics about the JA4DB database.

Returns:

Total records
Fingerprint type counts
Verified entries
Unique applications and OS
Last update timestamp

10. refresh_database

Force refresh of the database from ja4db.com.

Use Case: Call after significant threat events to get latest intelligence

Practical Use Cases

1. Malware Detection

Scenario: Detect IcedID malware
JA4: t13d201100_2b729b4bf6f3_9e7b989ebec8
JA4S: t120300_c030_5e2616a54c73

Use analyze_ja4 + analyze_ja4s in combination for high-fidelity detection

2. Threat Actor Tracking

Scenario: Track changing cipher tactics
Multiple fingerprints with same a_c, varying b component

Use detect_patterns to identify campaigns even as tactics evolve

3. Bot Detection

Scenario: Identify automated clients
JA4H with missing ALPN, unusual header patterns

Use analyze_ja4h to fingerprint bots vs. legitimate browsers

4. C2 Infrastructure

Scenario: Track malware command & control
JA4X fingerprints identify self-signed or reused certificates

Use analyze_ja4x + compare_fingerprints to link infrastructure

5. Zero-Day Response

Scenario: New exploit targeting specific TLS configurations
Pattern detection on observed fingerprints

Use detect_patterns to identify affected client population

Database Management

The server automatically:

Downloads the JA4DB database on first run
Caches ja4db.json locally in XDG cache dir
Refreshes every 24 hours
Can be manually refreshed with refresh_database tool

Database source: https://ja4db.com/api/read/

Understanding the Output

Database Matches

verified: true - Community-verified fingerprint
observation_count - How many times observed globally
Multiple matches indicate fingerprint collision (same config, different apps)

Pattern Analysis

Outliers: Unique fingerprints that don’t cluster
Cipher groups: Fingerprints sharing cipher selection (part_b)
Protocol configs: Fingerprints with identical metadata (part_a)

Available Resources

The JA4 MCP Server exposes resources for direct access to fingerprint databases and reference documentation through custom URI schemes:

Database Resources

`ja4-database://fingerprints`

Complete database of known JA4 fingerprints with applications and OS information. Returns JSON array of all fingerprint records.

`ja4-database://applications`

Applications grouped with their associated JA4 fingerprints. Returns JSON object with application names as keys and fingerprint arrays as values.

`ja4-database://operating-systems`

Operating system patterns found in JA4 fingerprints. Returns JSON object with OS names as keys and fingerprint arrays as values.

`ja4-database://statistics`

Statistics about the JA4 fingerprints database including total records, verified count, and unique applications/OS counts.

`ja4-database://verified`

Only verified JA4 fingerprints from the database. Returns filtered JSON array of high-confidence records.

Documentation Resources

`ja4-docs://protocols`

Reference for JA4 protocol codes (t=TCP, q=QUIC, d=DTLS) with full names and descriptions.

`ja4-docs://tls-versions`

TLS version mappings (10=TLS 1.0, 11=TLS 1.1, 12=TLS 1.2, 13=TLS 1.3) with security assessments.

`ja4-docs://tcp-options`

Complete reference for TCP options used in JA4T fingerprints with option codes and descriptions.

`ja4-docs://http-methods`

HTTP method codes used in JA4H fingerprints (ge=GET, po=POST, etc.).

`ja4-docs://alpn-protocols`

Application-Layer Protocol Negotiation codes and their corresponding protocols.

Resource Usage

Resources provide direct data access without tool execution overhead:

// Access database statistics
const stats = await readResource("ja4-database://statistics");
console.log(JSON.parse(stats.contents[0].text));

// Get protocol reference
const protocols = await readResource("ja4-docs://protocols");
console.log(JSON.parse(protocols.contents[0].text));

All resources include annotations for audience (["user", "assistant"]) and priority levels (0.0-1.0) to help clients determine relevance.

Integration Examples

With SIEM/SOAR

// Enrich alert with JA4 analysis
const alert = { ja4: "t13d1516h2_8daaf6152771_02713d6af862", src_ip: "192.168.1.100" };
const analysis = await analyze_ja4({ fingerprint: alert.ja4 });
const tips = await get_investigation_tips({ fingerprint: alert.ja4 });

// Add to ticket/case

With Network Security Tools

// Analyze PCAP-extracted fingerprints
const fingerprints = extractFromPCAP("capture.pcap");
const patterns = await detect_patterns({ fingerprints });

// Identify campaigns

With Threat Intelligence Platforms

// Check against known bad
const ioc = "t13d190900_9dc949149365_97f8aa674fd9"; // Sliver malware
const analysis = await analyze_ja4({ fingerprint: ioc });
// Match = Sliver C2 traffic

Performance

Database: ~10-50MB (thousands of fingerprint sets)
Analysis: <10ms per fingerprint (in-memory operations)
Database lookup: <50ms (indexed search)
Pattern detection: O(n) where n = fingerprint count

Troubleshooting

Database Download Fails

# Manual download
curl https://ja4db.com/api/read/ -o ja4db.json

# Check network/firewall for HTTPS to ja4db.com

Invalid Fingerprint Format

Error: Invalid JA4 fingerprint format. Expected format: a_b_c

Solution: Verify fingerprint has correct structure (underscores, part lengths)
Example valid: t13d1516h2_8daaf6152771_02713d6af862

Memory Issues (Large Datasets)

// Use streaming or batch processing for >10,000 fingerprints
const batches = chunkArray(fingerprints, 100);
for (const batch of batches) {
  await detect_patterns({ fingerprints: batch });
}

Resources

JA4+ Specification: https://github.com/FoxIO-LLC/ja4
JA4+ Database: https://ja4db.com/
Technical Details: https://github.com/FoxIO-LLC/ja4/tree/main/technical_details
FoxIO Blog: https://blog.foxio.io/ja4+-network-fingerprinting
Hunt.io Guide: https://hunt.io/glossary/ja4-fingerprinting

Licensing

This MCP server: See LICENSE.md

JA4+ Methods:

JA4 (TLS Client): BSD 3-Clause (open source)
JA4S/H/X/SSH/T: FoxIO License 1.1 (permissive for internal use, not for commercialization)

See: https://github.com/FoxIO-LLC/ja4/blob/main/LICENSE-JA4 and https://github.com/FoxIO-LLC/ja4/blob/main/LICENSE

Contributing

This is a community tool for analyzing JA4+ fingerprints. Contributions welcome:

Additional analysis features
Enhanced threat detection logic
Integration examples
Documentation improvements
Addtional prompts/resources

Support

For issues with:

This MCP server: Open an issue
JA4+ specification: https://github.com/FoxIO-LLC/ja4
JA4DB database: https://docs.ja4db.com/

Acknowledgments

John Althouse and the FoxIO team for creating JA4+
The ja4db.com community for maintaining the fingerprint database
The MCP community for the protocol specification