batman

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

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:

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