ja4plus 0.2.0__py3-none-any.whl

ja4plus/__init__.py

@@ -0,0 +1,30 @@
+"""
+JA4+ - Network Fingerprinting Library
+
+A Python implementation of the JA4+ network fingerprinting methods
+created by FoxIO LLC. Supports TLS, TCP, HTTP, SSH, and X.509
+fingerprinting for network security monitoring and traffic analysis.
+"""
+
+from ja4plus.fingerprinters.ja4 import JA4Fingerprinter
+from ja4plus.fingerprinters.ja4s import JA4SFingerprinter
+from ja4plus.fingerprinters.ja4h import JA4HFingerprinter
+from ja4plus.fingerprinters.ja4l import JA4LFingerprinter
+from ja4plus.fingerprinters.ja4x import JA4XFingerprinter
+from ja4plus.fingerprinters.ja4ssh import JA4SSHFingerprinter
+from ja4plus.fingerprinters.ja4t import JA4TFingerprinter
+from ja4plus.fingerprinters.ja4ts import JA4TSFingerprinter
+
+# Function-based API
+from ja4plus.fingerprinters.ja4 import generate_ja4
+from ja4plus.fingerprinters.ja4s import generate_ja4s
+from ja4plus.fingerprinters.ja4h import generate_ja4h
+from ja4plus.fingerprinters.ja4l import generate_ja4l
+from ja4plus.fingerprinters.ja4x import generate_ja4x
+from ja4plus.fingerprinters.ja4ssh import generate_ja4ssh
+from ja4plus.fingerprinters.ja4t import generate_ja4t
+from ja4plus.fingerprinters.ja4ts import generate_ja4ts
+
+__version__ = "0.2.0"
+__author__ = "ja4plus contributors"
+__license__ = "BSD-3-Clause"

ja4plus/collector.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+JA4+ collector for Elastic Agent integration.
+Captures network traffic and outputs JA4+ fingerprints as JSON.
+"""
+
+import argparse
+import json
+import sys
+import time
+import signal
+from scapy.all import sniff
+
+from ja4plus.fingerprinters.ja4 import JA4Fingerprinter
+from ja4plus.fingerprinters.ja4s import JA4SFingerprinter
+from ja4plus.fingerprinters.ja4h import JA4HFingerprinter
+from ja4plus.fingerprinters.ja4t import JA4TFingerprinter
+from ja4plus.fingerprinters.ja4ts import JA4TSFingerprinter
+from ja4plus.fingerprinters.ja4x import JA4XFingerprinter
+from ja4plus.fingerprinters.ja4ssh import JA4SSHFingerprinter
+
+# Global variables for signal handling
+packet_count = 0
+max_packets = 0
+start_time = 0
+timeout_seconds = 0
+
+def signal_handler(signum, frame):
+    """Handle termination signals gracefully"""
+    sys.stderr.write("Received signal, shutting down gracefully...\n")
+    sys.exit(0)
+
+def main():
+    """Main collector function"""
+    global packet_count, max_packets, start_time, timeout_seconds
+
+    parser = argparse.ArgumentParser(description="JA4+ Network Fingerprinting Collector")
+    parser.add_argument("--interface", "-i", default="any", help="Network interface to capture on")
+    parser.add_argument("--filter", "-f", default="tcp or udp", help="BPF filter expression")
+    parser.add_argument("--fingerprinters", default="ja4,ja4s,ja4h,ja4t,ja4ts,ja4x,ja4ssh",
+                       help="Comma-separated list of fingerprinters to enable")
+    parser.add_argument("--max-packets", type=int, default=0,
+                       help="Maximum packets to process (0 = unlimited)")
+    parser.add_argument("--timeout", type=float, default=0,
+                       help="Timeout in seconds (0 = no timeout)")
+    parser.add_argument("--output", choices=["json", "text"], default="json",
+                       help="Output format")
+
+    args = parser.parse_args()
+
+    # Set up signal handlers
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    # Initialize global variables
+    max_packets = args.max_packets
+    timeout_seconds = args.timeout
+    start_time = time.time()
+
+    # Initialize enabled fingerprinters
+    available_fingerprinters = {
+        "ja4": JA4Fingerprinter(),
+        "ja4s": JA4SFingerprinter(),
+        "ja4h": JA4HFingerprinter(),
+        "ja4t": JA4TFingerprinter(),
+        "ja4ts": JA4TSFingerprinter(),
+        "ja4x": JA4XFingerprinter(),
+        "ja4ssh": JA4SSHFingerprinter()
+    }
+
+    enabled_fps = args.fingerprinters.split(",")
+    fingerprinters = {}
+    for name in enabled_fps:
+        name = name.strip()
+        if name in available_fingerprinters:
+            fingerprinters[name] = available_fingerprinters[name]
+        else:
+            sys.stderr.write(f"Warning: Unknown fingerprinter '{name}'\n")
+
+    if not fingerprinters:
+        sys.stderr.write("Error: No valid fingerprinters enabled\n")
+        sys.exit(1)
+
+    def process_packet(packet):
+        """Process packet with enabled fingerprinters and output results"""
+        global packet_count
+
+        # Check packet limit
+        if max_packets > 0 and packet_count >= max_packets:
+            return
+
+        # Check timeout
+        if timeout_seconds > 0 and (time.time() - start_time) >= timeout_seconds:
+            return
+
+        packet_count += 1
+
+        results = {
+            "@timestamp": int(time.time() * 1000),  # Elasticsearch expects milliseconds
+            "ja4plus": {}
+        }
+
+        # Apply each enabled fingerprinter
+        for name, fp in fingerprinters.items():
+            try:
+                fingerprint = fp.process_packet(packet)
+                if fingerprint:
+                    results["ja4plus"][name] = fingerprint
+            except Exception as e:
+                sys.stderr.write(f"Error in {name} fingerprinter: {e}\n")
+
+        # Only output if we have fingerprints
+        if results["ja4plus"]:
+            # Add network metadata - properly extract IP addresses
+            try:
+                from scapy.all import IP, IPv6
+
+                # Look for IP layer (IPv4 or IPv6)
+                if packet.haslayer(IP):
+                    ip_layer = packet[IP]
+                    results["source"] = {"ip": ip_layer.src}
+                    results["destination"] = {"ip": ip_layer.dst}
+                elif packet.haslayer(IPv6):
+                    ip_layer = packet[IPv6]
+                    results["source"] = {"ip": ip_layer.src}
+                    results["destination"] = {"ip": ip_layer.dst}
+                elif hasattr(packet, "src") and hasattr(packet, "dst"):
+                    # Fallback to packet-level src/dst (might be MAC addresses)
+                    # Only use if they look like IP addresses
+                    src_str = str(packet.src)
+                    dst_str = str(packet.dst)
+                    if ":" not in src_str or len(src_str.split(":")) <= 4:  # Not a MAC address
+                        results["source"] = {"ip": src_str}
+                        results["destination"] = {"ip": dst_str}
+
+                # Add port information if available
+                from scapy.all import TCP, UDP
+                if packet.haslayer(TCP):
+                    tcp_layer = packet[TCP]
+                    if "source" in results:
+                        results["source"]["port"] = tcp_layer.sport
+                    if "destination" in results:
+                        results["destination"]["port"] = tcp_layer.dport
+                elif packet.haslayer(UDP):
+                    udp_layer = packet[UDP]
+                    if "source" in results:
+                        results["source"]["port"] = udp_layer.sport
+                    if "destination" in results:
+                        results["destination"]["port"] = udp_layer.dport
+
+            except Exception as e:
+                sys.stderr.write(f"Error extracting network metadata: {e}\n")
+
+            # Add collection metadata
+            results["ja4plus"]["interface"] = args.interface
+            results["ja4plus"]["filter"] = args.filter
+            results["ja4plus"]["collection_timestamp"] = int(time.time() * 1000)
+
+            # Output based on format
+            if args.output == "json":
+                print(json.dumps(results))
+            else:
+                print(f"Packet {packet_count}: {results}")
+
+            sys.stdout.flush()
+
+        # Stop if we've reached the packet limit
+        if max_packets > 0 and packet_count >= max_packets:
+            sys.stderr.write(f"Reached packet limit of {max_packets}, stopping...\n")
+            sys.exit(0)
+
+        # Stop if we've reached the timeout
+        if timeout_seconds > 0 and (time.time() - start_time) >= timeout_seconds:
+            sys.stderr.write(f"Reached timeout of {timeout_seconds} seconds, stopping...\n")
+            sys.exit(0)
+
+    try:
+        sys.stderr.write(f"Starting JA4+ collection on interface '{args.interface}' with filter '{args.filter}'\n")
+        sys.stderr.write(f"Enabled fingerprinters: {', '.join(fingerprinters.keys())}\n")
+
+        # Start sniffing
+        sniff(prn=process_packet,
+              filter=args.filter,
+              iface=args.interface if args.interface != "any" else None,
+              store=0)
+
+    except KeyboardInterrupt:
+        sys.stderr.write("Interrupted by user\n")
+    except Exception as e:
+        sys.stderr.write(f"Error during packet capture: {e}\n")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

ja4plus/fingerprinters/__init__.py

@@ -0,0 +1,23 @@
+"""
+JA4+ fingerprinters for various protocols and traffic types.
+"""
+
+from .ja4 import JA4Fingerprinter
+from .ja4s import JA4SFingerprinter
+from .ja4h import JA4HFingerprinter
+from .ja4l import JA4LFingerprinter
+from .ja4x import JA4XFingerprinter
+from .ja4ssh import JA4SSHFingerprinter
+from .ja4t import JA4TFingerprinter
+from .ja4ts import JA4TSFingerprinter
+
+__all__ = [
+    'JA4Fingerprinter',
+    'JA4SFingerprinter',
+    'JA4HFingerprinter',
+    'JA4LFingerprinter',
+    'JA4XFingerprinter',
+    'JA4SSHFingerprinter',
+    'JA4TFingerprinter',
+    'JA4TSFingerprinter'
+] 

ja4plus/fingerprinters/base.py

@@ -0,0 +1,44 @@
+"""
+Base fingerprinter class for JA4+ fingerprinters.
+"""
+
+class BaseFingerprinter:
+    """Base class for all JA4+ fingerprinters."""
+    
+    def __init__(self):
+        """Initialize the fingerprinter."""
+        self.fingerprints = []
+    
+    def process_packet(self, packet):
+        """
+        Process a packet and extract fingerprint if applicable.
+        This method should be overridden by subclasses.
+        
+        Args:
+            packet: A network packet to analyze
+            
+        Returns:
+            The extracted fingerprint if successful, None otherwise
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+    
+    def add_fingerprint(self, fingerprint, packet):
+        """
+        Add a fingerprint to the collection.
+        
+        Args:
+            fingerprint: The extracted fingerprint
+            packet: The packet that generated this fingerprint
+        """
+        self.fingerprints.append({
+            'fingerprint': fingerprint,
+            'packet': packet
+        })
+    
+    def get_fingerprints(self):
+        """Return all collected fingerprints."""
+        return self.fingerprints
+    
+    def reset(self):
+        """Reset the fingerprinter state."""
+        self.fingerprints = [] 

ja4plus/fingerprinters/ja4.py

@@ -0,0 +1,284 @@
+"""
+JA4 TLS Client Hello Fingerprinting implementation.
+"""
+
+import hashlib
+from scapy.all import TCP, UDP, Raw, IP
+from ja4plus.utils.tls_utils import extract_tls_info, is_grease_value
+from ja4plus.fingerprinters.base import BaseFingerprinter
+
+def generate_ja4(tls_info):
+    """
+    Generate a JA4 fingerprint from TLS Client Hello info.
+    
+    Args:
+        tls_info: A dictionary with TLS handshake information
+        
+    Returns:
+        A JA4 fingerprint string or None if not applicable
+    """
+    if not tls_info or tls_info.get('type') != 'client_hello':
+        return None
+        
+    try:
+        # Determine protocol type (q=QUIC, d=DTLS, t=TLS over TCP)
+        proto = 'q' if tls_info.get('is_quic') else 'd' if tls_info.get('is_dtls') else 't'
+        
+        # Get TLS version - prioritize supported_versions extension (0x002b)
+        version = tls_info.get('version')
+        supported_versions = tls_info.get('supported_versions', [])
+        
+        # Filter out GREASE values
+        supported_versions = [v for v in supported_versions if not is_grease_value(v)]
+        
+        if supported_versions:
+            # Use highest supported version
+            version = max(supported_versions)
+        
+        # Convert version to string format
+        if version == 0x0304:  # TLS 1.3
+            version_str = '13'
+        elif version == 0x0303:  # TLS 1.2
+            version_str = '12'
+        elif version == 0x0302:  # TLS 1.1
+            version_str = '11'
+        elif version == 0x0301:  # TLS 1.0
+            version_str = '10'
+        elif version == 0x0300:  # SSL 3.0
+            version_str = 's3'
+        elif version == 0x0200:  # SSL 2.0
+            version_str = 's2'
+        elif version == 0xfeff:  # DTLS 1.0
+            version_str = 'd1'
+        elif version == 0xfefd:  # DTLS 1.2
+            version_str = 'd2'
+        elif version == 0xfefc:  # DTLS 1.3
+            version_str = 'd3'
+        else:
+            version_str = '00'
+            
+        # SNI type - 'd' if SNI exists, 'i' if not
+        sni = tls_info.get('sni')
+        sni_type = 'd' if sni else 'i'
+        
+        # Get cipher suites - filter out GREASE values
+        ciphers = [c for c in tls_info.get('ciphers', []) if not is_grease_value(c)]
+        cipher_count = min(len(ciphers), 99)  # Cap at 99
+        cipher_count_str = f"{cipher_count:02d}"
+        
+        # Get extensions - filter out GREASE values
+        extensions = [e for e in tls_info.get('extensions', []) if not is_grease_value(e)]
+        ext_count = min(len(extensions), 99)  # Cap at 99
+        ext_count_str = f"{ext_count:02d}"
+        
+        # Get ALPN value - extract first and last character
+        # Per FoxIO spec: first+last alphanumeric char of first ALPN protocol
+        # Non-ASCII (ord > 127) -> '99'
+        alpn_protocols = tls_info.get('alpn_protocols', [])
+        if not alpn_protocols:
+            alpn_value = '00'
+        else:
+            first_alpn = alpn_protocols[0]
+
+            if not first_alpn:
+                alpn_value = '00'
+            else:
+                # FoxIO spec: if first char is non-ASCII, use '99'
+                if ord(first_alpn[0]) > 127:
+                    alpn_value = '99'
+                elif len(first_alpn) == 1:
+                    alpn_value = first_alpn[0] + first_alpn[0]
+                else:
+                    alpn_value = f"{first_alpn[0]}{first_alpn[-1]}"
+        
+        # Form part_a of the fingerprint
+        part_a = f"{proto}{version_str}{sni_type}{cipher_count_str}{ext_count_str}{alpn_value}"
+        
+        # Generate cipher hash - sort ciphers first
+        if ciphers:
+            sorted_ciphers = sorted(ciphers)
+            cipher_str = ','.join([f"{c:04x}" for c in sorted_ciphers])
+            cipher_hash = hashlib.sha256(cipher_str.encode()).hexdigest()[:12]
+        else:
+            cipher_hash = '000000000000'
+        
+        # Generate extension hash
+        # 1. Remove SNI (0x0000) and ALPN (0x0010) from extensions for hashing
+        filtered_extensions = [e for e in extensions if e != 0x0000 and e != 0x0010]
+        
+        # 2. Sort filtered extensions
+        sorted_extensions = sorted(filtered_extensions)
+        
+        # 3. Get signature algorithms in original order
+        sig_algs = tls_info.get('signature_algorithms', [])
+        
+        # 4. Form extension string - sorted extensions + underscore + sig algorithms if present
+        ext_str = ','.join([f"{e:04x}" for e in sorted_extensions])
+        if sig_algs:
+            sig_alg_str = ','.join([f"{s:04x}" for s in sig_algs])
+            ext_str = f"{ext_str}_{sig_alg_str}"
+            
+        # 5. Generate extension hash
+        if ext_str:
+            ext_hash = hashlib.sha256(ext_str.encode()).hexdigest()[:12]
+        else:
+            ext_hash = '000000000000'
+        
+        # Form the complete JA4 fingerprint
+        ja4 = f"{part_a}_{cipher_hash}_{ext_hash}"
+        
+        return ja4
+        
+    except Exception:
+        return None
+
+def get_raw_fingerprint(tls_info, original_order=False):
+    """
+    Generate a raw JA4 fingerprint with all values visible.
+    
+    Args:
+        tls_info: A dictionary with TLS handshake information
+        original_order: Whether to maintain original ordering (True) or sort (False)
+        
+    Returns:
+        A raw JA4 fingerprint string or None if not applicable
+    """
+    if not tls_info or tls_info.get('type') != 'client_hello':
+        return None
+        
+    try:
+        # Get the same components as in generate_ja4
+        proto = 'q' if tls_info.get('is_quic') else 'd' if tls_info.get('is_dtls') else 't'
+        
+        # Version
+        version = tls_info.get('version')
+        supported_versions = tls_info.get('supported_versions', [])
+        supported_versions = [v for v in supported_versions if not is_grease_value(v)]
+        
+        if supported_versions:
+            version = max(supported_versions)
+            
+        # Map version to string format (same as in generate_ja4)
+        if version == 0x0304:  # TLS 1.3
+            version_str = '13'
+        elif version == 0x0303:  # TLS 1.2
+            version_str = '12'
+        elif version == 0x0302:  # TLS 1.1
+            version_str = '11'
+        elif version == 0x0301:  # TLS 1.0
+            version_str = '10'
+        elif version == 0x0300:  # SSL 3.0
+            version_str = 's3'
+        elif version == 0x0200:  # SSL 2.0
+            version_str = 's2'
+        elif version == 0xfeff:  # DTLS 1.0
+            version_str = 'd1'
+        elif version == 0xfefd:  # DTLS 1.2
+            version_str = 'd2'
+        elif version == 0xfefc:  # DTLS 1.3
+            version_str = 'd3'
+        else:
+            version_str = '00'
+            
+        # SNI
+        sni = tls_info.get('sni')
+        sni_type = 'd' if sni else 'i'
+        
+        # Ciphers - filter GREASE
+        ciphers = [c for c in tls_info.get('ciphers', []) if not is_grease_value(c)]
+        cipher_count = min(len(ciphers), 99)
+        cipher_count_str = f"{cipher_count:02d}"
+        
+        # Extensions - filter GREASE
+        extensions = [e for e in tls_info.get('extensions', []) if not is_grease_value(e)]
+        ext_count = min(len(extensions), 99)
+        ext_count_str = f"{ext_count:02d}"
+        
+        # ALPN - same as in generate_ja4
+        alpn_protocols = tls_info.get('alpn_protocols', [])
+        if not alpn_protocols:
+            alpn_value = '00'
+        else:
+            first_alpn = alpn_protocols[0]
+
+            if not first_alpn:
+                alpn_value = '00'
+            elif ord(first_alpn[0]) > 127:
+                alpn_value = '99'
+            elif len(first_alpn) == 1:
+                alpn_value = first_alpn[0] + first_alpn[0]
+            else:
+                alpn_value = f"{first_alpn[0]}{first_alpn[-1]}"
+        
+        # First part of fingerprint
+        part_a = f"{proto}{version_str}{sni_type}{cipher_count_str}{ext_count_str}{alpn_value}"
+        
+        # Cipher list - either sorted or original
+        if original_order:
+            cipher_list = ','.join([f"{c:04x}" for c in tls_info.get('ciphers', []) if not is_grease_value(c)])
+        else:
+            cipher_list = ','.join([f"{c:04x}" for c in sorted(ciphers)])
+        
+        # Extension list - either with or without SNI/ALPN based on original_order
+        if original_order:
+            ext_list = ','.join([f"{e:04x}" for e in tls_info.get('extensions', []) if not is_grease_value(e)])
+        else:
+            ext_list = ','.join([f"{e:04x}" for e in sorted([e for e in extensions if e != 0x0000 and e != 0x0010])])
+        
+        # Signature algorithms
+        sig_algs = tls_info.get('signature_algorithms', [])
+        sig_alg_list = ','.join([f"{s:04x}" for s in sig_algs])
+        
+        # Final format
+        if sig_algs:
+            if original_order:
+                raw_ja4 = f"{part_a}_{cipher_list}_{ext_list}_{sig_alg_list}"
+            else:
+                raw_ja4 = f"{part_a}_{cipher_list}_{ext_list}_{sig_alg_list}"
+        else:
+            raw_ja4 = f"{part_a}_{cipher_list}_{ext_list}"
+        
+        # Add suffix to indicate format
+        if original_order:
+            return f"JA4_ro = {raw_ja4}"
+        else:
+            return f"JA4_r = {raw_ja4}"
+            
+    except Exception:
+        return None
+
+class JA4Fingerprinter(BaseFingerprinter):
+    """Fingerprinter for JA4 (TLS Client Hello)."""
+    
+    def process_packet(self, packet):
+        """Process a packet and extract JA4 fingerprint if applicable."""
+        # First extract TLS info from the packet
+        tls_info = extract_tls_info(packet)
+        
+        if not tls_info:
+            return None
+        
+        # Then generate JA4 from the extracted TLS info
+        fingerprint = generate_ja4(tls_info)
+        
+        if fingerprint:
+            self.add_fingerprint(fingerprint, packet)
+        
+        return fingerprint
+        
+    def get_raw_fingerprint(self, packet, original_order=False):
+        """
+        Get raw JA4 fingerprint with visible components.
+        
+        Args:
+            packet: A packet containing a TLS Client Hello
+            original_order: Whether to maintain original ordering
+            
+        Returns:
+            Raw JA4 fingerprint string or None
+        """
+        tls_info = extract_tls_info(packet)
+        if not tls_info:
+            return None
+            
+        return get_raw_fingerprint(tls_info, original_order)